claim_exposures

Code
Adds a recovery transaction to a claim or exposure.

Request Payload
---------------
recovery_details : dict
    {
        "api_key": str,
        "recovery_details": {
            "exposure_id": str | null if claim_id is provided
            "claim_id": str | null if exposure_id is provided
            "category": str,
            "amount": number,
            "description": str,
            "date": str (date "YYYY-MM-DD", stored as-is, or date-time,
                   whose America/Chicago calendar day is stored)
        }
    }

Returns
-------
success : bool
    True if successful, false otherwise.
messages : list of str | dict
    List of human-readable error or success messages.
data : dict
    {
        "amount": number,
        "category": str,
        "claim_id": str | null if exposure_id is provided
        "date": str (date),
        "description": str,
        "exposure_id": str | null if claim_id is provided
        "id": str,
        "reinsuranceContractContactId": str | null
    }

Code
Adds a recovery reserve to a claim or exposure.

Request Payload
---------------
recovery_reserve_details : dict
    {
        "api_key": str,
        "recovery_reserve_details": {
            "exposure_id": str | null,
            "claim_id": str | null,
            "reinsurance_amount": number,
            "reinsurancelae_amount": number,
            "salvage_amount": number,
            "subrogation_amount": number,
            "transaction_date": str (date "YYYY-MM-DD", stored as-is, or date-time,
                   whose America/Chicago calendar day is stored)
        }
    }

Returns
-------
success : bool
    True if successful, false otherwise.
messages : list of str | dict
    List of human-readable error or success messages.
data : dict
    {
        "claim_id": str | null,
        "exposure_id": str | null,
        "reinsurance_amount": number,
        "reinsurancelae_amount": number,
        "salvage_amount": number,
        "subrogation_amount": number,
        "transaction_date": str (date)
    }

Code
Add or update reserve values for an exposure.

Request Payload
---------------
reserve_details : dict
    {
        "exposure_id": str,
        "loss_amount": number,
        "adjusting_amount": number,
        "legal_amount": number,
        "transaction_date": str (date "YYYY-MM-DD", stored as-is, or date-time,
               whose America/Chicago calendar day is stored; defaults to the
               current date when omitted. It must be on or after the newest
               Losses Incurred entry on the claim, otherwise the change is rejected)
    }

Returns
-------
dict
    On success, the reserve values (``validate_data`` / ``warning``
    envelope fields are added by the decorator)::

        {
            "exposure_id": str,
            "loss_amount": number,
            "adjusting_amount": number,
            "legal_amount": number,
            "transaction_date": "YYYY-MM-DD"
        }

    If authority limits are exceeded::

        {"brokenLimits": [...], "adminData": {...}}

Code
Create a claim exposure record.

Request Payload
---------------
claim_exposure : dict
    {
        "claim_id": str,
        "coverage_id": str,
        "loss_type": "property" | "vehicle" | "injury",   # optional but recommended
        "loss_id": str,                                    # optional
        "claimant_id": str,                                # optional
        "representative": {                                # optional
            "contact_id": str,
            "start_date": "YYYY-MM-DD"
        }
    }

Returns
-------
dict
    {
        "id": str,
        "claim_id": str,
        "coverage_id": str,
        "coverage_type_id": str,
        "loss_id": str,
        "loss_type": "property" | "vehicle" | "injury",
        "claimant_id": str,
        "representative": {
            "contact_id": str,
            "start_date": "YYYY-MM-DD",
            "name": str
        },
        "loss": {"id": str, "name": str},
        "coverage": {"id": str, "name": str, "deductible": number, ...},
        "claimant": {"id": str, "name": str, "type": str, ...},
        "coverage_deductible": number,
        "override": bool,
        "is_borrowed": bool,
        "date_updated": str (datetime),
        "is_liability": bool
    }

Notes
-----
- ``claim_id`` and ``coverage_id`` are required by service validation.
- Duplicate exposures (same claimant + coverage + claim + loss) are rejected.

Code
Delete a claim exposure by ID.

Parameters
----------
id : str
    Exposure ID.

Returns
-------
None
    Successful deletion returns an empty standard API response.

Code
Retrieve accounting summary for all exposures on a claim.

Parameters
----------
claim_id : str
    Claim ID.

