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. 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

Method	Endpoint
GET	https://api.insurehero.io/api/shield/v1/users/:userId
GET	https://api.insurehero.io/api/shield/v1/users/by-email/:userEmail
GET	https://api.insurehero.io/api/shield/v1/users/:userId/risk-items
GET	https://api.insurehero.io/api/shield/v1/risk-items/:riskItemId/variants
POST	https://app.insurehero.io/api/shield/v1/claims
GET	https://api.insurehero.io/api/shield/v1/users/:userId/claims
GET	https://app.insurehero.io/api/shield/v1/claims
GET	https://app.insurehero.io/api/shield/v1/claims/:claimId
POST	https://app.insurehero.io/api/shield/v1/claims
POST	https://app.insurehero.io/api/shield/v1/claims/:claimId/events
GET	https://app.insurehero.io/api/shield/v1/claims/:claimId/events

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.

GET https://api.insurehero.io/api/shield/v1/users/:userId

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
userId*	string	Either user_id or uid

Query Parameters

Name	Type	Description
searchBy	id | uid	Field use to search for a matching user. Default to 'id'

Or using its email.

GET https://api.insurehero.io/api/shield/v1/users/by-email/:userEmail

Path Parameters

Name	Type	Description
userEmail*	string	The user email

Example Response

200: OK Retrieved successfully

{
    "data": {
        "id": "6e83de1e-af92-4604-99d8-eaf9f198e8a9",
        "channel_id": "fc94d4a1-f834-481d-a6b2-138b823389c8",
        "email": "[e-mail]",
        "first_name": "John PROD",
        "last_name": "Doe",
        "phone": "098 321 3123",
        "uid": "USER1",
        "gender": "MALE",
        "dob": "2024-04-01T05:00:00+00:00",
        "address": "Jr Junin 550",
        "document_type": "RUC",
        "document_number": "0931339568",
        "bank_accounts": [
            {
                "account_name": "John Doe",
                "bank_name": "Global Bank",
                "account_number": "2313213123123",
                "bic_swift": "GBL12345",
                "iban": "123123123",
                "routing_number": "011000138",
                "country": "3b67c9ca-fd42-4c37-a53b-8aabfc90ee10",
                "currency": "8d4ddf57-f5cf-4b03-83f9-97e9abb8ee13",
                "account_type": "Checking",
                "bank_address": "example",
                "additional_info": "example"
            }
        ],
        "company_name": "Doe Enterprises",
        "company_role": "Founder",
        "company_email": "[e-mail]",
        "company_identifier": {
            "type": "RUC",
            "value": "12312321321321"
        },
        "company_address": "Jr Junin 550",
        "company_bank_accounts": [
            {
                "account_name": "Doe Enterprises",
                "bank_name": "Business Bank",
                "account_number": "987654321",
                "bic_swift": "BSNS12345",
                "iban": "GB33BUKB20201555555555",
                "routing_number": "011000015",
                "country": "3b67c9ca-fd42-4c37-a53b-8aabfc90ee10",
                "currency": "8d4ddf57-f5cf-4b03-83f9-97e9abb8ee13",
                "account_type": "Savings",
                "bank_address": "Jr Junin 550",
                "additional_info": "Branch: Main"
            }
        ],
        "group_id": "8049cfed-c4fb-4114-8c69-457d405eeb10",
        "metadata": {}
    }
}

400: Bad Request Request contains malformed data

{}

401: Unauthorized Invalid or expired access token

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

Name	Type	Description
type	string	Type of company identifier.
value	string	The actual identifier value.

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.

GET https://api.insurehero.io/api/shield/v1/users/:userId/risk-items

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
userId*	string	Either user_id or uid

Query Parameters

Name	Type	Description
searchBy	id | uid	Field use to search for a matching user. Default to 'id'

Example Response

200: OK Retrieved successfully

{
    "data": [
        {
            "id": "5254x367-ba46-4549-803b-0c22b35ad99e",
            "policy_id": "c12a9583-9a58-4b0c-b332-21499780a35b",
            "authorized_claimants": [
                {
                    "email": "[e-mail]"
                }
            ],
            "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
            "start_date": "2024-05-30T03:00:00+00:00",
            "end_date": "2024-05-31T03:00:00+00:00",
            "beneficiaries": [
                {
                    "email": null
                }
            ],
            "insured_subject": {
                "identifier_value": "example",
                "identifier_type": "example"
            },
            "status": "ACTIVE",
            "uid": UIDEXAMPLE,
            "assets": [],
            "metadata": {}
        }
    ]
}

400: Bad Request Request contains malformed data

{}

401: Unauthorized Invalid or expired access token

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

GET https://api.insurehero.io/api/shield/v1/risk-items/:riskItemId/variants

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
riskItemId*	string	The risk item ID

Example Response

200: OK Retrieved successfully

{
    "data": [
        {
            "id": "c8038056-91d5-4c61-91d5-578f8b482086",
            "uid": "UIDEXAMPLE",
            "name": "Variant example",
            "channel_id": "fc54d4a1-f834-481d-a6b2-138b823389c8",
            "conditions": "Conditions example",
            "created_at": "2024-05-27T20:59:36.0742+00:00",
            "deductible": null,
            "deleted_at": null,
            "exclusions": "Exclusions example",
            "updated_at": "2024-05-27T21:00:04.906+00:00",
            "coverage_id": "958b552b-c72b-455a-8142-3062f7c8c7b7",
            "description": null,
            "gross_price": "535253",
            "claim_schema": {}
        }
    ]
}

400: Bad Request Request contains malformed data

{}

401: Unauthorized Invalid or expired access token

Attributes

