> For the complete documentation index, see [llms.txt](https://docs.insurehero.io/shield-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.insurehero.io/shield-api/claims/claims-management.md).

# Claims Management

***

To initiate a claim using the Shield API, the user creating the claim must first be registered. For security reasons, we recommend using the [OTP (one-time password) creation and confirmation endpoint sent to the user's email to confirm ownership of the email address used for the claim.](https://docs.insurehero.io/shield-api/policies/user-management#create-opt) Once verified, follow this workflow: retrieve the user’s active risk items, which include items where they are the authorized claimant. Present these items to the user for selection. Upon selection, you can use the risk item UID to retrieve the available variants. With the claimant, risk item, and variant details established, a claim can be created, tying together the claimant, the risk item, and the contested variant. A claim allows you to explain what happened to a single risk item with regard to a specific variant, which has its own rules and exceptions. During the claim process, the user might be asked to provide additional information to corroborate their claim; this information is archivable using the communication endpoints.

## Endpoints

<table><thead><tr><th width="113">Method</th><th>Endpoint</th></tr></thead><tbody><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#identify-the-user"><code>https://app.insurehero.io/api/shield/v1/users/:userId</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#identify-the-user"><code>https://app.insurehero.io/api/shield/v1/users/by-email/:userEmail</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-the-users-risk-items"><code>https://app.insurehero.io/api/shield/v1/users/:userId/risk-items</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-the-variants-available-for-the-risk-item"><code>https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/variants</code></a></td></tr><tr><td><mark style="color:green;">POST</mark></td><td><a href="#create-a-new-claim-for-a-risk-item"><code>https://app.insurehero.io/api/shield/v1/claims</code></a></td></tr><tr><td><mark style="color:green;">POST</mark></td><td><a href="#create-a-new-claim-for-a-risk-item"><code>https://app.insurehero.io/api/shield/v2/claims</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#user-claims"><code>https://app.insurehero.io/api/shield/v1/users/:userId/claims</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#all-claims"><code>https://app.insurehero.io/api/shield/v1/claims</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#all-claims"><code>https://app.insurehero.io/api/shield/v2/claims</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-the-data-of-a-given-claim"><code>https://app.insurehero.io/api/shield/v1/claims/:claimId</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-the-data-of-a-given-claim"><code>https://app.insurehero.io/api/shield/v2/claims/:claimId</code></a></td></tr><tr><td><mark style="color:purple;">PATCH</mark></td><td><a href="#add-a-communication-to-a-claim"><code>https://app.insurehero.io/api/shield/v2/claims/:claimId</code></a></td></tr><tr><td><mark style="color:green;">POST</mark></td><td><a href="#post-a-claim-without-user-authorization-token"><code>https://app.insurehero.io/api/shield/v1/claims</code></a></td></tr><tr><td><mark style="color:green;">POST</mark></td><td><a href="#add-event-to-claim"><code>https://app.insurehero.io/api/shield/v1/claims/:claimId/events</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-claim-events"><code>https://app.insurehero.io/api/shield/v1/claims/:claimId/events</code></a></td></tr></tbody></table>

{% hint style="info" %}
Every error response uses the same envelope: `{ "error": string, "details": any }`. See [Error Handling](https://docs.insurehero.io/shield-api/data-dictionary#error-handling) for the general format and the meaning of each status code.
{% endhint %}

## Step-by-Step Workflow

To initiate a claim using the Shield API, the user creating the claim must first be registered. For security reasons, this is accomplished via an OTP (One-Time Password) confirmation code sent to the user’s email to confirm that they are the owner of the email submitting the claim.

Once verified, the workflow is as follows: retrieve the user’s active risk items, which include items where they are either the holder or an authorized claimant. Present these items to the user for selection. Upon selection, you can now use the risk item UID to retrieve the available coverages by identifying the correct variant. With the claimant, risk item, and coverage details established, a claim can then be created, tying together the claimant, the risk item, the contested coverage, and the relevant policy. A claim allows you to explain what happened to a single risk item in regards to a specific coverage, which has its own rules and exceptions. During the claim process, the user might be asked to provide additional information to corroborate their claim.

### Identify the user

You can identify the user using its uid or id.

<mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v1/users/:userId`

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Path Parameters

<table><thead><tr><th>Name</th><th width="212">Type</th><th>Description</th></tr></thead><tbody><tr><td>userId<mark style="color:red;">*</mark></td><td>string</td><td>The value to search by: id, uid, email, phone or document number (see <code>searchBy</code>)</td></tr></tbody></table>

#### Query Parameters

<table><thead><tr><th width="256">Name</th><th width="201">Type</th><th>Description</th></tr></thead><tbody><tr><td>searchBy</td><td>id | uid | email | phone | document_number</td><td>Field used to search for a matching user. Defaults to 'id'</td></tr></tbody></table>

Or using its email.

<mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v1/users/by-email/:userEmail`

#### Path Parameters

| Name                                        | Type   | Description    |
| ------------------------------------------- | ------ | -------------- |
| userEmail<mark style="color:red;">\*</mark> | string | The user email |

#### Example Response

{% tabs %}
{% tab title="200: OK Retrieved successfully" %}

```json
{
    "data": {
        "id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
        "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
        "email": "maria.lopez@example.com",
        "first_name": "Maria",
        "last_name": "Lopez",
        "phone": "+593991234501",
        "uid": "USR-0001",
        "gender": "FEMALE",
        "dob": "1990-05-10T00:00:00+00:00",
        "address": "Av. 9 de Octubre 100, Guayaquil",
        "document_type": "CI",
        "document_number": "1700000001",
        "bank_accounts": [
            {
                "account_name": "Maria Lopez",
                "bank_name": "Example Bank",
                "account_number": "1234567890",
                "bic_swift": "EXBKECEG",
                "iban": "EC00EXBK0000001234567890",
                "routing_number": "011000015",
                "country": "0e9178ee-6453-53dc-984b-65bf02c016c2",
                "currency": "70c94a4a-6764-5590-b1cf-e13e352c8f93",
                "account_type": "Checking",
                "bank_address": "Av. 9 de Octubre 100, Guayaquil",
                "additional_info": "Primary account"
            }
        ],
        "company_name": "Andes Logistics S.A.",
        "company_role": "Founder",
        "company_email": "operations@example.com",
        "company_identifier": {
            "type": "RUC",
            "value": "1790000001001"
        },
        "company_address": "Av. 9 de Octubre 100, Guayaquil",
        "company_bank_accounts": [
            {
                "account_name": "Andes Logistics S.A.",
                "bank_name": "Example Bank",
                "account_number": "1234567890",
                "bic_swift": "EXBKECEG",
                "iban": "EC00EXBK0000001234567890",
                "routing_number": "011000015",
                "country": "0e9178ee-6453-53dc-984b-65bf02c016c2",
                "currency": "70c94a4a-6764-5590-b1cf-e13e352c8f93",
                "account_type": "Savings",
                "bank_address": "Av. 9 de Octubre 100, Guayaquil",
                "additional_info": "Branch: Main"
            }
        ],
        "group_id": "2ceb1648-18b8-5d01-b614-8d697d282632",
        "metadata": {}
    }
}

```

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}

```json
{}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

{% endtab %}
{% endtabs %}

#### Attributes

| Name                    | Type       | Description                                |
| ----------------------- | ---------- | ------------------------------------------ |
| data                    | object     | Object containing information about a user |
| channel\_id             | uuid       | Unique identifier of the channel.          |
| email                   | string     | User's email address.                      |
| first\_name             | string     | User's first name.                         |
| last\_name              | string     | User's last name.                          |
| phone                   | string     | User's phone number.                       |
| uid                     | string     | Unique user identifier.                    |
| gender                  | string     | User's gender.                             |
| dob                     | string     | Date of birth in ISO 8601 format.          |
| address                 | string     | User's address.                            |
| document\_type          | string     | Type of document.                          |
| document\_number        | string     | User's document number.                    |
| bank\_accounts          | object\[]  | List of user's personal bank accounts.     |
| company\_name           | string     | Name of the user's company.                |
| company\_role           | string     | User's role in the company.                |
| company\_email          | string     | Company email address.                     |
| company\_identifier     | object     | Identification details of the company.     |
| company\_address        | string     | Address of the company.                    |
| company\_bank\_accounts | object \[] | List of company's bank accounts.           |
| group\_id               | uuid       | Identifier of the user's group.            |
| metadata                | jsonb      | Additional user metadata.                  |

Bank Account Structure

| Name             | Type   | Description                               |
| ---------------- | ------ | ----------------------------------------- |
| account\_name    | string | Name of the account holder.               |
| bank\_name       | string | Name of the bank.                         |
| account\_number  | string | User's account number.                    |
| bic\_swift       | string | Bank's BIC/SWIFT code.                    |
| iban             | string | International Bank Account Number (IBAN). |
| routing\_number  | string | Routing number for the account.           |
| country          | uuid   | Country identifier.                       |
| currency         | uuid   | Currency identifier.                      |
| account\_type    | string | Type of account.                          |
| bank\_address    | string | Address of the bank.                      |
| additional\_info | string | Additional details.                       |

Company Identifier

<table><thead><tr><th width="251">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>type</td><td>string</td><td>Type of company identifier.</td></tr><tr><td>value</td><td>string</td><td>The actual identifier value.</td></tr></tbody></table>

### Get the user's risk items

After retrieving user information, you can access all risk items associated with them. It's important to note that this association relies on the 'authorized\_claimants' array within the risk items. Each object inside this array must include the 'email' key with the user's email address, which should be registered using the user post route. These email addresses must correspond to existing entries in the user table for the association to be valid.

<mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v1/users/:userId/risk-items`

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Path Parameters

| Name                                     | Type   | Description            |
| ---------------------------------------- | ------ | ---------------------- |
| userId<mark style="color:red;">\*</mark> | string | Either user\_id or uid |

#### Query Parameters

<table><thead><tr><th width="252">Name</th><th width="213">Type</th><th>Description</th></tr></thead><tbody><tr><td>searchBy</td><td>id | uid | email | phone | document_number</td><td>Field used to search for a matching user. Defaults to 'id'</td></tr></tbody></table>

#### Example Response

{% tabs %}
{% tab title="200: OK Retrieved successfully" %}

```json
{
    "data": [
        {
            "id": "371dcc84-f8d7-54e0-9f2e-2599950e7297",
            "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c",
            "authorized_claimants": [
                {
                    "email": "maria.lopez@example.com"
                }
            ],
            "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd",
            "start_date": "2026-03-01T05:00:00+00:00",
            "end_date": "2027-03-01T05:00:00+00:00",
            "beneficiaries": [
                {
                    "email": null
                }
            ],
            "insured_subject": {
                "identifier_value": "1700000002",
                "identifier_type": "CI"
            },
            "status": "ACTIVE",
            "uid": "RI-0001",
            "assets": [],
            "metadata": {}
        }
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}
{}
{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

{% endtab %}
{% endtabs %}

#### Attributes

| Name                  | Type      | Description                            |
| --------------------- | --------- | -------------------------------------- |
| id                    | uuid      | Unique identifier of the risk item.    |
| policy\_id            | uuid      | Identifier of the associated policy.   |
| authorized\_claimants | object\[] | List of authorized claimants.          |
| package\_id           | uuid      | Identifier of the insurance package.   |
| start\_date           | string    | Start date of the coverage.            |
| end\_date             | string    | End date of the coverage.              |
| beneficiaries         | object\[] | List of beneficiaries.                 |
| insured\_subject      | object    | Information about the insured subject. |
| status                | string    | Status of the risk item.               |
| uid                   | string    | User identifier.                       |
| assets                | object\[] | List of associated assets.             |
| metadata              | jsonb     | Additional metadata.                   |

#### **Authorized Claimants Structure**

| Name  | Type   | Description                       |
| ----- | ------ | --------------------------------- |
| email | string | Email of the authorized claimant. |

#### **Beneficiaries Structure**

| Name  | Type   | Description               |
| ----- | ------ | ------------------------- |
| email | string | Email of the beneficiary. |

#### **Insured Subject Structure**

| Name              | Type   | Description                                     |
| ----------------- | ------ | ----------------------------------------------- |
| identifier\_value | string | Unique identifier value of the insured subject. |
| identifier\_type  | string | Type of identifier.                             |

### Get the variants available for the risk item

You can get all the variants available that cover a Risk Item. The variants are read from the product snapshot stored in the risk item's policy.

<mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/variants`

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Path Parameters

| Name                                         | Type   | Description      |
| -------------------------------------------- | ------ | ---------------- |
| riskItemId<mark style="color:red;">\*</mark> | string | The risk item ID |

#### Query Parameters

| Name     | Type      | Description                                                     |
| -------- | --------- | --------------------------------------------------------------- |
| searchBy | id \| uid | Field used to search for a matching risk item. Defaults to 'id' |

#### Example Response

{% tabs %}
{% tab title="200: OK Retrieved successfully" %}

```json
{
    "data": [
        {
            "id": "294594d1-4100-577f-9222-46dd8dc69ab2",
            "uid": "VAR-GOLD",
            "name": "Gold plan",
            "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
            "coverage_id": "c98625a4-bff7-5485-90b4-6e45758bccee",
            "insurer_id": null,
            "description": null,
            "conditions": "Coverage applies to incidents reported within 30 days.",
            "exclusions": "Pre-existing damage is not covered.",
            "net_price": null,
            "fields": null,
            "subject_schema": {},
            "claim_schema": {}
        }
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}
{}
{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

{% endtab %}

{% tab title="404: Not Found Resource not found" %}

```json
{
    "error": "Resource not found",
    "details": "Risk item not found"
}
```

If the risk item exists but its policy has no variants, `details` is `"Variants not found"`.
{% endtab %}
{% endtabs %}

#### Attributes

<table><thead><tr><th>Name</th><th width="174">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>uuid</td><td>Unique identifier of the variant.</td></tr><tr><td>uid</td><td>string</td><td>Unique identifier of the variant in your system. Send it as <code>variant_uid</code> when you create a claim with v2. Can be null.</td></tr><tr><td>name</td><td>string</td><td>Name of the variant.</td></tr><tr><td>channel_id</td><td>uuid</td><td>Identifier of the channel.</td></tr><tr><td>coverage_id</td><td>uuid</td><td>Identifier of the associated coverage. Can be null.</td></tr><tr><td>insurer_id</td><td>string</td><td>Identifier of the insurer. Can be null.</td></tr><tr><td>description</td><td>string</td><td>Description of the variant. Can be null.</td></tr><tr><td>conditions</td><td>string</td><td>Conditions associated with the variant. Can be null.</td></tr><tr><td>exclusions</td><td>string</td><td>Exclusions related to the variant. Can be null.</td></tr><tr><td>net_price</td><td>string</td><td>Net price of the variant. Can be null.</td></tr><tr><td>fields</td><td>jsonb</td><td>Additional field configuration of the variant. Can be null.</td></tr><tr><td>subject_schema</td><td>jsonb</td><td>Insured subject schema for this variant. Can be null.</td></tr><tr><td>claim_schema</td><td>jsonb</td><td>Claim schema for this variant. The incident's additional properties are validated against it when you create a claim. Can be null.</td></tr></tbody></table>

Fields that are not set in the policy snapshot are omitted from the response.

## Create a Claim

Once you have all the information you can create the claim.

{% hint style="success" %}
**Good to know**

It's very likely that the UID of the variants might not be descriptive enough or could even be confusing (imagine a variant named "life\_insurance\_up\_to\_1,000"). Therefore, we recommend displaying the variant's description and/or name when selecting it, while sending us the variant UID in the background.
{% endhint %}

### Create a new claim for a risk item

{% tabs %}
{% tab title="v1" %} <mark style="color:green;">`POST`</mark> `https://app.insurehero.io/api/shield/v1/claims`
{% endtab %}

{% tab title="v2" %} <mark style="color:green;">`POST`</mark> `https://app.insurehero.io/api/shield/v2/claims`
{% endtab %}
{% endtabs %}

#### Headers

| Name                                                 | Type   | Description                                                                                          |
| ---------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark>      | string | Bearer access token                                                                                  |
| User-Authorization<mark style="color:red;">\*</mark> | string | [User unique token to create claims](https://docs.insurehero.io/shield-api/policies/user-management) |

{% hint style="warning" %}
**User-Authorization**

* Send the user token returned by [`POST /v1/users/:userId/verify-otp`](https://docs.insurehero.io/shield-api/policies/user-management) as is, without the `Bearer` prefix. The token is valid for 1 hour.
* The channel access token is not accepted in this header. Without a valid user token the request fails with `400` and details `"Missing user token"`.
* Channels enabled for handshake can send `claimant_email` in the body instead of the user token (see [Post a Claim without User-Authorization token](#post-a-claim-without-user-authorization-token)). In those channels, a request with neither returns `400` with details `"Missing user token and claimant_email"`.
  {% endhint %}

#### Request Body

{% tabs %}
{% tab title="v1" %}

| Name                                             | Type         | Description                                            |
| ------------------------------------------------ | ------------ | ------------------------------------------------------ |
| risk\_item\_id<mark style="color:red;">\*</mark> | string       | Item being claimed                                     |
| variant\_id<mark style="color:red;">\*</mark>    | string       | The coverage variant chosen for this claim             |
| metadata                                         | object       | Additional data of this claim                          |
| subject<mark style="color:red;">\*</mark>        | string       | A sentence describing the claim (10 to 255 characters) |
| incident<mark style="color:red;">\*</mark>       | IncidentType | Incident data                                          |
| claim\_amount                                    | number       | A positive number requested to be paid                 |

The description of the incident goes in `incident.details.description`. A `description` field at the root of the body is ignored.
{% endtab %}

{% tab title="v2" %}

| Name                                              | Type         | Description                                |
| ------------------------------------------------- | ------------ | ------------------------------------------ |
| risk\_item\_uid<mark style="color:red;">\*</mark> | string       | Item being claimed                         |
| variant\_uid<mark style="color:red;">\*</mark>    | string       | The coverage variant chosen for this claim |
| incident<mark style="color:red;">\*</mark>        | IncidentType | Incident data.                             |
| metadata                                          | object       | Additional data of this claim              |

In v2, `subject`, `description` and `claim_amount` go inside `incident`. Fields at the root of the body other than the ones listed here are not stored.
{% endtab %}
{% endtabs %}

#### Example Response 201

{% tabs %}
{% tab title="v1 " %}

```json
{
    "data": {
        "id": "82802426-7a16-5104-b5ab-273bb941d782",
        "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd",
        "subject": "Cargo stolen during delivery",
        "claimant_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
        "risk_item_id": "371dcc84-f8d7-54e0-9f2e-2599950e7297",
        "variant_id": "294594d1-4100-577f-9222-46dd8dc69ab2",
        "type": "Property Insurance",
        "status": "SUBMITTED",
        "uid": null,
        "insurer_claim_number": null,
        "internal_claim_number": 88,
        "incident_date": "2026-03-15T14:30:00.000+00:00",
        "consent_date": null,
        "resolution_date": null,
        "assets": [],
        "incident": {
            "date": "2026-03-15T14:30:00.000Z",
            "details": {
                "transaction": {
                    "date": "2026-03-10T14:48:00.000Z",
                    "amount": 150,
                    "method": "VISA",
                    "retailer": "Example Store",
                    "description": "Transaction description"
                },
                "description": "The cargo was stolen during a scheduled delivery stop. The incident occurred while the cargo was en route to its next destination."
            },
            "additional_properties": {
                "claim_type": "THEFT",
                "fast_track": true,
                "incident_coords": "-0.1807, -78.4678"
            }
        },
        "claim_amount": null,
        "communications": [],
        "metadata": {},
        "policy_reference": {
            "policy": {
                "id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c",
                "uid": "POL-0001",
                "version": 2,
                "metadata": {},
                "policy_number": "PN-0001",
                "total_gross_price": "535253 + 125125"
            },
            "variant": {
                "id": "294594d1-4100-577f-9222-46dd8dc69ab2",
                "name": "Gold plan",
                "markup": [
                    {
                        "owner": "channel",
                        "taxes": [
                            {
                                "name": "VAT",
                                "rate": 0.15
                            }
                        ],
                        "net_price": null,
                        "gross_price": "125125"
                    }
                ],
                "conditions": "Coverage applies to incidents reported within 30 days.",
                "created_at": "2026-01-10T20:59:36.0742+00:00",
                "exclusions": "Pre-existing damage is not covered.",
                "description": null,
                "coverage_id": "c98625a4-bff7-5485-90b4-6e45758bccee",
                "insurer_id": null
            },
            "riskItem": {
                "id": "371dcc84-f8d7-54e0-9f2e-2599950e7297",
                "start_date": "2026-03-01T05:00:00+00:00",
                "end_date": "2027-03-01T05:00:00+00:00",
                "insured_subject": {
                    "identifier_value": "1700000002",
                    "identifier_type": "CI"
                },
                "metadata": {},
                "beneficiaries": []
            }
        },
        "claimant_data": {
            "id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
            "dob": "1990-05-10T00:00:00+00:00",
            "uid": "USR-0001",
            "name": "Maria Lopez",
            "email": "maria.lopez@example.com",
            "phone": "+593991234501",
            "gender": "FEMALE",
            "address": "Av. 9 de Octubre 100, Guayaquil",
            "group_id": "2ceb1648-18b8-5d01-b614-8d697d282632",
            "metadata": {},
            "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
            "company_name": "Andes Logistics S.A.",
            "company_role": "Founder",
            "bank_accounts": null,
            "company_email": "operations@example.com",
            "document_type": "CI",
            "company_address": "Av. 9 de Octubre 100, Guayaquil",
            "document_number": "1700000001",
            "company_identifier": null,
            "company_bank_accounts": null
        }
    }
}
```

{% endtab %}

{% tab title="v2" %}

```json
{
    "data": {
        "id": "5dac73e7-b568-5ad4-bed2-3ce06f1c47e0",
        "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd",
        "claimant_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
        "risk_item_id": "371dcc84-f8d7-54e0-9f2e-2599950e7297",
        "variant_id": "294594d1-4100-577f-9222-46dd8dc69ab2",
        "type": "Property Insurance",
        "status": "SUBMITTED",
        "uid": null,
        "insurer_claim_number": null,
        "internal_claim_number": 89,
        "consent_date": null,
        "resolution_date": null,
        "assets": [],
        "metadata": {},
        "incident": {
            "date": "2026-03-15T14:30:00.000Z",
            "subject": "Cargo stolen during delivery",
            "claim_amount": 500,
            "description": "The cargo was stolen during a scheduled delivery stop.",
            "property_one": true
        },
        "communications": []
    }
}
```

{% endtab %}
{% endtabs %}

If the claimant (the user of the token, or `claimant_email`) does not exist in the channel, the response is `404` with `"details": "Claimant not found"`.

**IncidentType**

{% tabs %}
{% tab title="v1" %}

| Value                                     | Type                        |
| ----------------------------------------- | --------------------------- |
| date<mark style="color:red;">\*</mark>    | date                        |
| summary                                   | string (5 to 30 characters) |
| details<mark style="color:red;">\*</mark> | DetailsType                 |
| additional\_properties                    | JSON                        |

`additional_properties` is validated against the claim schema of the selected variant.

**DetailsType**

| Value                                         | Type            |
| --------------------------------------------- | --------------- |
| transaction<mark style="color:red;">\*</mark> | TransactionType |
| description                                   | string          |

**TransactionType**

| Value        | Type                                        |
| ------------ | ------------------------------------------- |
| date         | string                                      |
| amount       | number                                      |
| method       | VISA, MASTERCARD, AMEX, DISCOVER o TRANSFER |
| retailer     | string                                      |
| description  | string                                      |
| {% endtab %} |                                             |

{% tab title="v2" %}

| Value                                     | Type                          |
| ----------------------------------------- | ----------------------------- |
| subject<mark style="color:red;">\*</mark> | string (10 to 255 characters) |
| date<mark style="color:red;">\*</mark>    | date                          |
| description                               | string                        |
| claim\_amount                             | number                        |
| transaction                               | TransactionType               |

Any other key inside `incident` is stored as an additional property of the incident and validated against the claim schema of the selected variant.
{% endtab %}
{% endtabs %}

### User claims

Fetch all claims from a given user

<mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v1/users/:userId/claims`

#### Path Parameters

| Name                                     | Type   | Description            |
| ---------------------------------------- | ------ | ---------------------- |
| userId<mark style="color:red;">\*</mark> | string | Either user\_id or uid |

#### Query Parameters

<table><thead><tr><th>Name</th><th width="213">Type</th><th>Description</th></tr></thead><tbody><tr><td>searchBy</td><td>id | uid | email</td><td>Field used to search for a matching user. Defaults to 'id'</td></tr></tbody></table>

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

{% tabs %}
{% tab title="200: OK Retrieved successfully" %}

```json
{
    "data": [
        {
            "id": "c245b7ae-7dfe-5230-88b1-df0200a298ac",
            "package_id": "1cfefa45-b04c-52d6-9c00-aeefea8b6cee",
            "subject": "Car accident",
            "claimant_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
            "risk_item_id": "b19172f2-f932-5134-a753-63bff448aae0",
            "variant_id": "b5730dea-a857-5e58-b563-b8bcde1d2118",
            "type": "Car Insurance",
            "status": "SUBMITTED",
            "uid": null,
            "insurer_claim_number": null,
            "internal_claim_number": 1,
            "incident_date": "2026-03-15T14:30:00.000+00:00",
            "consent_date": null,
            "resolution_date": null,
            "assets": [],
            "incident": {
                "date": "2026-03-15T14:30:00.000Z",
                "details": {
                    "transaction": {
                        "date": "2026-03-10T14:48:00.000Z",
                        "amount": 100,
                        "method": "VISA",
                        "retailer": "Example Store",
                        "description": "Purchase of goods"
                    },
                    "description": "The car was damaged during a collision at an intersection. The incident occurred while driving to work."
                },
                "additional_properties": {
                    "claim_type": "COLLISION",
                    "fast_track": true,
                    "incident_coords": "-2.1894, -79.8891"
                }
            },
            "claim_amount": null,
            "communications": [],
            "metadata": {}
        }
    ]
}

```

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}

{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

{% endtab %}

{% tab title="422: Unprocessable Entity Internal validation failed" %}

{% endtab %}

{% tab title="404: Not Found User not found" %}

```json
{
    "error": "Resource not found",
    "details": "User not found"
}
```

{% endtab %}
{% endtabs %}

#### Attributes

<table><thead><tr><th>Name</th><th width="183">Type</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>object</td><td>Claims data List of claims related to the user.</td></tr><tr><td>id</td><td>uuid</td><td>Unique identifier of the claim</td></tr><tr><td>package_id</td><td>string</td><td>Identifier of the associated package</td></tr><tr><td>subject</td><td>string</td><td>Subject or title of the claim</td></tr><tr><td>claimant_id</td><td>string</td><td>Unique identifier of the claimant</td></tr><tr><td>risk_item_id</td><td>uuid</td><td>Identifier of the associated risk item</td></tr><tr><td>variant_id</td><td>uuid</td><td>Identifier of the policy variant</td></tr><tr><td>type</td><td>string</td><td>Type of insurance claim. Can be null.</td></tr><tr><td>status</td><td>string</td><td>Current status of the claim</td></tr><tr><td>uid</td><td>string</td><td>Unique identifier of the claim in external systems</td></tr><tr><td>insurer_claim_number</td><td>string</td><td>Claim number assigned by the insurer</td></tr><tr><td>internal_claim_number</td><td>number</td><td>Internal claim number assigned by the system</td></tr><tr><td>incident_date</td><td>string</td><td>Date and time of the incident (ISO 8601 format)</td></tr><tr><td>consent_date</td><td>string</td><td>Date when consent was given, if applicable</td></tr><tr><td>resolution_date</td><td>string</td><td>Date when the claim was resolved, if applicable</td></tr><tr><td>assets</td><td>object[]</td><td>List of associated assets</td></tr><tr><td>incident</td><td>object</td><td>Contains information about the reported incident, including date, details, and additional properties.</td></tr><tr><td>claim_amount</td><td>number</td><td>Total amount claimed</td></tr><tr><td>communications</td><td>object[]</td><td>List of communications related to the claim</td></tr><tr><td>metadata</td><td>object</td><td>Additional metadata about the claim</td></tr></tbody></table>

This endpoint does not return `policy_reference` or `claimant_data`. Use [Get the data of a given claim](#get-the-data-of-a-given-claim) to read them.

### All claims

{% tabs %}
{% tab title="v1" %} <mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v1/claims`
{% endtab %}

{% tab title="v2" %} <mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v2/claims`
{% endtab %}
{% endtabs %}

A paginated list of all claims.

Page size cannot exceed 100 records at a time.

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Query Parameters

| Name                                   | Type    | Description                              |
| -------------------------------------- | ------- | ---------------------------------------- |
| from<mark style="color:red;">\*</mark> | number  | Starting record index                    |
| to<mark style="color:red;">\*</mark>   | number  | Ending record index                      |
| comm\_info                             | boolean | Communication information for that claim |
| policy\_ref                            | boolean | The policy detail for that claim         |
| general                                | boolean | The details of the claim                 |

`from` must be lower than `to`. Each flag is applied when the parameter is present with any value (`false` is also treated as present). Without flags the endpoint returns the details of the claim (`general`); with flags it returns `id` plus the selected groups.

#### Example Response 200

{% tabs %}
{% tab title="V1" %}

```json
{
    "data": [
        {
            "id": "8b3a2608-bff2-5d36-aaae-2e30ff9db9bc",
            "communications": [],
            "policy_reference": {
                "policy": {
                    "id": "40ae240b-1fe2-5240-8cd7-622e935b3ad1",
                    "uid": "POL-0002",
                    "version": 1,
                    "metadata": {},
                    "policy_number": "PN-0002",
                    "total_gross_price": "100 + 50"
                },
                "variant": {
                    "id": "2ec38e90-0097-5a26-97e2-08b5b34bcacc",
                    "name": "Silver plan",
                    "conditions": "Standard coverage conditions apply.",
                    "created_at": "2026-01-10T21:00:41.277415+00:00",
                    "exclusions": "Excludes pre-existing conditions.",
                    "insurer_id": "94f9e6c6-0b50-5d44-af83-4a11195ba7bf",
                    "description": "Silver plan with standard medical coverage."
                },
                "riskItem": {}
            },
            "created_at": "2026-03-16T17:18:36.452503+00:00",
            "updated_at": "2026-03-16T17:18:36.452503+00:00",
            "deleted_at": null,
            "risk_item_id": "51bdb6c8-1f54-5bf2-a586-9ebaa9a9490c",
            "claimant_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
            "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
            "subject": "I broke my leg",
            "insurer_claim_number": null,
            "internal_claim_number": 42,
            "status": "SUBMITTED",
            "incident_date": "2026-03-15T14:30:00.000+00:00",
            "resolution_date": null,
            "claim_amount": null,
            "payout_amount": null,
            "metadata": {},
            "assets": [],
            "type": "Health Insurance",
            "consent_date": null,
            "incident": {
                "date": "2026-03-15T14:30:00.000Z",
                "details": {
                    "description": "I was riding a bike and fell.",
                    "transaction": {}
                },
                "summary": "MEDICAL",
                "additional_properties": {}
            },
            "package_id": "6cb8ecbb-f171-54b5-b62c-9edae3e1465b",
            "transaction_date": null,
            "uid": null,
            "variant_id": "2ec38e90-0097-5a26-97e2-08b5b34bcacc",
            "claimant_data": {
                "id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
                "dob": "1990-05-10T00:00:00+00:00",
                "uid": "USR-0001",
                "name": "Maria Lopez",
                "email": "maria.lopez@example.com",
                "phone": "+593991234501",
                "gender": "FEMALE",
                "address": "Av. 9 de Octubre 100, Guayaquil",
                "group_id": "2ceb1648-18b8-5d01-b614-8d697d282632",
                "metadata": {
                    "vip": true
                },
                "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
                "company_name": "Andes Logistics S.A.",
                "company_role": "Founder",
                "bank_accounts": [
                    {
                        "iban": "EC00EXBK0000001234567890",
                        "country": "EC",
                        "currency": "USD",
                        "bank_name": "Example Bank",
                        "bic_swift": "EXBKECEG",
                        "account_name": "Maria Lopez",
                        "account_type": "checking",
                        "bank_address": "Av. 9 de Octubre 100, Guayaquil",
                        "account_number": "1234567890",
                        "routing_number": "011000015",
                        "additional_info": "Primary account"
                    },
                    {
                        "iban": "EC00EXBK0000001234567890",
                        "country": "EC",
                        "currency": "USD",
                        "bank_name": "Example Bank",
                        "bic_swift": "EXBKECEG",
                        "account_name": "Maria Lopez",
                        "account_type": "savings",
                        "bank_address": "Av. 9 de Octubre 100, Guayaquil",
                        "account_number": "1234567890",
                        "routing_number": "011000015",
                        "additional_info": "Savings account"
                    }
                ],
                "company_email": "operations@example.com",
                "document_type": "CI",
                "company_address": "Av. 9 de Octubre 100, Guayaquil",
                "document_number": "1700000001",
                "company_identifier": {
                    "type": "RUC",
                    "value": "1790000001001"
                },
                "company_bank_accounts": [
                    {
                        "iban": "EC00EXBK0000001234567890",
                        "country": "EC",
                        "currency": "USD",
                        "bank_name": "Example Bank",
                        "bic_swift": "EXBKECEG",
                        "account_name": "Andes Logistics S.A.",
                        "account_type": "business",
                        "bank_address": "Av. 9 de Octubre 100, Guayaquil",
                        "account_number": "1234567890",
                        "routing_number": "011000015",
                        "additional_info": "Corporate account"
                    }
                ]
            },
            "required_documents": {},
            "owner_id": null,
            "assignee_id": null
        }
    ]
}
```

{% endtab %}

{% tab title="V2" %}

```json
{
    "data": [
        {
            "id": "8b3a2608-bff2-5d36-aaae-2e30ff9db9bc",
            "package_id": "6cb8ecbb-f171-54b5-b62c-9edae3e1465b",
            "claimant_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
            "risk_item_id": "51bdb6c8-1f54-5bf2-a586-9ebaa9a9490c",
            "variant_id": "2ec38e90-0097-5a26-97e2-08b5b34bcacc",
            "type": "Health Insurance",
            "status": "SUBMITTED",
            "uid": null,
            "insurer_claim_number": null,
            "internal_claim_number": 42,
            "consent_date": null,
            "resolution_date": null,
            "assets": [],
            "metadata": {},
            "policy_reference": {
                "policy": {
                    "id": "40ae240b-1fe2-5240-8cd7-622e935b3ad1",
                    "uid": "POL-0002",
                    "version": 1,
                    "metadata": {},
                    "policy_number": "PN-0002",
                    "total_gross_price": "100 + 50"
                },
                "variant": {
                    "id": "2ec38e90-0097-5a26-97e2-08b5b34bcacc",
                    "name": "Silver plan",
                    "conditions": "Standard coverage conditions apply.",
                    "created_at": "2026-01-10T21:00:41.277415+00:00",
                    "exclusions": "Excludes pre-existing conditions.",
                    "insurer_id": "94f9e6c6-0b50-5d44-af83-4a11195ba7bf",
                    "description": "Silver plan with standard medical coverage."
                },
                "riskItem": {}
            },
            "incident": {
                "date": "2026-03-15T14:30:00.000Z",
                "details": {
                    "description": "I was riding a bike and fell.",
                    "transaction": {}
                },
                "additional_properties": {},
                "subject": "I broke my leg",
                "claim_amount": null
            },
            "communications": [],
            "created_at": "2026-03-16T17:18:36.452503+00:00",
            "updated_at": "2026-03-16T17:18:36.452503+00:00",
            "deleted_at": null,
            "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
            "payout_amount": null,
            "transaction_date": null
        },
        {
            "id": "ff8b675a-bb56-5e5d-8130-7fc28d0ba0db",
            "package_id": "ea607b11-65a0-5763-a492-ea9e02ebf393",
            "claimant_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
            "risk_item_id": "564ec620-c35c-5f4d-a8e5-0b09507e4e66",
            "variant_id": "b1ab5dc8-057f-5a29-9c1b-9958c7f94638",
            "type": "Life Insurance",
            "status": "SUBMITTED",
            "uid": null,
            "insurer_claim_number": null,
            "internal_claim_number": 202,
            "consent_date": "2026-04-02T05:00:00+00:00",
            "resolution_date": null,
            "assets": [],
            "metadata": {},
            "policy_reference": {},
            "incident": {
                "date": "2026-04-01T05:00:00.000Z",
                "details": {
                    "transaction": {}
                },
                "additional_properties": {
                    "additional_details": true
                },
                "subject": "Life insurance claim",
                "claim_amount": null
            },
            "communications": [],
            "created_at": "2026-04-02T16:16:08.251657+00:00",
            "updated_at": "2026-04-06T17:00:58.894+00:00",
            "deleted_at": null,
            "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
            "payout_amount": null,
            "transaction_date": null
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Attributes

| Name                    | Type       | Description                                        |
| ----------------------- | ---------- | -------------------------------------------------- |
| data                    | object \[] | List of claims related to the user.                |
| id                      | uuid       | Unique identifier of the claim                     |
| communications          | object \[] | List of communications related to the claim        |
| policy\_reference       | object     | Reference to the associated policy and its details |
| created\_at             | string     | Date and time when the claim was created           |
| updated\_at             | string     | Date and time when the claim was last updated      |
| deleted\_at             | string     | Date and time when the claim was deleted (if any)  |
| risk\_item\_id          | uuid       | Identifier of the related risk item                |
| claimant\_id            | uuid       | Identifier of the claimant                         |
| channel\_id             | uuid       | Identifier of the communication channel            |
| subject                 | string     | Brief description of the claim                     |
| insurer\_claim\_number  | string     | Claim number assigned by the insurer               |
| internal\_claim\_number | number     | Internal claim number for tracking                 |
| status                  | string     | Current status of the claim                        |
| incident\_date          | string     | Date and time of the incident                      |
| resolution\_date        | string     | Date and time when the claim was resolved (if any) |
| claim\_amount           | number     | Amount claimed                                     |
| payout\_amount          | number     | Amount paid by the insurer                         |
| metadata                | object     | Additional metadata for the claim                  |
| assets                  | object \[] | List of assets related to the claim                |
| type                    | string     | Type of insurance claim. Can be null.              |
| consent\_date           | string     | Date when consent was given (if required)          |
| incident                | object     | Details about the incident                         |
| package\_id             | uuid       | Identifier of the related insurance package        |
| transaction\_date       | string     | Date of the related transaction                    |
| uid                     | string     | Unique identifier for the claim (if available)     |
| variant\_id             | uuid       | Identifier of the associated policy variant        |
| claimant\_data          | object     | Personal and contact details of the claimant       |
| required\_documents     | object     | List of required documents for the claim           |
| owner\_id               | uuid       | Identifier of the claim owner                      |
| assignee\_id            | uuid       | Identifier of the person assigned to the claim     |

In v2, `subject` and `claim_amount` are returned inside `incident` instead of at the root, and `incident_date` is not returned.

### Get the data of a given claim

{% tabs %}
{% tab title="v1" %} <mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v1/claims/:claimId`
{% endtab %}

{% tab title="v2" %} <mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v2/claims/:claimId`
{% endtab %}
{% endtabs %}

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Path Parameters

| Name                                      | Type   | Description      |
| ----------------------------------------- | ------ | ---------------- |
| claimId<mark style="color:red;">\*</mark> | string | Claim identifier |

**Query Params**

| Name        | Type                                 | Description                                                 |
| ----------- | ------------------------------------ | ----------------------------------------------------------- |
| searchBy    | id \| uid \| internal\_claim\_number | Field used to search for a matching claim. Defaults to 'id' |
| comm\_info  | boolean                              | Communication information for that claim                    |
| policy\_ref | boolean                              | The policy detail for that claim                            |
| general     | boolean                              | The details of the claim                                    |

If no claim matches, the endpoint responds `404` with details `"Claim not found"`.

#### Example Response 200

{% tabs %}
{% tab title="v1" %}

```json
{
    "data": {
        "id": "3d559069-489f-5564-91d4-ba7627ae5d92",
        "package_id": "51ea41cd-fb00-5688-b07d-82fe3336fba9",
        "claimant_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
        "risk_item_id": "d40ebf8d-efa9-518e-a5a8-7b106ce0ef1a",
        "type": "Auto Insurance",
        "status": "SUBMITTED",
        "uid": "CLM-0001",
        "insurer_claim_number": "INS-0001",
        "internal_claim_number": 69,
        "consent_date": "2026-03-16T05:00:00+00:00",
        "resolution_date": null,
        "assets": [],
        "metadata": {
            "additional_info": "Some additional info"
        },
        "policy_reference": {
            "policy": {
                "id": "e693dbd7-7621-5407-a9e4-5fa0fc44bd67",
                "uid": "POL-0003",
                "version": 1,
                "metadata": {
                    "policy_info": "Additional policy info"
                },
                "policy_number": "PN-0003",
                "total_gross_price": "1 + 1"
            },
            "variant": {
                "id": "c97a1111-89f8-5fbe-bc00-544bb019e476",
                "name": "Basic plan",
                "conditions": "Coverage applies to incidents reported within 30 days.",
                "created_at": "2026-01-10T21:00:41.277415+00:00",
                "exclusions": "Pre-existing damage is not covered.",
                "insurer_id": "94f9e6c6-0b50-5d44-af83-4a11195ba7bf",
                "description": "Basic plan for vehicle damage.",
                "gross_price": "1",
                "pricing_type": "one_time",
                "pricing_rules": {
                    "net_price": "Net price rules"
                },
                "coverage_limits": 0
            },
            "riskItem": {}
        },
        "claimant_data": {
            "id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
            "dob": "1990-05-10T00:00:00+00:00",
            "uid": "USR-0001",
            "name": "Maria Lopez",
            "email": "maria.lopez@example.com",
            "phone": "+593991234501",
            "gender": "FEMALE",
            "address": "Av. 9 de Octubre 100, Guayaquil",
            "group_id": "2ceb1648-18b8-5d01-b614-8d697d282632",
            "metadata": {
                "additional_info": "Some additional info"
            },
            "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
            "company_name": "Andes Logistics S.A.",
            "company_role": "Founder",
            "bank_accounts": [
                {
                    "iban": "EC00EXBK0000001234567890",
                    "country": "EC",
                    "currency": "USD",
                    "bank_name": "Example Bank",
                    "bic_swift": "EXBKECEG",
                    "account_name": "Maria Lopez",
                    "account_type": "Checking",
                    "bank_address": "Av. 9 de Octubre 100, Guayaquil",
                    "account_number": "1234567890",
                    "routing_number": "011000015",
                    "additional_info": "Some additional info"
                }
            ],
            "company_email": "operations@example.com",
            "document_type": "CI",
            "company_address": "Av. 9 de Octubre 100, Guayaquil",
            "document_number": "1700000001",
            "company_identifier": {
                "type": "RUC",
                "value": "1790000001001"
            },
            "company_bank_accounts": [
                {
                    "iban": "EC00EXBK0000001234567890",
                    "country": "EC",
                    "currency": "USD",
                    "bank_name": "Example Bank",
                    "bic_swift": "EXBKECEG",
                    "account_name": "Andes Logistics S.A.",
                    "account_type": "Savings",
                    "bank_address": "Av. 9 de Octubre 100, Guayaquil",
                    "account_number": "1234567890",
                    "routing_number": "011000015",
                    "additional_info": "Some additional info"
                }
            ]
        },
        "incident": {
            "date": "2026-03-15T14:30:00.000Z",
            "details": {
                "description": "I was involved in a car accident.",
                "transaction": {}
            },
            "additional_properties": {}
        },
        "communications": [],
        "created_at": "2026-03-16T17:18:36.452503+00:00",
        "updated_at": "2026-03-16T17:18:36.452503+00:00",
        "deleted_at": null,
        "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
        "subject": "Car accident",
        "incident_date": "2026-03-15T14:30:00.000+00:00",
        "claim_amount": null,
        "payout_amount": null,
        "transaction_date": null,
        "variant_id": "c97a1111-89f8-5fbe-bc00-544bb019e476",
        "required_documents": {},
        "owner_id": null,
        "assignee_id": null
    }
}
```

{% endtab %}

{% tab title="v2" %}

```json
{
    "data": {
        "id": "3d559069-489f-5564-91d4-ba7627ae5d92",
        "package_id": "51ea41cd-fb00-5688-b07d-82fe3336fba9",
        "claimant_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
        "risk_item_id": "d40ebf8d-efa9-518e-a5a8-7b106ce0ef1a",
        "type": "Auto Insurance",
        "status": "SUBMITTED",
        "uid": "CLM-0001",
        "insurer_claim_number": "INS-0001",
        "internal_claim_number": 69,
        "consent_date": "2026-03-16T05:00:00+00:00",
        "resolution_date": null,
        "assets": [],
        "metadata": {
            "additional_info": "Some additional info"
        },
        "policy_reference": {
            "policy": {
                "id": "e693dbd7-7621-5407-a9e4-5fa0fc44bd67",
                "uid": "POL-0003",
                "version": 1,
                "metadata": {
                    "policy_info": "Additional policy info"
                },
                "policy_number": "PN-0003",
                "total_gross_price": "1 + 1"
            },
            "variant": {
                "id": "c97a1111-89f8-5fbe-bc00-544bb019e476",
                "name": "Basic plan",
                "conditions": "Coverage applies to incidents reported within 30 days.",
                "created_at": "2026-01-10T21:00:41.277415+00:00",
                "exclusions": "Pre-existing damage is not covered.",
                "insurer_id": "94f9e6c6-0b50-5d44-af83-4a11195ba7bf",
                "description": "Basic plan for vehicle damage.",
                "gross_price": "1",
                "pricing_type": "one_time",
                "pricing_rules": {
                    "net_price": "Net price rules"
                },
                "coverage_limits": 0
            },
            "riskItem": {}
        },
        "claimant_data": {
            "id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
            "dob": "1990-05-10T00:00:00+00:00",
            "uid": "USR-0001",
            "name": "Maria Lopez",
            "email": "maria.lopez@example.com",
            "phone": "+593991234501",
            "gender": "FEMALE",
            "address": "Av. 9 de Octubre 100, Guayaquil",
            "group_id": "2ceb1648-18b8-5d01-b614-8d697d282632",
            "metadata": {
                "additional_info": "Some additional info"
            },
            "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
            "company_name": "Andes Logistics S.A.",
            "company_role": "Founder",
            "bank_accounts": [
                {
                    "iban": "EC00EXBK0000001234567890",
                    "country": "EC",
                    "currency": "USD",
                    "bank_name": "Example Bank",
                    "bic_swift": "EXBKECEG",
                    "account_name": "Maria Lopez",
                    "account_type": "Checking",
                    "bank_address": "Av. 9 de Octubre 100, Guayaquil",
                    "account_number": "1234567890",
                    "routing_number": "011000015",
                    "additional_info": "Some additional info"
                }
            ],
            "company_email": "operations@example.com",
            "document_type": "CI",
            "company_address": "Av. 9 de Octubre 100, Guayaquil",
            "document_number": "1700000001",
            "company_identifier": {
                "type": "RUC",
                "value": "1790000001001"
            },
            "company_bank_accounts": [
                {
                    "iban": "EC00EXBK0000001234567890",
                    "country": "EC",
                    "currency": "USD",
                    "bank_name": "Example Bank",
                    "bic_swift": "EXBKECEG",
                    "account_name": "Andes Logistics S.A.",
                    "account_type": "Savings",
                    "bank_address": "Av. 9 de Octubre 100, Guayaquil",
                    "account_number": "1234567890",
                    "routing_number": "011000015",
                    "additional_info": "Some additional info"
                }
            ]
        },
        "incident": {
            "date": "2026-03-15T14:30:00.000Z",
            "details": {
                "description": "I was involved in a car accident.",
                "transaction": {}
            },
            "additional_properties": {},
            "subject": "Car accident",
            "claim_amount": null
        },
        "communications": [],
        "created_at": "2026-03-16T17:18:36.452503+00:00",
        "updated_at": "2026-03-16T17:18:36.452503+00:00",
        "deleted_at": null,
        "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
        "payout_amount": null,
        "transaction_date": null,
        "variant_id": "c97a1111-89f8-5fbe-bc00-544bb019e476",
        "required_documents": {},
        "owner_id": null,
        "assignee_id": null
    }
}
```

{% endtab %}
{% endtabs %}

#### Attributes

| Name                    | Type       | Description                                        |
| ----------------------- | ---------- | -------------------------------------------------- |
| id                      | uuid       | Unique identifier of the claim                     |
| communications          | object \[] | List of communications related to the claim        |
| policy\_reference       | object     | Reference to the associated policy and its details |
| created\_at             | string     | Date and time when the claim was created           |
| updated\_at             | string     | Date and time when the claim was last updated      |
| deleted\_at             | string     | Date and time when the claim was deleted (if any)  |
| risk\_item\_id          | uuid       | Identifier of the related risk item                |
| claimant\_id            | uuid       | Identifier of the claimant                         |
| channel\_id             | uuid       | Identifier of the communication channel            |
| subject                 | string     | Brief description of the claim                     |
| insurer\_claim\_number  | string     | Claim number assigned by the insurer               |
| internal\_claim\_number | number     | Internal claim number for tracking                 |
| status                  | string     | Current status of the claim                        |
| incident\_date          | string     | Date and time of the incident                      |
| resolution\_date        | string     | Date and time when the claim was resolved (if any) |
| claim\_amount           | number     | Amount claimed                                     |
| payout\_amount          | number     | Amount paid by the insurer                         |
| metadata                | object     | Additional metadata for the claim                  |
| assets                  | object \[] | List of assets related to the claim                |
| type                    | string     | Type of insurance claim. Can be null.              |
| consent\_date           | string     | Date when consent was given (if required)          |
| incident                | object     | Details about the incident                         |
| package\_id             | uuid       | Identifier of the related insurance package        |
| transaction\_date       | string     | Date of the related transaction                    |
| uid                     | string     | Unique identifier for the claim (if available)     |
| variant\_id             | uuid       | Identifier of the associated policy variant        |
| claimant\_data          | object     | Personal and contact details of the claimant       |
| required\_documents     | object     | List of required documents for the claim           |
| owner\_id               | uuid       | Identifier of the claim owner                      |
| assignee\_id            | uuid       | Identifier of the person assigned to the claim     |

In v2, `subject` and `claim_amount` are returned inside `incident` instead of at the root, and `incident_date` is not returned.

### Add a communication to a claim

Adds an entry to the communications of a claim and, optionally, changes its status.

<mark style="color:purple;">`PATCH`</mark> `https://app.insurehero.io/api/shield/v2/claims/:claimId`

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Path Parameters

| Name                                      | Type   | Description                                          |
| ----------------------------------------- | ------ | ---------------------------------------------------- |
| claimId<mark style="color:red;">\*</mark> | string | The claim id, or the field selected with `searchBy`. |

#### Query Parameters

| Name     | Type                                 | Description                                       |
| -------- | ------------------------------------ | ------------------------------------------------- |
| searchBy | id \| uid \| internal\_claim\_number | Field used to search for the claim. Default `id`. |

#### Request Body

| Name                                    | Type   | Description                                                                    |
| --------------------------------------- | ------ | ------------------------------------------------------------------------------ |
| entry<mark style="color:red;">\*</mark> | object | Communication to add. See the table below.                                     |
| status                                  | string | New status of the claim: `SUBMITTED`, `APPROVED`, `REJECTED` or `IN PROGRESS`. |

The `entry` object supports these fields; any other field is stored as sent:

| Name                                        | Type    | Description                                                           |
| ------------------------------------------- | ------- | --------------------------------------------------------------------- |
| type<mark style="color:red;">\*</mark>      | string  | Type of communication, for example `note` or `email`.                 |
| sender<mark style="color:red;">\*</mark>    | string  | Who sends the communication.                                          |
| recipient<mark style="color:red;">\*</mark> | string  | Who receives the communication.                                       |
| body                                        | string  | Content of the communication. Required when `type` is `email`.        |
| subject                                     | string  | Subject of the communication. Required when `type` is `email`.        |
| public                                      | boolean | Whether the communication is visible to the claimant. Default `true`. |
| metadata                                    | object  | Additional data. Default `{}`.                                        |

```json
{
    "entry": {
        "type": "note",
        "sender": "agent",
        "recipient": "claimant",
        "body": "We received your documents.",
        "public": true
    },
    "status": "IN PROGRESS"
}
```

#### Example Response

The response contains every communication of the claim, including the new one. InsureHero adds the `date` of the entry.

{% tabs %}
{% tab title="200: OK Updated successfully" %}

```json
{
    "data": {
        "communications": [
            {
                "type": "note",
                "sender": "agent",
                "recipient": "claimant",
                "body": "We received your documents.",
                "public": true,
                "metadata": {},
                "date": "2026-10-12T21:53:14.539Z"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}

```json
{
    "error": "Request contains malformed data",
    "details": "Missing bearer token"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

```json
{
    "error": "Invalid or expired access token",
    "details": "Invalid access token"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Internal validation failed" %}
The claim does not exist in your channel:

```json
{
    "error": "Internal validation failed",
    "details": {
        "code": "PGRST116",
        "message": "Cannot coerce the result to a single JSON object",
        "details": "The result contains 0 rows",
        "hint": ""
    }
}
```

Without `entry`, `details` is `"No entry provided"`. An `email` entry without `body` and `subject`, or an unknown `status`, returns an input validation error. See [Error Handling](https://docs.insurehero.io/shield-api/data-dictionary#error-handling).
{% endtab %}
{% endtabs %}

#### Attributes

| Name           | Type       | Description                                                     |
| -------------- | ---------- | --------------------------------------------------------------- |
| data           | object     | Updated claim data.                                             |
| communications | object \[] | Every communication of the claim, in the order they were added. |

## Additional resources

### Add Event to Claim

Add a new event with asynchronous data to a claim

<mark style="color:green;">`POST`</mark> `https://app.insurehero.io/api/shield/v1/claims/:claimId/events`

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Path Parameters

| Name                                      | Type | Description      |
| ----------------------------------------- | ---- | ---------------- |
| claimId<mark style="color:red;">\*</mark> | uuid | Claim identifier |

#### Request Body

<table><thead><tr><th width="165">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>event_data<mark style="color:red;">*</mark></td><td>object</td><td>Data of the event. <code>start_date</code> and <code>end_date</code> (ISO 8601 date-time), <code>amountPaid</code> (number) and <code>eventType</code> (string) are required. Any other key is stored as sent.</td></tr><tr><td>metadata</td><td>object</td><td>Additional data to include in the event. Defaults to <code>{}</code>.</td></tr><tr><td>uid</td><td>string</td><td>Identifier of the event in your system (1 to 64 characters).</td></tr></tbody></table>

#### Example response

{% tabs %}
{% tab title="201: Created Created successfully" %}

```json
{
    "data": {
        "id": "a5c2034e-f96a-5b78-87f8-7242485a8983",
        "claim_id": "e7f2703f-6ef5-581a-b2aa-13088b55a1b3",
        "metadata": {
            "additional_properties": "additional properties"
        },
        "event_data": {
            "start_date": "2026-03-15T00:00:00.000Z",
            "end_date": "2026-06-15T00:00:00.000Z",
            "amountPaid": 500,
            "eventType": "PAYMENT_RECEIVED"
        },
        "uid": null
    }
}
```

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}

{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

{% endtab %}

{% tab title="422: Unprocessable Entity Internal validation failed" %}
The claim does not exist in your channel:

```json
{
    "error": "Internal validation failed",
    "details": "Claim does not exist in this channel"
}
```

A body that does not match the schema (for example, without `amountPaid` or `eventType` in `event_data`) also returns `422`, with the validation issues in `details`.
{% endtab %}
{% endtabs %}

#### Attributes

| Name        | Type   | Description                                          |
| ----------- | ------ | ---------------------------------------------------- |
| id          | uuid   | Unique identifier of the event.                      |
| claim\_id   | uuid   | Identifier of the claim.                             |
| metadata    | object | Additional metadata related to the event.            |
| event\_data | object | Details of the event, as sent in the request.        |
| start\_date | string | Event start date.                                    |
| end\_date   | string | Event end date.                                      |
| amountPaid  | number | Amount paid in the event.                            |
| eventType   | string | Type of event.                                       |
| uid         | string | Identifier of the event in your system. Can be null. |

### Get Claim events

<mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v1/claims/:claimId/events`

Events in a claim

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Path Parameters

| Name                                      | Type | Description                                    |
| ----------------------------------------- | ---- | ---------------------------------------------- |
| claimId<mark style="color:red;">\*</mark> | uuid | The id of the claim associated with the events |

#### Example response

{% tabs %}
{% tab title="200: OK Retrieved successfully" %}

```json
{
    "data": {
        "id": "e7f2703f-6ef5-581a-b2aa-13088b55a1b3",
        "package_id": "f68da85b-6903-5f08-be32-0a48d97b3f61",
        "subject": "Trip cancelled before departure",
        "claimant_id": "c217cdfc-10a2-5a6e-82f0-99e659284c82",
        "risk_item_id": "ac13f412-a5e8-5614-98a5-f040dfaa4b8c",
        "variant_id": "82797f53-d10d-5d19-98f3-46fec38dd377",
        "type": "Refund Protection",
        "status": "SUBMITTED",
        "uid": null,
        "insurer_claim_number": null,
        "internal_claim_number": 164,
        "incident_date": "2026-03-14T20:00:00+00:00",
        "consent_date": null,
        "resolution_date": null,
        "assets": [],
        "incident": {
            "date": "2026-03-14T20:00:00.000Z",
            "details": {
                "transaction": {}
            },
            "additional_properties": {}
        },
        "claim_amount": null,
        "communications": [],
        "metadata": {},
        "policy_reference": {
            "policy": {
                "id": "300e2bb7-f7f7-546a-aeb9-4aed1411b0ba",
                "uid": "POL-0004",
                "version": 5,
                "metadata": {},
                "policy_number": "PN-0004",
                "total_gross_price": "0.1*total_reservation_value + 0.1*total_reservation_value + 0.07 + 0.015 + 0.015 + 0.07 + 0.015 + 0.015"
            },
            "variant": {
                "id": "82797f53-d10d-5d19-98f3-46fec38dd377",
                "name": "Cancellation for any reason 100%",
                "markup": [
                    {
                        "owner": "insurer",
                        "taxes": [
                            {
                                "name": "VAT",
                                "rate": 0.15
                            }
                        ],
                        "net_price": "0",
                        "gross_price": "0.07"
                    },
                    {
                        "owner": "platform",
                        "taxes": [
                            {
                                "name": "VAT",
                                "rate": 0.15
                            }
                        ],
                        "net_price": "0",
                        "gross_price": "0.015"
                    },
                    {
                        "owner": "channel",
                        "taxes": [
                            {
                                "name": "VAT",
                                "rate": 0.15
                            }
                        ],
                        "net_price": "0",
                        "gross_price": "0.015"
                    }
                ],
                "conditions": "Cancellation for any reason up to 30 minutes before departure.",
                "created_at": "2026-01-05T17:55:21.978517+00:00",
                "exclusions": "Less than 30 minutes before departure.\n",
                "description": "Credit for a ticket change."
            },
            "riskItem": {
                "id": "ac13f412-a5e8-5614-98a5-f040dfaa4b8c",
                "end_date": "2026-03-17T02:50:00+00:00",
                "metadata": {},
                "start_date": "2026-03-10T18:07:48+00:00",
                "beneficiaries": [
                    {
                        "email": "carlos.andrade@example.com",
                        "phone": "+593991234502",
                        "last_name": "Andrade",
                        "first_name": "Carlos",
                        "identifier_type": "National ID",
                        "identifier_value": "1700000002"
                    }
                ],
                "insured_subject": {
                    "ticket_id": "TKT-0001",
                    "arrival_city": "Guayaquil Terminal",
                    "departure_city": "Manta Terminal",
                    "number_tickets": 2,
                    "reservation_id": "TKT-0001",
                    "identifier_type": "ticket_id",
                    "cooperativa_name": "Pacific Transport Co.",
                    "identifier_value": "TKT-0001",
                    "arrival_date_time": "2026-03-16T07:20:00.000Z",
                    "purchase_date_time": "2026-03-10T13:07:48-05:00",
                    "departure_date_time": "2026-03-16T03:20:00.000Z",
                    "total_reservation_value": 15.4
                }
            }
        },
        "claimant_data": {
            "id": "c217cdfc-10a2-5a6e-82f0-99e659284c82",
            "dob": null,
            "uid": "USR-0002",
            "name": "Carlos Andrade",
            "email": "carlos.andrade@example.com",
            "phone": "+593991234502",
            "gender": null,
            "address": null,
            "group_id": null,
            "metadata": {},
            "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
            "company_name": null,
            "company_role": null,
            "bank_accounts": [
                {
                    "iban": "EC00EXBK0000001234567890",
                    "country": "EC",
                    "currency": "USD",
                    "bank_name": "Example Bank",
                    "bic_swift": "EXBKECEG",
                    "account_name": "Carlos Andrade",
                    "account_type": "Checking",
                    "bank_address": "Av. 9 de Octubre 100, Guayaquil",
                    "account_number": "1234567890",
                    "routing_number": "011000015",
                    "additional_info": "Personal account"
                }
            ],
            "company_email": null,
            "document_type": null,
            "company_address": null,
            "document_number": null,
            "company_identifier": null,
            "company_bank_accounts": null
        },
        "claims_events": [
            {
                "id": "a5c2034e-f96a-5b78-87f8-7242485a8983",
                "claim_id": "e7f2703f-6ef5-581a-b2aa-13088b55a1b3",
                "metadata": {},
                "event_data": {
                    "start_date": "2026-03-15T00:00:00.000Z",
                    "end_date": "2026-06-15T00:00:00.000Z",
                    "amountPaid": 500,
                    "eventType": "PAYMENT_RECEIVED"
                },
                "uid": null
            },
            {
                "id": "2893f360-763a-578e-b001-677197d08028",
                "claim_id": "e7f2703f-6ef5-581a-b2aa-13088b55a1b3",
                "metadata": {},
                "event_data": {
                    "start_date": "2026-03-15T00:00:00.000Z",
                    "end_date": "2026-06-15T00:00:00.000Z",
                    "amountPaid": 500,
                    "eventType": "PAYMENT_RECEIVED"
                },
                "uid": null
            },
            {
                "id": "4e54a59f-e9ad-527c-88d4-6fe3ca05dbfb",
                "claim_id": "e7f2703f-6ef5-581a-b2aa-13088b55a1b3",
                "metadata": {},
                "event_data": {
                    "start_date": "2026-03-15T00:00:00.000Z",
                    "end_date": "2026-06-15T00:00:00.000Z",
                    "amountPaid": 500,
                    "eventType": "PAYMENT_RECEIVED"
                },
                "uid": null
            },
            {
                "id": "8154d6c1-30f5-5d39-8699-8a63360e6a02",
                "claim_id": "e7f2703f-6ef5-581a-b2aa-13088b55a1b3",
                "metadata": {},
                "event_data": null,
                "uid": null
            }
        ]
    }
}
```

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}

{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

{% endtab %}

{% tab title="422: Unprocessable Entity Internal validation failed" %}
The claim does not exist in your channel:

```json
{
    "error": "Internal validation failed",
    "details": "Claim does not exist in this channel"
}
```

{% endtab %}
{% endtabs %}

#### Attributes

| Name                    | Type       | Description                                        |
| ----------------------- | ---------- | -------------------------------------------------- |
| id                      | uuid       | Unique identifier of the claim                     |
| package\_id             | uuid       | Identifier of the related insurance package        |
| subject                 | string     | Brief description of the claim                     |
| claimant\_id            | uuid       | Identifier of the claimant                         |
| risk\_item\_id          | uuid       | Identifier of the related risk item                |
| variant\_id             | uuid       | Identifier of the associated policy variant        |
| type                    | string     | Type of insurance claim. Can be null.              |
| status                  | string     | Current status of the claim                        |
| uid                     | string     | Unique identifier for the claim (if available)     |
| insurer\_claim\_number  | string     | Claim number assigned by the insurer               |
| internal\_claim\_number | number     | Internal claim number for tracking                 |
| incident\_date          | string     | Date and time of the incident                      |
| consent\_date           | string     | Date when consent was given (if required)          |
| resolution\_date        | string     | Date and time when the claim was resolved (if any) |
| assets                  | object \[] | List of assets related to the claim                |
| incident                | object     | Details about the incident                         |
| claim\_amount           | number     | Amount claimed                                     |
| communications          | object \[] | List of communications related to the claim        |
| metadata                | object     | Additional metadata for the claim                  |
| policy\_reference       | object     | Reference to the associated policy and its details |
| claimant\_data          | object     | Personal and contact details of the claimant       |
| claims\_events          | object \[] | List of events associated with the claim           |

**Claim event**

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| id          | uuid   | Unique identifier of the event.                                                          |
| claim\_id   | uuid   | Identifier of the claim.                                                                 |
| metadata    | object | Additional metadata related to the event.                                                |
| event\_data | object | Data of the event. Free JSON: its keys depend on how the event was created. Can be null. |
| uid         | string | Identifier of the event in your system. Can be null.                                     |

## Post a Claim without User-Authorization token

To create a claim without User-Authorization token, you will need to contact our support team. Once you have requested authorization and it has been granted, you will be provided with the specific instructions to carry out this action.

You can still use the method of sending the token and not sending the claimant\_email even if your channel has permissions.

`claimant_email` is only taken into account in channels enabled for handshake. In any other channel it is ignored and the request still needs the `User-Authorization` header; without it the response is `400` with details `"Missing user token"`.

{% tabs %}
{% tab title="v1" %} <mark style="color:green;">`POST`</mark> `https://app.insurehero.io/api/shield/v1/claims`
{% endtab %}

{% tab title="v2" %} <mark style="color:green;">`POST`</mark> `https://app.insurehero.io/api/shield/v2/claims`
{% endtab %}
{% endtabs %}

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Request Body

{% tabs %}
{% tab title="v1" %}

| Name                                              | Type         | Description                                            |
| ------------------------------------------------- | ------------ | ------------------------------------------------------ |
| risk\_item\_id<mark style="color:red;">\*</mark>  | string       | Item being claimed                                     |
| claimant\_email<mark style="color:red;">\*</mark> | string       | Claimant email                                         |
| variant\_id<mark style="color:red;">\*</mark>     | string       | The coverage variant chosen for this claim             |
| metadata                                          | object       | Additional data of this claim                          |
| subject<mark style="color:red;">\*</mark>         | string       | A sentence describing the claim (10 to 255 characters) |
| incident<mark style="color:red;">\*</mark>        | IncidentType | Incident data                                          |
| claim\_amount                                     | number       | A positive number requested to be paid                 |

The description of the incident goes in `incident.details.description`. A `description` field at the root of the body is ignored.
{% endtab %}

{% tab title="v2" %}

| Name                                              | Type         | Description                                |
| ------------------------------------------------- | ------------ | ------------------------------------------ |
| risk\_item\_uid<mark style="color:red;">\*</mark> | string       | Item being claimed                         |
| claimant\_email<mark style="color:red;">\*</mark> | string       | Claimant Email                             |
| variant\_uid<mark style="color:red;">\*</mark>    | string       | The coverage variant chosen for this claim |
| incident<mark style="color:red;">\*</mark>        | IncidentType | Incident data.                             |
| metadata                                          | object       | Additional data of this claim              |

In v2, `subject`, `description` and `claim_amount` go inside `incident`. Fields at the root of the body other than the ones listed here are not stored.
{% endtab %}
{% endtabs %}

**Types of responses**

{% tabs %}
{% tab title="201: Created Created successfully" %}

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}
Neither a valid user token nor `claimant_email` was sent:

```json
{
    "error": "Request contains malformed data",
    "details": "Missing user token and claimant_email"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

{% endtab %}

{% tab title="422: Unprocessable Entity Internal validation failed" %}
A body that is not valid JSON or does not match the schema returns `422` with the validation issues in `details`. Business rules (for example, an unregistered claimant or a claimant who is not authorized for the risk item) also return `422`.
{% endtab %}
{% endtabs %}

#### Example Response 201

{% tabs %}
{% tab title="v1 " %}

```json
{
    "data": {
        "id": "82802426-7a16-5104-b5ab-273bb941d782",
        "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd",
        "subject": "Cargo stolen during delivery",
        "claimant_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
        "risk_item_id": "371dcc84-f8d7-54e0-9f2e-2599950e7297",
        "variant_id": "294594d1-4100-577f-9222-46dd8dc69ab2",
        "type": "Property Insurance",
        "status": "SUBMITTED",
        "uid": null,
        "insurer_claim_number": null,
        "internal_claim_number": 88,
        "incident_date": "2026-03-15T14:30:00.000+00:00",
        "consent_date": null,
        "resolution_date": null,
        "assets": [],
        "incident": {
            "date": "2026-03-15T14:30:00.000Z",
            "details": {
                "transaction": {
                    "date": "2026-03-10T14:48:00.000Z",
                    "amount": 150,
                    "method": "VISA",
                    "retailer": "Example Store",
                    "description": "Transaction description"
                },
                "description": "The cargo was stolen during a scheduled delivery stop. The incident occurred while the cargo was en route to its next destination."
            },
            "additional_properties": {
                "claim_type": "THEFT",
                "fast_track": true,
                "incident_coords": "-0.1807, -78.4678"
            }
        },
        "claim_amount": null,
        "communications": [],
        "metadata": {},
        "policy_reference": {
            "policy": {
                "id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c",
                "uid": "POL-0001",
                "version": 2,
                "metadata": {},
                "policy_number": "PN-0001",
                "total_gross_price": "535253 + 125125"
            },
            "variant": {
                "id": "294594d1-4100-577f-9222-46dd8dc69ab2",
                "name": "Gold plan",
                "markup": [
                    {
                        "owner": "channel",
                        "taxes": [
                            {
                                "name": "VAT",
                                "rate": 0.15
                            }
                        ],
                        "net_price": null,
                        "gross_price": "125125"
                    }
                ],
                "conditions": "Coverage applies to incidents reported within 30 days.",
                "created_at": "2026-01-10T20:59:36.0742+00:00",
                "exclusions": "Pre-existing damage is not covered.",
                "description": null,
                "coverage_id": "c98625a4-bff7-5485-90b4-6e45758bccee",
                "insurer_id": null
            },
            "riskItem": {
                "id": "371dcc84-f8d7-54e0-9f2e-2599950e7297",
                "start_date": "2026-03-01T05:00:00+00:00",
                "end_date": "2027-03-01T05:00:00+00:00",
                "insured_subject": {
                    "identifier_value": "1700000002",
                    "identifier_type": "CI"
                },
                "metadata": {},
                "beneficiaries": []
            }
        },
        "claimant_data": {
            "id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
            "dob": "1990-05-10T00:00:00+00:00",
            "uid": "USR-0001",
            "name": "Maria Lopez",
            "email": "maria.lopez@example.com",
            "phone": "+593991234501",
            "gender": "FEMALE",
            "address": "Av. 9 de Octubre 100, Guayaquil",
            "group_id": "2ceb1648-18b8-5d01-b614-8d697d282632",
            "metadata": {},
            "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
            "company_name": "Andes Logistics S.A.",
            "company_role": "Founder",
            "bank_accounts": null,
            "company_email": "operations@example.com",
            "document_type": "CI",
            "company_address": "Av. 9 de Octubre 100, Guayaquil",
            "document_number": "1700000001",
            "company_identifier": null,
            "company_bank_accounts": null
        }
    }
}
```

{% endtab %}

{% tab title="v2" %}

```json
{
    "data": {
        "id": "5dac73e7-b568-5ad4-bed2-3ce06f1c47e0",
        "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd",
        "claimant_id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
        "risk_item_id": "371dcc84-f8d7-54e0-9f2e-2599950e7297",
        "variant_id": "294594d1-4100-577f-9222-46dd8dc69ab2",
        "type": "Property Insurance",
        "status": "SUBMITTED",
        "uid": null,
        "insurer_claim_number": null,
        "internal_claim_number": 89,
        "consent_date": null,
        "resolution_date": null,
        "assets": [],
        "metadata": {},
        "incident": {
            "date": "2026-03-15T14:30:00.000Z",
            "subject": "Cargo stolen during delivery",
            "claim_amount": 500,
            "description": "The cargo was stolen during a scheduled delivery stop.",
            "property_one": true
        },
        "communications": []
    }
}
```

{% endtab %}
{% endtabs %}

**IncidentType**

{% tabs %}
{% tab title="v1" %}

| Value                                     | Type                        |
| ----------------------------------------- | --------------------------- |
| date<mark style="color:red;">\*</mark>    | date                        |
| summary                                   | string (5 to 30 characters) |
| details<mark style="color:red;">\*</mark> | DetailsType                 |
| additional\_properties                    | JSON                        |

`additional_properties` is validated against the claim schema of the selected variant.

**DetailsType**

| Value                                         | Type            |
| --------------------------------------------- | --------------- |
| transaction<mark style="color:red;">\*</mark> | TransactionType |
| description                                   | string          |

**TransactionType**

| Value        | Type                                        |
| ------------ | ------------------------------------------- |
| date         | string                                      |
| amount       | number                                      |
| method       | VISA, MASTERCARD, AMEX, DISCOVER o TRANSFER |
| retailer     | string                                      |
| description  | string                                      |
| {% endtab %} |                                             |

{% tab title="v2" %}

| Value                                     | Type                          |
| ----------------------------------------- | ----------------------------- |
| subject<mark style="color:red;">\*</mark> | string (10 to 255 characters) |
| date<mark style="color:red;">\*</mark>    | date                          |
| description                               | string                        |
| claim\_amount                             | number                        |
| transaction                               | TransactionType               |

Any other key inside `incident` is stored as an additional property of the incident and validated against the claim schema of the selected variant.
{% endtab %}
{% endtabs %}

#### Additional Attributes

#### Claimant data

<table><thead><tr><th width="224">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>claimant_data</td><td>object</td><td>Information about the claimant.</td></tr><tr><td>id</td><td>uuid</td><td>Unique identifier of the claimant.</td></tr><tr><td>dob</td><td>string</td><td>Date of birth of the claimant.</td></tr><tr><td>uid</td><td>string</td><td>Unique user identifier.</td></tr><tr><td>name</td><td>string</td><td>Full name of the claimant.</td></tr><tr><td>email</td><td>string</td><td>Email address of the claimant.</td></tr><tr><td>phone</td><td>string</td><td>Phone number of the claimant.</td></tr><tr><td>gender</td><td>string</td><td>Gender of the claimant.</td></tr><tr><td>address</td><td>string</td><td>Address of the claimant.</td></tr><tr><td>group_id</td><td>uuid</td><td>Group identifier associated with the claimant.</td></tr><tr><td>metadata</td><td>object</td><td>Additional metadata related to the claimant.</td></tr><tr><td>channel_id</td><td>uuid</td><td>Identifier of the communication channel.</td></tr><tr><td>company_name</td><td>string</td><td>Name of the company associated with the claimant.</td></tr><tr><td>company_role</td><td>string</td><td>Role of the claimant within the company.</td></tr><tr><td>bank_accounts</td><td>object []</td><td>List of bank accounts associated with the claimant.</td></tr><tr><td>company_email</td><td>string</td><td>Corporate email of the claimant.</td></tr><tr><td>document_type</td><td>string</td><td>Type of identification document.</td></tr><tr><td>company_address</td><td>string</td><td>Address of the company associated with the claimant.</td></tr><tr><td>document_number</td><td>string</td><td>Identification document number.</td></tr><tr><td>company_identifier</td><td>object</td><td>Company identification details.</td></tr><tr><td>company_bank_accounts</td><td>object []</td><td>List of corporate bank accounts.</td></tr></tbody></table>

#### Policy

| Name                | Type   | Description                                                 |
| ------------------- | ------ | ----------------------------------------------------------- |
| policy              | object | Contains information about the insurance policy.            |
| id                  | uuid   | Unique identifier of the policy.                            |
| uid                 | string | Unique identifier of the policy.                            |
| version             | number | Version number of the policy.                               |
| metadata            | object | Additional metadata related to the policy.                  |
| policy\_number      | string | Policy number assigned by the insurer.                      |
| total\_gross\_price | string | Total gross price of the policy (can include calculations). |

#### Taxes

| Name  | Type       | Description                          |
| ----- | ---------- | ------------------------------------ |
| taxes | object \[] | List of taxes applied to the policy. |
| name  | string     | Name of the tax.                     |
| rate  | number     | Tax rate or amount applied.          |

#### Markup

| Name         | Type       | Description                               |
| ------------ | ---------- | ----------------------------------------- |
| markup       | object \[] | List of markups applied to the policy.    |
| owner        | string     | Entity responsible for the markup.        |
| taxes        | object \[] | List of taxes associated with the markup. |
| net\_price   | string     | Net price of the markup.                  |
| gross\_price | string     | Gross price of the markup.                |

#### Variant

| Name         | Type       | Description                            |
| ------------ | ---------- | -------------------------------------- |
| variant      | object     | Variant information.                   |
| id           | string     | Unique identifier.                     |
| name         | string     | Name of the variant.                   |
| markup       | object \[] | List of markups applied.               |
| conditions   | string     | Conditions associated with variant.    |
| created\_at  | string     | Creation timestamp.                    |
| exclusions   | string     | Exclusions for the variant.            |
| description  | string     | Description.                           |
| coverage\_id | uuid       | Identifier of the associated coverage. |
| insurer\_id  | string     | Identifier of the insurer.             |

#### Risk item

| Name             | Type       | Description                            |
| ---------------- | ---------- | -------------------------------------- |
| riskItem         | object     | Risk item information.                 |
| id               | uuid       | Unique identifier of the risk item.    |
| start\_date      | string     | Start date of the coverage.            |
| end\_date        | string     | End date of the coverage.              |
| insured\_subject | object     | Information about the insured subject. |
| metadata         | object     | Additional metadata of the risk item.  |
| beneficiaries    | object \[] | List of beneficiaries.                 |