Returns
-------
dict
    {
        "exposure_summaries": [<exposure_accounting_summary>, ...],
        "summary": <exposure_accounting_summary>
    }

    Each ``<exposure_accounting_summary>`` has the shape documented in
    ``get_exposure_accounting_data``.

Code
Retrieves detailed loss accounting data for a claim, including exposure-level
and total loss details. Provides comprehensive breakdown of loss, legal, and
adjusting reserves and payments for financial analysis and reporting.
Uses pagination for exposure data.

Permissions
-----------
Requires read access to at least one of:
    - 'britecore/claims/exposures'
    - 'britecore/claims/accounting'
    - 'agent/claims'

Parameters
----------
claim_id : str
    The ID of the claim for which to retrieve loss details.
page : int, optional
    The page number for paginated exposures (default: 1).
page_size : int, optional
    The number of exposures per page (default: 100).

Returns
-------
dict
    {
        'exposure_loss_details': [
            {
                'id': str,                    # Exposure/claim item UUID
                'claimant_name': str|null,    # Name of the claimant
                'coverage_name': str,         # Insurance coverage name
                'loss_name': str,             # Description of the loss/damage
                'loss_details': {
                    'loss_reserve': float,        # Current loss reserve amount
                    'loss_paid': float,           # Loss payments, net of return payments
                    'loss_gross_paid': float,     # Loss payments before return payments
                    'loss_returned': float,       # Loss amount given back by return payments
                    'legal_reserve': float,       # Current legal reserve amount
                    'legal_paid': float,          # Legal payments, net of return payments
                    'legal_gross_paid': float,    # Legal payments before return payments
                    'legal_returned': float,      # Legal amount given back by return payments
                    'adjusting_reserve': float,   # Current adjusting reserve amount
                    'adjusting_paid': float,      # Adjusting payments, net of return payments
                    'adjusting_gross_paid': float,  # Adjusting payments before return payments
                    'adjusting_returned': float   # Adjusting amount given back by return payments
                }
            },
            ...
        ],
        'total_loss_details': {
            'loss_reserve': float,        # Sum of all exposure loss reserves
            'loss_paid': float,           # Exposure loss payments, net of return payments
            'loss_gross_paid': float,     # Exposure loss payments before return payments
            'loss_returned': float,       # Loss amount given back by return payments
            'legal_reserve': float,       # Sum of all exposure legal reserves
            'legal_paid': float,          # Exposure legal payments, net of return payments
            'legal_gross_paid': float,    # Exposure legal payments before return payments
            'legal_returned': float,      # Legal amount given back by return payments
            'adjusting_reserve': float,   # Sum of all exposure adjusting reserves
            'adjusting_paid': float,      # Exposure adjusting payments, net of return payments
            'adjusting_gross_paid': float,  # Exposure adjusting payments before return payments
            'adjusting_returned': float   # Adjusting amount given back by return payments
        },
        'total_records': int            # Total number of exposures for pagination
    }

Code
Retrieves comprehensive accounting overview data for a claim,
including claim-level overview, exposure-level overviews, and total summaries.
This endpoint provides financial data for reserves, payments, incurred amounts,
recoveries, and net incurred calculations. Uses pagination for exposure data.

Permissions
-----------
Requires read access to at least one of:
    - 'britecore/claims/exposures'
    - 'britecore/claims/accounting'
    - 'agent/claims'

Parameters
----------
claim_id : str
    The ID of the claim for which to retrieve accounting overview data.
page : int, optional
    The page number for paginated exposures (default: 1).
page_size : int, optional
    The number of exposures per page (default: 100).

Returns
-------
dict
    {
        'claim_level_overview': {
            'total_reserve': float,      # Always 0.0 at claim level
            'total_payment': float,      # Always 0.0 at claim level
            'gross_payment': float,      # Always 0.0 at claim level
            'total_returned': float,     # Always 0.0 at claim level
            'total_incurred': float,     # Always 0.0 at claim level
            'total_recovery': float,     # Sum of all recovery reserves + recovered amounts
            'net_incurred': float        # total_incurred - total_recovery (always negative)
        },
        'exposure_level_overview': [
            {
                'id': str,                    # Exposure/claim item UUID
                'claimant_name': str|null,    # Name of the claimant
                'coverage_name': str,         # Insurance coverage name
                'loss_name': str,             # Description of the loss/damage
                'overview': {
                    'total_reserve': float,    # Sum of loss, legal, and adjusting reserves
                    'total_payment': float,    # Payments net of return payments
                    'gross_payment': float,    # Payments before return payments
                    'total_returned': float,   # Given back by return payments
                    'total_incurred': float,   # total_reserve + total_payment
                    'total_recovery': float,   # Sum of recovery reserves + recovered amounts
                    'net_incurred': float      # total_incurred - total_recovery
                }
            },
            ...
        ],
        'total_overview': {
            'total_reserve': float,      # Sum of all exposure reserves
            'total_payment': float,      # Exposure payments net of return payments
            'gross_payment': float,      # Exposure payments before return payments
            'total_returned': float,     # Given back by return payments
            'total_incurred': float,     # total_reserve + total_payment
            'total_recovery': float,     # Sum of all recovery data (claim + exposure level)
            'net_incurred': float        # total_incurred - total_recovery
        },
        'total_records': int            # Total number of exposures for pagination
    }