Name	Type	Description
id	uuid	Unique identifier of the variant.
uid	string	User identifier.
name	string	Name of the variant.
channel_id	uuid	Identifier of the channel.
conditions	string	Conditions associated with the variant.
created_at	string	Date and time of creation.
deductible	string	Deductible amount.
deleted_at	string	Deletion timestamp.
exclusions	string	Exclusions related to the variant.
updated_at	string	Last update timestamp.
coverage_id	uuid	Identifier of the associated coverage.
description	string	Description of the variant.
gross_price	string	Gross price of the variant.
claim_schema	jsonb	Claim schema for this variant.

Create a Claim

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

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.

Create a new claim for a risk item

v1

POST https://app.insurehero.io/api/shield/v1/claims

v2

POST https://app.insurehero.io/api/shield/v2/claims

Headers

Name	Type	Description
Authorization*	string	Bearer access token
User-Authorization*	string	User unique token to create claims

Request Body

v1

Name	Type	Description
risk_item_id*	string	Item being claimed
variant_id*	string	The coverage variant chosen for this claim
metadata	object	Additional data of this claim
subject*	string	A sentence describing the claim
incident*	IncidentType	Incident data
claim_amount	number	A positive number requested to be paid

v2

Name	Type	Description
risk_item_uid*	string	Item being claimed
variant_uid*	string	The coverage variant chosen for this claim
incident*	IncidentType	Incident data.
metadata	object	Additional data of this claim

Example Response 201

v1

{
    "data": {
        "id": "6fa8c194-69b9-4d84-8fa8-495d06acccef",
        "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
        "subject": "Subject Example",
        "claimant_id": "6063125e-1626-49ea-87ec-ed7bd756ea70",
        "risk_item_id": "5254e367-ba46-4549-803b-0c22b35ad99e",
        "variant_id": "c7038056-91d5-4c61-91d5-578f8b482086",
        "type": "Property Insurance",
        "status": "SUBMITTED",
        "uid": null,
        "insurer_claim_number": null,
        "internal_claim_number": 88,
        "incident_date": "2025-01-19T02:06:34.539+00:00",
        "consent_date": null,
        "resolution_date": null,
        "assets": [],
        "incident": {
            "date": "2025-01-19T02:06:34.539Z",
            "details": {
                "transaction": {
                    "date": "2023-05-20T14:48:00.000Z",
                    "amount": 150,
                    "method": "VISA",
                    "retailer": "Retailer Name",
                    "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": "ROBO",
                "fast_track": true,
                "incident_coords": "-0.180653, -78.467838"
            }
        },
        "claim_amount": null,
        "communications": [],
        "metadata": {},
        "policy_reference": {
            "policy": {
                "id": "c42a9583-9a58-4b0c-b332-21499780a35b",
                "uid": "c42a9583-9a58-4b0c-b332-21499780a35b",
                "version": 2,
                "metadata": {},
                "policy_number": "46",
                "total_gross_price": "535253 + 125125"
            },
            "variant": {
                "id": "c7038056-91d5-4c61-91d5-578f8b482086",
                "name": "Variant name example",
                "taxes": [
                    {
                        "name": "tax",
                        "rate": 215125
                    }
                ],
                "markup": [
                    {
                        "owner": "channel",
                        "taxes": [
                            {
                                "name": "Cobertura",
                                "rate": 4124124
                            }
                        ],
                        "net_price": null,
                        "gross_price": "125125"
                    }
                ],
                "conditions": "Conditions example",
                "created_at": "2024-05-27T20:59:36.0742+00:00",
                "exclusions": "Exclusions example",
                "description": null,
                "gross_price": "535253",
                "pricing_type": "one_time",
                "pricing_rules": {
                    "net_price": null
                },
                "coverage_limits": 0
            },
            "riskItem": {}
        },
        "claimant_data": {
            "id": "6063125e-1626-49ea-87ec-ed7bd756ea70",
            "dob": null,
            "uid": "[e-mail]",
            "name": "John Doe",
            "email": "[e-mail]",
            "phone": "0386541656035235",
            "gender": null,
            "address": "Address example",
            "group_id": null,
            "metadata": {},
            "channel_id": "fc94d4a1-f834-481d-a6b2-138b823389c8",
            "company_name": null,
            "company_role": null,
            "bank_accounts": null,
            "company_email": null,
            "document_type": null,
            "company_address": null,
            "document_number": null,
            "company_identifier": null,
            "company_bank_accounts": null
        }
    }
}

v2

{
    "data": {
        "id": "4202e93a-1d15-4a99-ae3e-de267a29e67d",
        "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
        "claimant_id": "6063125e-1626-49ea-87ec-ed7bd756ea70",
        "risk_item_id": "5254e367-ba46-4549-803b-0c22b35ad99e",
        "variant_id": "c7038056-91d5-4c61-91d5-578f8b482086",
        "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": "2025-01-19T02:06:34.539Z",
            "subject": "Subject Example",
            "claim_amount": 1999,
            "description": "Incident description.",
            // Additional properties
            "property_one": true
        },
        "communications": []
    }
}

IncidentType

v1

Value	Type
date*	date
summary	string
details*	DetailsType
adittional_properties*	JSON

DetailsType

Value	Type
transaction*	TransactionType
description	string

TransactionType

Value	Type
date	string
amount	number
method	VISA, MASTERCARD, AMEX, DISCOVER o TRANSFER
retailer	string
description	string

v2

Value	Type
subject*	string
date*	date
description	string
claim_amount	number

User claims

Fetch all claims from a given user

GET https://api.insurehero.io/api/shield/v1/users/:userId/claims

Path Parameters

Name	Type	Description
userId*	string	Either user_id or uid

Query Parameters

Name	Type	Description
searchBy	id | uid	Field use to search for a matching user. Default to 'id'

Headers

Name	Type	Description
Authorization*	string	Bearer access token

200: OK Retrieved successfully

{
    "data": [
        {
            "id": "12345678-1234-1234-1234-1234567890ab",
            "package_id": "87654321-4321-4321-4321-0987654321ba",
            "subject": "Car accident",
            "claimant_id": "11223344-5566-7788-99aa-bbccddeeff00",
            "risk_item_id": "aabbccdd-eeff-1122-3344-556677889900",
            "variant_id": "ffeeddcc-bbaa-9988-7766-554433221100",
            "type": "Car Insurance",
            "status": "SUBMITTED",
            "uid": null,
            "insurer_claim_number": null,
            "internal_claim_number": 1,
            "incident_date": "2025-01-19T02:06:34.539+00:00",
            "consent_date": null,
            "resolution_date": null,
            "assets": [],
            "incident": {
                "date": "2025-01-19T02:06:34.539Z",
                "details": {
                    "transaction": {
                        "date": "2023-05-20T14:48:00.000Z",
                        "amount": 100,
                        "method": "VISA",
                        "retailer": "Retail 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": "37.7749, -122.4194"
                }
            },
            "claim_amount": null,
            "communications": [],
            "metadata": {},
            "policy_reference": {
                "policy": {
                    "id": "99887766-5544-3322-1100-aabbccddeeff",
                    "uid": "99887766-5544-3322-1100-aabbccddeeff",
                    "version": 1,
                    "metadata": {},
                    "policy_number": "12345",
                    "total_gross_price": "500.00"
                },
                "variant": {
                    "id": "ffeeddcc-bbaa-9988-7766-554433221100",
                    "name": "Standard Coverage",
                    "taxes": [
                        {
                            "name": "Sales Tax",
                            "rate": 8.5
                        }
                    ],
                    "markup": [
                        {
                            "owner": "insurance_company",
                            "taxes": [
                                {
                                    "name": "Service Fee",
                                    "rate": 2.5
                                }
                            ],
                            "net_price": 450,
                            "gross_price": "500.00"
                        }
                    ],
                    "conditions": "Coverage includes collision and liability.",
                    "created_at": "2024-05-27T20:59:36.0742+00:00",
                    "exclusions": "Does not cover intentional damage or wear and tear.",
                    "description": "Standard car insurance coverage.",
                    "gross_price": "500.00",
                    "pricing_type": "one_time",
                    "pricing_rules": {
                        "net_price": 450
                    },
                    "coverage_limits": 10000
                },
                "riskItem": {}
            },
            "claimant_data": {
                "id": "11223344-5566-7788-99aa-bbccddeeff00",
                "dob": "1985-06-15",
                "uid": "[e-mail]",
                "name": "John Doe",
                "email": "[e-mail]",
                "phone": "123-456-7890",
                "gender": "male",
                "address": "123 Main St, Anytown, USA",
                "group_id": null,
                "metadata": {},
                "channel_id": "1122-3344-5566-7788",
                "company_name": null,
                "company_role": null,
                "bank_accounts": null,
                "company_email": null,
                "document_type": "passport",
                "company_address": null,
                "document_number": "A12345678",
                "company_identifier": null,
                "company_bank_accounts": null
            }
        }
    ]
}

400: Bad Request Request contains malformed data

401: Unauthorized Invalid or expired access token

402: Payment Required Pending payment

422: Unprocessable Entity Internal validation failed

429: Too Many Requests API rate limit

404: Not Found User not found

Attributes

Name	Type	Description
data	object	Claims data List of claims related to the user.
id	uuid	Unique identifier of the claim
package_id	string	Identifier of the associated package
subject	string	Subject or title of the claim
claimant_id	string	Unique identifier of the claimant
risk_item_id	uuid	Identifier of the associated risk item
variant_id	uuid	Identifier of the policy variant
type	string	Type of insurance claim
status	string	Current status of the claim
uid	string	Unique identifier of the claim in external systems
insurer_claim_number	string	Claim number assigned by the insurer
internal_claim_number	number	Internal claim number assigned by the system
incident_date	string	Date and time of the incident (ISO 8601 format)
consent_date	string	Date when consent was given, if applicable
resolution_date	string	Date when the claim was resolved, if applicable
assets	object[]	List of associated assets
incident	object	Contains information about the reported incident, including date, details, and additional properties.
claim_amount	number	Total amount claimed
communications	object[]	List of communications related to the claim
metadata	object	Additional metadata about the claim
policy_reference	object	Holds policy-related details, including policy ID, number, coverage variant, and pricing information.
claimant_data	object	Stores personal information about the claimant, such as name, contact details, and identification data.

All claims

v1

GET https://app.insurehero.io/api/shield/v1/claims

v2

GET https://app.insurehero.io/api/shield/v2/claims

A paginated list of all claims.

Page size cannot exceed 100 records at a time.

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Query Parameters

Name	Type	Description
from*	string	Starting record index
to*	string	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

Example Response 201

V1

{
    "data": [
        {
            "id": "12345678-1234-1234-1234-1234567890ab",
            "communications": [],
            "policy_reference": {
                "policy": {
                    "id": "87654321-4321-4321-4321-0987654321ba",
                    "uid": "package5678",
                    "version": 1,
                    "metadata": {},
                    "policy_number": "9876",
                    "total_gross_price": "100 + 50"
                },
                "variant": {
                    "id": "11223344-5566-7788-99aa-bbccddeeff00",
                    "name": "Standard Variant",
                    "conditions": "Standard coverage conditions apply.",
                    "created_at": "2024-05-10T21:00:41.277415+00:00",
                    "exclusions": "Excludes pre-existing conditions.",
                    "insurer_id": "55667788-99aa-bbcc-ddee-ff0011223344",
                    "description": "Standard insurance variant.",
                },
                "riskItem": {}
            },
            "created_at": "2024-05-11T17:18:36.452503+00:00",
            "updated_at": "2024-05-11T17:18:36.452503+00:00",
            "deleted_at": null,
            "risk_item_id": "55667788-99aa-bbcc-ddee-ff0011223344",
            "claimant_id": "22334455-6677-8899-aabb-ccddeeff0011",
            "channel_id": "99887766-5544-3322-1100-aabbccddeeff",
            "subject": "I broke my leg",
            "insurer_claim_number": null,
            "internal_claim_number": 42,
            "status": "SUBMITTED",
            "incident_date": "2025-01-19T02:06:34.539+00:00",
            "resolution_date": null,
            "claim_amount": null,
            "payout_amount": null,
            "metadata": {},
            "assets": [],
            "type": "Health Insurance",
            "consent_date": null,
            "incident": {
                "date": "2025-01-19T02:06:34.539Z",
                "details": {
                    "description": "I was riding a bike and fell.",
                    "transaction": {}
                },
                "summary": "MEDICAL",
                "additional_properties": {}
            },
            "package_id": "33445566-7788-99aa-bbcc-ddeeff001122",
            "transaction_date": null,
            "uid": null,
            "variant_id": "11223344-5566-7788-99aa-bbccddeeff00",
            "claimant_data": {
                "id": "22334455-6677-8899-aabb-ccddeeff0011",
                "dob": "1990-01-01T00:00:00+00:00",
                "uid": "[e-mail]",
                "name": "John Doe",
                "email": "[e-mail]",
                "phone": "123-456-7890",
                "gender": "MALE",
                "address": "123 Main St, Anytown, USA",
                "group_id": "55667788-99aa-bbcc-ddee-ff0011223344",
                "metadata": {
                    "vip": true
                },
                "channel_id": "99887766-5544-3322-1100-aabbccddeeff",
                "company_name": "TechCorp",
                "company_role": "Developer",
                "bank_accounts": [
                    {
                        "iban": "DE89370400440532013000",
                        "country": "Germany",
                        "currency": "EUR",
                        "bank_name": "Deutsche Bank",
                        "bic_swift": "DEUTDEDBFRA",
                        "account_name": "John Doe",
                        "account_type": "checking",
                        "bank_address": "Taunusanlage 12, 60325 Frankfurt am Main, Germany",
                        "account_number": "0123456789",
                        "routing_number": "10010010",
                        "additional_info": "Primary account"
                    },
                    {
                        "iban": "GB33BUKB20201555555555",
                        "country": "UK",
                        "currency": "GBP",
                        "bank_name": "Barclays",
                        "bic_swift": "BUKBGB22",
                        "account_name": "John Doe",
                        "account_type": "savings",
                        "bank_address": "1 Churchill Place, London, E14 5HP, UK",
                        "account_number": "987654321",
                        "routing_number": "202015",
                        "additional_info": "Savings account"
                    }
                ],
                "company_email": "[e-mail]",
                "document_type": "passport",
                "company_address": "456 Corporate Ave, Metropolis, USA",
                "document_number": "A1234567",
                "company_identifier": {
                    "type": "TIN",
                    "value": "123-45-6789"
                },
                "company_bank_accounts": [
                    {
                        "iban": "FR7630006000011234567890189",
                        "country": "France",
                        "currency": "EUR",
                        "bank_name": "BNP Paribas",
                        "bic_swift": "BNPAFRPP",
                        "account_name": "TechCorp",
                        "account_type": "business",
                        "bank_address": "16 Boulevard des Italiens, 75009 Paris, France",
                        "account_number": "12345678901",
                        "routing_number": "30004",
                        "additional_info": "Corporate account"
                    }
                ]
            },
            "required_documents": {},
            "owner_id": null,
            "asignee_id": null
        }
    ]
}

V2

{
    "data": [
        {
            "id": "12345678-1234-1234-1234-1234567890ab",
            "package_id": "12345678-1234-1234-1234-1234567890ac",
            "claimant_id": "12345678-1234-1234-1234-1234567890ad",
            "risk_item_id": "12345678-1234-1234-1234-1234567890ae",
            "variant_id": "12345678-1234-1234-1234-1234567890af",
            "type": "Health Insurance",
            "status": "SUBMITTED",
            "uid": null,
            "insurer_claim_number": null,
            "internal_claim_number": 101,
            "consent_date": null,
            "resolution_date": null,
            "assets": [],
            "metadata": {},
            "policy_reference": {
                "policy": {
                    "id": "12345678-1234-1234-1234-1234567890ag",
                    "uid": "policy1234",
                    "version": 1,
                    "metadata": {},
                    "policy_number": "5678",
                    "total_gross_price": "100 + 50"
                },
                "variant": {
                    "id": "12345678-1234-1234-1234-1234567890ah",
                    "name": "Standard Variant",
                    "conditions": "Standard coverage conditions apply.",
                    "created_at": "2024-05-10T21:00:41.277415+00:00",
                    "exclusions": "Excludes pre-existing conditions.",
                    "insurer_id": "12345678-1234-1234-1234-1234567890ai",
                    "description": "Standard insurance variant.",
                },
                "riskItem": {}
            },
            "incident": {
                "date": "2025-01-19T02:06:34.539Z",
                "subject": "Broke my arm",
                "claim_amount": null,
                "description": "I was riding a bike and fell."
            },
            "communications": [],
            "created_at": "2024-05-11T17:18:36.452503+00:00",
            "updated_at": "2024-05-11T17:18:36.452503+00:00",
            "deleted_at": null,
            "channel_id": "12345678-1234-1234-1234-1234567890ai",
            "incident_date": "2025-01-19T02:06:34.539+00:00",
            "payout_amount": null,
            "transaction_date": null
        },
        {
            "id": "22334455-6677-8899-aabb-ccddeeff0011",
            "package_id": "22334455-6677-8899-aabb-ccddeeff0022",
            "claimant_id": "22334455-6677-8899-aabb-ccddeeff0033",
            "risk_item_id": "22334455-6677-8899-aabb-ccddeeff0044",
            "variant_id": "22334455-6677-8899-aabb-ccddeeff0055",
            "type": "Life Insurance",
            "status": "SUBMITTED",
            "uid": null,
            "insurer_claim_number": null,
            "internal_claim_number": 202,
            "consent_date": "2024-05-02T03:00:00+00:00",
            "resolution_date": null,
            "assets": [],
            "metadata": {},
            "policy_reference": {},
            "incident": {
                "date": "2024-05-01T03:00:00.000Z",
                "subject": "Life insurance claim",
                "claim_amount": null,
                "description": null,
                "additional_details": true
            },
            "communications": [],
            "created_at": "2024-05-02T16:16:08.251657+00:00",
            "updated_at": "2024-05-06T17:00:58.894+00:00",
            "deleted_at": null,
            "channel_id": "22334455-6677-8899-aabb-ccddeeff0066",
            "subject": "Life insurance claim",
            "incident_date": "2024-05-01T03:00:00+00:00",
            "claim_amount": null,
            "payout_amount": null,
            "transaction_date": null
        }
    ]
}

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	string	Amount claimed
payout_amount	string	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
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
asignee_id	uuid	Identifier of the person assigned to the claim

Get the data of a given claim

v1

GET https://app.insurehero.io/api/shield/v1/claims/:claimId

v2

GET https://app.insurehero.io/api/shield/v2/claims/:claimId

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
claimId*	string	Claim identifier

Query Params

Name	Type	Description
comm_info	boolean	Communication information for that claim
policy_ref	boolean	The policy detail for that claim
general	boolean	The details of the claim

Example Response 200

v1

{
    "data": {
        "id": "30fa2bdf-dd3e-4301-acd8-301668ee6cce",
        "package_id": "91b749df-d833-46d8-92ae-fefb7ae607c2",
        "claimant_id": "93729951-ea59-4116-a9ef-266b2f690ed4",
        "risk_item_id": "2140618c-522c-493c-a81d-c28ccfa9d86e",
        "type": "Auto Insurance",
        "status": "SUBMITTED",
        "uid": "CLAIM123",
        "insurer_claim_number": "INSURE123",
        "internal_claim_number": 69,
        "consent_date": "2024-05-02T03:00:00+00:00",
        "resolution_date": null,
        "assets": [],
        "metadata": {
            "additional_info": "Some additional info"
        },
        "policy_reference": {
            "policy": {
                "id": "eb326ade-902b-4298-b6e8-fa8f8fe7bf2a",
                "uid": "package1234",
                "version": 1,
                "metadata": {
                    "policy_info": "Additional policy info"
                },
                "policy_number": "2245",
                "total_gross_price": "1 + 1"
            },
            "variant": {
                "id": "525f201c-516d-4780-9d08-9459d73d9f5d",
                "name": "variant PROD",
                "conditions": "Some conditions",
                "created_at": "2024-05-10T21:00:41.277415+00:00",
                "exclusions": "Some exclusions",
                "insurer_id": "INSURER123",
                "description": "Some description",
                "gross_price": "1",
                "pricing_type": "one_time",
                "pricing_rules": {
                    "net_price": "Net price rules"
                },
                "coverage_limits": 0
            },
            "riskItem": {}
        },
        "claimant_data": {
            "id": "93729951-ea59-4116-a9ef-266b2f690ed4",
            "dob": "2024-04-11T03:00:00+00:00",
            "uid": "USER123",
            "name": "John Doe",
            "email": "[e-mail]",
            "phone": "1234567890",
            "gender": "MALE",
            "address": "123 Main Street",
            "group_id": "GROUP123",
            "metadata": {
                "additional_info": "Some additional info"
            },
            "channel_id": "CHANNEL123",
            "company_name": "ABC Company",
            "company_role": "Employee",
            "bank_accounts": [
                {
                    "iban": "IBAN123",
                    "country": "US",
                    "currency": "USD",
                    "bank_name": "Bank of America",
                    "bic_swift": "BOFAUS3N",
                    "account_name": "John Doe",
                    "account_type": "Checking",
                    "bank_address": "456 Bank Street",
                    "account_number": "123456789",
                    "routing_number": "123456789",
                    "additional_info": "Some additional info"
                }
            ],
            "company_email": "[e-mail]",
            "document_type": "PASSPORT",
            "company_address": "456 Company Avenue",
            "document_number": "ABC123",
            "company_identifier": {
                "type": "TAX_ID",
                "value": "TAX123"
            },
            "company_bank_accounts": [
                {
                    "iban": "IBAN456",
                    "country": "US",
                    "currency": "USD",
                    "bank_name": "Chase Bank",
                    "bic_swift": "CHASUS33",
                    "account_name": "ABC Company",
                    "account_type": "Savings",
                    "bank_address": "789 Company Boulevard",
                    "account_number": "987654321",
                    "routing_number": "987654321",
                    "additional_info": "Some additional info"
                }
            ]
        },
        "incident": {
            "date": "2025-01-19T02:06:34.539Z",
            "claim_amount": null,
            "description": "Iba a bicicleta y me cai."
        },
        "communications": [],
        "created_at": "2024-05-11T17:18:36.452503+00:00",
        "updated_at": "2024-05-11T17:18:36.452503+00:00",
        "deleted_at": null,
        "channel_id": "fc94d4a1-f834-481d-a6b2-138b823389c8",
        "subject": "Me rompí una pierna24",
        "incident_date": "2025-01-19T02:06:34.539+00:00",
        "claim_amount": null,
        "payout_amount": null,
        "transaction_date": null,
        "variant_id": "525f201c-516d-4780-9d08-9459d73d9f5d",
        "required_documents": {},
        "owner_id": null,
        "asignee_id": null
    }
}

v2

{
    "data": {
        "id": "30fa2bdf-dd3e-4301-acd8-301668ee6cce",
        "package_id": "91b749df-d833-46d8-92ae-fefb7ae607c2",
        "claimant_id": "93729951-ea59-4116-a9ef-266b2f690ed4",
        "risk_item_id": "2140618c-522c-493c-a81d-c28ccfa9d86e",
        "type": "Auto Insurance",
        "status": "SUBMITTED",
        "uid": "CLAIM123",
        "insurer_claim_number": "INSURE123",
        "internal_claim_number": 69,
        "consent_date": "2024-05-02T03:00:00+00:00",
        "resolution_date": null,
        "assets": [],
        "metadata": {
            "additional_info": "Some additional info"
        },
        "policy_reference": {
            "policy": {
                "id": "eb326ade-902b-4298-b6e8-fa8f8fe7bf2a",
                "uid": "package1234",
                "version": 1,
                "metadata": {
                    "policy_info": "Additional policy info"
                },
                "policy_number": "2245",
                "total_gross_price": "1 + 1"
            },
            "variant": {
                "id": "525f201c-516d-4780-9d08-9459d73d9f5d",
                "name": "variant PROD",
                "conditions": "Some conditions",
                "created_at": "2024-05-10T21:00:41.277415+00:00",
                "exclusions": "Some exclusions",
                "insurer_id": "INSURER123",
                "description": "Some description",
                "gross_price": "1",
                "pricing_type": "one_time",
                "pricing_rules": {
                    "net_price": "Net price rules"
                },
                "coverage_limits": 0
            },
            "riskItem": {}
        },
        "claimant_data": {
            "id": "93729951-ea59-4116-a9ef-266b2f690ed4",
            "dob": "2024-04-11T03:00:00+00:00",
            "uid": "USER123",
            "name": "John Doe",
            "email": "[e-mail]",
            "phone": "1234567890",
            "gender": "MALE",
            "address": "123 Main Street",
            "group_id": "GROUP123",
            "metadata": {
                "additional_info": "Some additional info"
            },
            "channel_id": "CHANNEL123",
            "company_name": "ABC Company",
            "company_role": "Employee",
            "bank_accounts": [
                {
                    "iban": "IBAN123",
                    "country": "US",
                    "currency": "USD",
                    "bank_name": "Bank of America",
                    "bic_swift": "BOFAUS3N",
                    "account_name": "John Doe",
                    "account_type": "Checking",
                    "bank_address": "456 Bank Street",
                    "account_number": "123456789",
                    "routing_number": "123456789",
                    "additional_info": "Some additional info"
                }
            ],
            "company_email": "[e-mail]",
            "document_type": "PASSPORT",
            "company_address": "456 Company Avenue",
            "document_number": "ABC123",
            "company_identifier": {
                "type": "TAX_ID",
                "value": "TAX123"
            },
            "company_bank_accounts": [
                {
                    "iban": "IBAN456",
                    "country": "US",
                    "currency": "USD",
                    "bank_name": "Chase Bank",
                    "bic_swift": "CHASUS33",
                    "account_name": "ABC Company",
                    "account_type": "Savings",
                    "bank_address": "789 Company Boulevard",
                    "account_number": "987654321",
                    "routing_number": "987654321",
                    "additional_info": "Some additional info"
                }
            ]
        },
        "incident": {
            "date": "2025-01-19T02:06:34.539Z",
            "subject": "Car accident",
            "claim_amount": null,
            "description": "I was involved in a car accident."
        },
        "communications": [],
        "created_at": "2024-05-11T17:18:36.452503+00:00",
        "updated_at": "2024-05-11T17:18:36.452503+00:00",
        "deleted_at": null,
        "channel_id": "CHANNEL123",
        "subject": "Car accident",
        "incident_date": "2025-01-19T02:06:34.539+00:00",
        "claim_amount": null,
        "payout_amount": null,
        "transaction_date": null,
        "variant_id": "525f201c-516d-4780-9d08-9459d73d9f5d",
        "required_documents": {},
        "owner_id": null,
        "asignee_id": null
}
}

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	string	Amount claimed
payout_amount	string	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
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
asignee_id	uuid	Identifier of the person assigned to the claim

Additional resources

Add Event to Claim

Add a new event with asynchronous data to a claim

POST https://app.insurehero.io/api/shield/v1/claims/:claimId/events

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
ClaimId*	string	Claim identifier

Request Body

Name	Type	Description
event_data*	object	Additional data related to an event. "start_date" and "end_date" are obligatory
metadata	object	Additional data to include in the event

Example response

201: Created Created successfully

{
  "metadata": {
    "additional_properties":"additional properties"
  },
  "event_data": {
    "start_date": "2024-03-15T00:00:00.000Z",
    "end_date": "2024-06-15T00:00:00.000Z",
    "amountPaid": 500,
    "eventType": "PAYMENT_RECEIVED"
  }
}

400: Bad Request Request contains malformed data

401: Unauthorized Invalid or expired access token

402: Payment Required Pending payment

422: Unprocessable Entity Internal validation failed

429: Too Many Requests API rate limit

Attributes

Name	Type	Description
metadata	object	Additional metadata related to the event.
additional_properties	string	Additional custom properties.
event_data	object	Details of the event.
start_date	string	Event start date.
end_date	string	Event end date.
amountPaid	number	Amount paid in the event.
eventType	string	Type of event.

Get Claim events

GET https://app.insurehero.io/api/shield/v1/claims/:claimId/events

Events in a claim

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
ClaimId*	string	The id of the claim associated with the events

Example response

200: OK Retrieved successfully

{
    "data": {
        "id": "85981d7e-bed5-4ec0-9dd1-6d1222fb7f38",
        "package_id": "5b6e7195-6d8f-48b4-a373-688488587d08",
        "subject": "test123456789",
        "claimant_id": "feff4003-bbc3-4ec6-a5ac-b8e631813f76",
        "risk_item_id": "41d1b71f-c9e7-42bd-87dd-93cf3bd36f4c",
        "variant_id": "ede7125c-b302-4270-bbc9-d05f769339a4",
        "type": "Refund Protection",
        "status": "SUBMITTED",
        "uid": null,
        "insurer_claim_number": null,
        "internal_claim_number": 164,
        "incident_date": "2024-09-23T20:00:00+00:00",
        "consent_date": null,
        "resolution_date": null,
        "assets": [],
        "incident": {
            "date": "2024-09-23T20:00:00.000Z",
            "details": {
                "transaction": {}
            },
            "additional_properties": {}
        },
        "claim_amount": null,
        "communications": [],
        "metadata": {},
        "policy_reference": {
            "policy": {
                "id": "5b44b69c-cc0f-4593-a669-fa5ef433f96a",
                "uid": "cfar_vamospasajes_1_test",
                "version": 5,
                "metadata": {},
                "policy_number": "cfar_vamospasajes_1_test",
                "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": "ede7125c-b302-4270-bbc9-d05f769339a4",
                "name": "Cancellation for any reason 100%",
                "markup": [
                    {
                        "owner": "insurer",
                        "taxes": [
                            {
                                "name": "IVA 15%",
                                "rate": 0.15
                            }
                        ],
                        "net_price": "0",
                        "gross_price": "0.07"
                    },
                    {
                        "owner": "platform",
                        "taxes": [
                            {
                                "name": "IVA 15",
                                "rate": 0.15
                            }
                        ],
                        "net_price": "0",
                        "gross_price": "0.015"
                    },
                    {
                        "owner": "channel",
                        "taxes": [
                            {
                                "name": "IVA 15%",
                                "rate": 0.15
                            }
                        ],
                        "net_price": "0",
                        "gross_price": "0.015"
                    }
                ],
                "conditions": "Cancelación por cualquier razón Hasta 30 minutos antes del viaje",
                "created_at": "2024-09-05T17:55:21.978517+00:00",
                "exclusions": "Si ya son menos de 30 minutos.\n",
                "description": "Crédito para cambio de pasaje. "
            },
            "riskItem": {
                "id": "41d1b71f-c9e7-42bd-87dd-93cf3bd36f4c",
                "end_date": "2024-09-26T02:50:00+00:00",
                "metadata": {},
                "start_date": "2024-09-19T18:07:48+00:00",
                "beneficiaries": [
                    {
                        "email": "[e-mail]",
                        "phone": "34619066223",
                        "last_name": "TESTING",
                        "first_name": "SAMUEL",
                        "identifier_type": "National ID",
                        "identifier_value": "1306133578"
                    }
                ],
                "insured_subject": {
                    "ticket_id": "VAPTEST3",
                    "arrival_city": "Guayaquil Terminal Terrestre",
                    "departure_city": "Manta Terminal Terrestre",
                    "number_tickets": 2,
                    "reservation_id": "VAPTEST3",
                    "identifier_type": "ticket_id",
                    "cooperativa_name": "REINA DEL CAMINO",
                    "identifier_value": "VAPTEST3",
                    "arrival_date_time": "2024-09-26T07:20",
                    "purchase_date_time": "2024-09-19T13:07:48-05:00",
                    "departure_date_time": "2024-09-26T03:20",
                    "total_reservation_value": 15.4
                }
            }
        },
        "claimant_data": {
            "id": "6a6147f9-29af-403c-bf38-1c35a3371822",
            "dob": null,
            "uid": "34619066223",
            "name": "SAMUEL TESTING",
            "email": "[e-mail]",
            "phone": "34619066223",
            "gender": null,
            "address": null,
            "group_id": null,
            "metadata": {},
            "channel_id": "88eae369-fff4-471c-9761-089b8304edfa",
            "company_name": null,
            "company_role": null,
            "bank_accounts": [
                {
                    "iban": "",
                    "country": "",
                    "currency": "",
                    "bank_name": "",
                    "bic_swift": "",
                    "account_name": "",
                    "account_type": "",
                    "bank_address": "",
                    "account_number": "",
                    "routing_number": "",
                    "additional_info": ""
                }
            ],
            "company_email": null,
            "document_type": null,
            "company_address": null,
            "document_number": null,
            "company_identifier": null,
            "company_bank_accounts": null
        },
        "claims_events": [
            {
                "id": "7b82b94c-1e1b-4e55-ab6e-76aac9c37b10",
                "claim_id": "85981d7e-bed5-4ec0-9dd1-6d1222fb7f38",
                "metadata": {},
                "event_data": {
                    "start_date": "2025-03-15T00:00:00.000Z",
                    "end_date": "2025-06-15T00:00:00.000Z"
                    "amountPaid": 500,
                    "eventType": "PAYMENT_RECEIVED"
                },
                "uid": null
            },
            {
                "id": "4199ce3e-5a02-48e5-8e6e-6f531fa80e5b",
                "claim_id": "85981d7e-bed5-4ec0-9dd1-6d1222fb7f38",
                "metadata": {},
                "event_data": {
                   "start_date": "2025-03-15T00:00:00.000Z",
                    "end_date": "2025-06-15T00:00:00.000Z"
                    "amountPaid": 500,
                    "eventType": "PAYMENT_RECEIVED"
                },
                "uid": null
            },
            {
                "id": "301ded23-9fc5-48d1-bd8e-10c2a4d95d23",
                "claim_id": "85981d7e-bed5-4ec0-9dd1-6d1222fb7f38",
                "metadata": {},
                "event_data": {
                   "start_date": "2025-03-15T00:00:00.000Z",
                    "end_date": "2025-06-15T00:00:00.000Z"
                    "amountPaid": 500,
                    "eventType": "PAYMENT_RECEIVED"
                },
                "uid": null
            },
            {
                "id": "ee2c8ea2-a6be-4b2a-87da-d1aaeb11a2a8",
                "claim_id": "85981d7e-bed5-4ec0-9dd1-6d1222fb7f38",
                "metadata": {},
                "event_data": {
                    "start_date": "2025-03-15T00:00:00.000Z",
                    "end_date": "2025-06-15T00:00:00.000Z"
                    "amountPaid": 500,
                    "eventType": "PAYMENT_RECEIVED"
                },
                "uid": null
            }
        ]
    }
}

400: Bad Request Request contains malformed data

401: Unauthorized Invalid or expired access token

402: Payment Required Pending payment

422: Unprocessable Entity Internal validation failed

429: Too Many Requests API rate limit

404: Not Found User not found

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	string	Amount claimed
payout_amount	string	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
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
asignee_id	uuid	Identifier of the person assigned to the claim
claims_events	object []	List of events associated with the claim

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.

v1

POST https://app.insurehero.io/api/shield/v1/claims

v2

POST https://app.insurehero.io/api/shield/v2/claims

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Request Body

v1

Name	Type	Description
risk_item_id*	string	Item being claimed
claimant_email*	string	Claimant email
variant_id*	string	The coverage variant chosen for this claim
metadata	object	Additional data of this claim
subject*	string	A sentence describing the claim
incident*	IncidentType	Incident data
claim_amount	number	A positive number requested to be paid

v2

Name	Type	Description
risk_item_uid*	string	Item being claimed
claimant_email*	string	Claimant Email
variant_uid*	string	The coverage variant chosen for this claim
incident*	IncidentType	Incident data.
metadata	object	Additional data of this claim

Types of responses

201: Created Created successfully

400: Bad Request Request contains malformed data

401: Unauthorized Invalid or expired access token

402: Payment Required Pending payment

422: Unprocessable Entity Internal validation failed

429: Too Many Requests API rate limit

Example Response 201

v1

{
    "data": {
        "id": "6fa8c194-69b9-4d84-8fa8-495d06acccef",
        "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
        "subject": "Subject Example",
        "claimant_id": "6063125e-1626-49ea-87ec-ed7bd756ea70",
        "risk_item_id": "5254e367-ba46-4549-803b-0c22b35ad99e",
        "variant_id": "c7038056-91d5-4c61-91d5-578f8b482086",
        "type": "Property Insurance",
        "status": "SUBMITTED",
        "uid": null,
        "insurer_claim_number": null,
        "internal_claim_number": 88,
        "incident_date": "2025-01-19T02:06:34.539+00:00",
        "consent_date": null,
        "resolution_date": null,
        "assets": [],
        "incident": {
            "date": "2025-01-19T02:06:34.539Z",
            "details": {
                "transaction": {
                    "date": "2023-05-20T14:48:00.000Z",
                    "amount": 150,
                    "method": "VISA",
                    "retailer": "Retailer Name",
                    "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": "ROBO",
                "fast_track": true,
                "incident_coords": "-0.180653, -78.467838"
            }
        },
        "claim_amount": null,
        "communications": [],
        "metadata": {},
        "policy_reference": {
            "policy": {
                "id": "c42a9583-9a58-4b0c-b332-21499780a35b",
                "uid": "c42a9583-9a58-4b0c-b332-21499780a35b",
                "version": 2,
                "metadata": {},
                "policy_number": "46",
                "total_gross_price": "535253 + 125125"
            },
            "variant": {
                "id": "c7038056-91d5-4c61-91d5-578f8b482086",
                "name": "Variant name example",
                "taxes": [
                    {
                        "name": "tax",
                        "rate": 215125
                    }
                ],
                "markup": [
                    {
                        "owner": "channel",
                        "taxes": [
                            {
                                "name": "Cobertura",
                                "rate": 4124124
                            }
                        ],
                        "net_price": null,
                        "gross_price": "125125"
                    }
                ],
                "conditions": "Conditions example",
                "created_at": "2024-05-27T20:59:36.0742+00:00",
                "exclusions": "Exclusions example",
                "description": null,
                "gross_price": "535253",
                "pricing_type": "one_time",
                "pricing_rules": {
                    "net_price": null
                },
                "coverage_limits": 0
            },
            "riskItem": {}
        },
        "claimant_data": {
            "id": "6063125e-1626-49ea-87ec-ed7bd756ea70",
            "dob": null,
            "uid": "[e-mail]",
            "name": "John Doe",
            "email": "[e-mail]",
            "phone": "0386541656035235",
            "gender": null,
            "address": "Address example",
            "group_id": null,
            "metadata": {},
            "channel_id": "fc94d4a1-f834-481d-a6b2-138b823389c8",
            "company_name": null,
            "company_role": null,
            "bank_accounts": null,
            "company_email": null,
            "document_type": null,
            "company_address": null,
            "document_number": null,
            "company_identifier": null,
            "company_bank_accounts": null
        }
    }
}

v2

{
    "data": {
        "id": "4202e93a-1d15-4a99-ae3e-de267a29e67d",
        "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
        "claimant_id": "6063125e-1626-49ea-87ec-ed7bd756ea70",
        "risk_item_id": "5254e367-ba46-4549-803b-0c22b35ad99e",
        "variant_id": "c7038056-91d5-4c61-91d5-578f8b482086",
        "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": "2025-01-19T02:06:34.539Z",
            "subject": "Subject Example",
            "claim_amount": 1999,
            "description": "Incident description.",
            // Additional properties
            "property_one": true
        },
        "communications": []
    }
}

IncidentType

v1

Value	Type
date*	date
summary	string
details*	DetailsType
adittional_properties*	JSON

DetailsType

Value	Type
transaction*	TransactionType
description	string

TransactionType

Value	Type
date	string
amount	number
method	VISA, MASTERCARD, AMEX, DISCOVER o TRANSFER
retailer	string
description	string

v2

Value	Type
subject*	string
date*	date
description	string
claim_amount	number

Additional Attributes

Claimant data

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

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.
taxes	object []	List of taxes applied.
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.
gross_price	string	Gross price of the variant.
pricing_type	string	Type of pricing.
pricing_rules	object	Pricing rules configuration.
coverage_limits	number	Coverage limits applied.