Code
Retrieves accounting recoveries summary data for a claim,
including claim-level, exposure-level recoveries and total recoveries.
This endpoint uses pagination to return the data.

Permissions
-----------
Requires read access to at least one of:
    - 'britecore/claims/exposures'
    - 'britecore/claims/accounting'
    - 'agent/claims'

Parameters
----------
claim_id : str
    The ID of the claim for which to retrieve recoveries data.
page : int, optional
    The page number for paginated exposures (default: 1).
page_size : int, optional
    The number of exposures per page (default: 100).

Returns
-------
dict
    {
        'claim_level_recoveries': {
            'reinsurance_summary': {
                'total_recovery_reserve': Decimal,
                'total_recovered': Decimal
            },
            'reinsurancelae_summary': {
                'total_recovery_reserve': Decimal,
                'total_recovered': Decimal
            },
            'salvage_summary': {
                'total_recovery_reserve': Decimal,
                'total_recovered': Decimal
            },
            'subrogation_summary': {
                'total_recovery_reserve': Decimal,
                'total_recovered': Decimal
            }
        },
        'exposure_level_recoveries': [
            {
                'id': str,
                'claimant_name': str,
                'coverage_name': str,
                'loss_name': str,
                'recoveries': {
                    'reinsurance_summary': {
                        'total_recovery_reserve': Decimal,
                        'total_recovered': Decimal
                    },
                    'reinsurancelae_summary': {
                        'total_recovery_reserve': Decimal,
                        'total_recovered': Decimal
                    },
                    'salvage_summary': {
                        'total_recovery_reserve': Decimal,
                        'total_recovered': Decimal
                    },
                    'subrogation_summary': {
                        'total_recovery_reserve': Decimal,
                        'total_recovered': Decimal
                    }
                }
            },
            ...
        ],
        'total_recoveries': {
            'reinsurance_summary': {
                'total_recovery_reserve': Decimal,
                'total_recovered': Decimal
            },
            'reinsurancelae_summary': {
                'total_recovery_reserve': Decimal,
                'total_recovered': Decimal
            },
            'salvage_summary': {
                'total_recovery_reserve': Decimal,
                'total_recovered': Decimal
            },
            'subrogation_summary': {
                'total_recovery_reserve': Decimal,
                'total_recovered': Decimal
            }
        }
    }

get_broken_limits

Code
Retrieve claim accounting summary filtered to one coverage.

Parameters
----------
claim_id : str
    Claim ID.
coverage_id : str
    Coverage ID.

Returns
-------
dict
    Same shape as ``get_accounting_data`` (``exposure_summaries`` list +
    ``summary``), filtered to exposures matching *coverage_id*.

Code
Retrieve accounting summary for a single exposure.

Parameters
----------
exposure_id : str
    Exposure ID.

Returns
-------
dict
    Exposure accounting summary.  Reserve-category summaries (``loss_summary``,
    ``adjusting_summary``, ``legal_summary``) each contain::

        {"id", "reserve_category_type", "total_reserve", "total_payments",
         "gross_payments", "total_returned", "total_recovery", "total_incurred", "net_incurred"}

    ``total_payments`` is net of return payments; ``gross_payments`` is before them.

    Recovery-category summaries (``reinsurance_summary``,
    ``reinsurancelae_summary``, ``salvage_summary``,
    ``subrogation_summary``) each contain::

        {"id", "recovery_category_type", "total_recovery_reserve",
         "total_recovered", "total_recovery"}

    Top-level aggregates::

        {
            "id": str,
            "exposure": <exposure object>,
            "loss_summary": <reserve_category>,
            "adjusting_summary": <reserve_category>,
            "legal_summary": <reserve_category>,
            "reinsurance_summary": <recovery_category>,
            "reinsurancelae_summary": <recovery_category>,
            "salvage_summary": <recovery_category>,
            "subrogation_summary": <recovery_category>,
            "total_recovered": number,
            "total_recovery_reserve": number,
            "total_recovery": number,
            "total_reserve": number,
            "total_payments": number,
            "gross_payments": number,
            "total_returned": number,
            "total_incurred": number,
            "net_incurred": number
        }

Code
Returns whether an exposure is editable.

Code
Get transactions for an exposure with optional filtering and sorting.

This endpoint returns all accounting transactions for a specific exposure.
When no filter parameters are provided, returns all transactions sorted by
date (newest first).

Permissions
-----------
Requires read access to at least one of:
    - 'britecore/claims/accounting/transactions'
    - 'agent/claims'

Parameters
----------
exposure_id : str
    UUID of the exposure
transaction_types : str (optional)
    Filter by transaction type(s): reserve, payment, recovery, recovery_reserve
categories : List[str] (optional)
    Filter by category(ies): loss, adjuster, legal, reinsurance, subrogation,
    salvage, reinsurancelae
statuses : List[str] (optional)
    Filter by status(es): voided
payment_methods : List[str] (optional)
    Filter by payment method(s): NoAuth, CC, ACH
date_from : str (optional)
    Filter transactions on or after this date (YYYY-MM-DD format)
date_to : str (optional)
    Filter transactions on or before this date (YYYY-MM-DD format)
sort_by : str (optional, default: "transaction_datetime")
    Field to sort by: transaction_datetime, amount, payee, transaction_category
sort_order : str (optional, default: "desc")
    Sort order: asc, desc

Returns
-------
    List of serialized ClaimExposureAccountingTransactionWithExposureDetailsModel

Code
Retrieve a payment by its id (claim transaction id).

Parameters
----------
payment_id : str
    Claim transaction ID.

Returns
-------
dict
    Payment object (same shape as ``make_payment`` response).

Code
What a payment paid one exposure, what has been returned from it and what can still be returned.

Only callers with an explicit ``rw`` rule on exactly
``britecore/claims/accounting/returnPayments`` may read it.

Parameters
----------
payment_id : str
    Claim transaction ID of the payment.
exposure_id : str
    Exposure (claim item) the payment paid.

Returns
-------
dict
    Payment date, total and payees; this exposure's share, returned so far and remaining per
    bucket (loss, adjusting, legal); the system's today and the return reasons.

Raises
------
BCApiRequestPermissionDeniedError
    When the caller holds no exact grant.

Code
Describe a return payment and what voiding it would do, for the void dialog.

Parameters
----------
transaction_id : str
    Claim transaction ID of the return payment.

Returns
-------
dict
    The return's date, reason and amounts per bucket; the linked payment's return summary; per bucket
    the reserve the return restored, the current reserve and the change a void would make; whether the
    claim is closed or was closed since the return; and ``refusal`` when the reserve is now too low.
    Advisory: the void checks again under its locks.

Raises
------
BCApiRequestPermissionDeniedError
    When the caller holds no exact grant.

Code
The payments of an exposure that a return payment can be recorded against.

Lists the claim's non-voided positive payments dated up to today that paid this exposure, newest
first, each with this exposure's share, what has been returned from it and what can still be
returned per bucket. Fully returned payments are listed with nothing remaining. Needs the
``claims/enable-return-payments`` setting and an explicit ``rw`` rule on exactly
``britecore/claims/accounting/returnPayments``.

Parameters
----------
exposure_id : str
    Exposure (claim item) to list the payments of.

Returns
-------
dict
    ``payments``: one payment return summary per payment, as get_payment_return_summary returns it.

Raises
------
BCApiRequestPermissionDeniedError
    When the caller holds no exact grant.

Code
List all exposures for a claim.

Parameters
----------
claim_id : str
    Claim ID.

Returns
-------
list[dict]
    List of exposure objects.  Each element has the same shape as the
    ``create_exposure`` response (see its docstring for the full schema).

Code
Create a single payment distributed across multiple exposures.

Request Payload
---------------
payment_details : dict
    {
        "claim_id": str,
        "exposures": [
            {"id": str, "loss_paid": number, "adjusting_paid": number, "legal_paid": number}
        ],
        "payee_ids": [str, ...],
        "date": "YYYY-MM-DD",
        "display_on_check": str,
        "payment_method": str,
        "memo": str                         # optional
    }

Returns
-------
dict
    On success, the created multi-exposure payment::

        {
            "id": str,
            "claim_id": str,
            "exposures": [
                {"id": str, "loss_paid": number,
                 "adjusting_paid": number, "legal_paid": number}
            ],
            "payee_ids": [str, ...],
            "date": "YYYY-MM-DD",
            "display_on_check": str,
            "payment_method": str,
            "payment_classification": str,
            "address_id": str,
            "deductible_amount": number,
            "memo": str,
            "system_tags": dict,
            "amount": number
        }

    If authority limits are exceeded::

        {"brokenLimits": [...], "adminData": {...}}

Code
Create a payment transaction for an exposure.

Request Payload
---------------
payment_details : dict
    {
        "exposure_id": str,
        "payee_ids": [str, ...],
        "date": "YYYY-MM-DD",
        "display_on_check": str,
        "payment_method": str,
        "loss_paid": number,
        "adjusting_paid": number,
        "legal_paid": number,
        "deductible_amount": number,      # optional
        "memo": str,                      # optional
        "payment_classification": str,    # optional
        "address_id": str                 # optional
    }

Returns
-------
dict
    On success, the created payment::

        {
            "id": str,
            "exposure_id": str,
            "payee_ids": [str, ...],
            "date": "YYYY-MM-DD",
            "display_on_check": str,
            "payment_method": str,
            "payment_classification": str,
            "address_id": str,
            "loss_paid": number,
            "adjusting_paid": number,
            "legal_paid": number,
            "deductible_amount": number,
            "memo": str,
            "system_tags": dict,
            "amount": number
        }

    If authority limits are exceeded::

        {"brokenLimits": [...], "adminData": {...}}

Code
Record money returned against one exposure's share of a payment.

The return is stored as a ``return_payment`` claim transaction with negative amounts linked to the
payment. Paid goes down and the reserve back up by the returned amounts; recoveries are untouched.
Needs the ``claims/enable-return-payments`` setting and an explicit ``rw`` rule on exactly
``britecore/claims/accounting/returnPayments``.

Request Payload
---------------
return_payment_details : dict
    {
        "original_transaction_id": str,
        "exposure_id": str,
        "date": "YYYY-MM-DD",
        "loss_returned": number,
        "adjusting_returned": number,
        "legal_returned": number,
        "reason": str,
        "other_text": str,          # required when reason is "Other"
        "check_number": str,        # optional, digits only
        "payment_method": str,      # optional, a carrier payment method id
        "memo": str                 # optional
    }

Returns
-------
dict
    The payment's return summary after the return, with ``transaction_id`` set to the new return.

Raises
------
BCApiRequestPermissionDeniedError
    When the caller holds no exact grant.

Code
Updates an existing exposure's claimant, coverage, or loss/risk.
Blocked when payments exist on the exposure.

Code
Update an existing payment transaction.

Request Payload
---------------
payment_details : dict
    Partial payment payload that includes ``id`` and one or more
    updatable fields from ``make_payment``.

Returns
-------
dict
    On success, the updated payment object (same shape as
    ``make_payment`` response).

    If authority limits are exceeded::

        {"brokenLimits": [...], "adminData": {...}}

Code
Void a return payment, keeping it in the ledger marked Voided.

Paid goes back up by the returned amounts. While the claim is open and has not been closed since the
return, the reserve goes back down by what the return restored; a reserve now lower than that refuses
the void. The reason is stored in the "Return Payment Voided" note. Needs an explicit ``rw`` rule on
exactly ``britecore/claims/accounting/returnPayments``; the setting is not required.

Request Payload
---------------
return_void_details : dict
    {
        "transaction_id": str,      # the return payment
        "reason": str               # required, up to 250 characters
    }

Returns
-------
dict
    The void summary after the void, with the linked payment's remaining balance restored.

Raises
------
BCApiRequestPermissionDeniedError
    When the caller holds no exact grant.

Code
Void a claim accounting transaction.

Parameters
----------
transaction_id : str
    Transaction ID.

Returns
-------
str
    The voided transaction ID.