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

GET

GET

GET

POST

GET

GET

GET

POST

POST

GET

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

{
    "data": {
        "id": "6e83de1e-af92-4604-99d8-eaf9f198e8a9",
        "channel_id": "fc94d4a1-f834-481d-a6b2-138b823389c8",
        "email": "john.doe@example.com",
        "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": "john.doe@example.com",
        "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": {}
    }
}

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

{
    "data": [
        {
            "id": "5254x367-ba46-4549-803b-0c22b35ad99e",
            "policy_id": "c12a9583-9a58-4b0c-b332-21499780a35b",
            "authorized_claimants": [
                {
                    "email": "example@mail.com"
                }
            ],
            "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": {}
        }
    ]
}

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

{
    "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": {}
        }
    ]
}

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

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

Headers

Name
Type
Description

Authorization*

string

Bearer access token

User-Authorization*

string

Request Body

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

Types of responses

Example Response 201

{
    "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": "mail@example.com",
            "name": "John Doe",
            "email": "mail@example.com",
            "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
        }
    }
}

IncidentType

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

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

{
    "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": "john.doe@example.com",
                "name": "John Doe",
                "email": "john.doe@example.com",
                "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
            }
        }
    ]
}

All claims

GET https://app.insurehero.io/api/shield/v1/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

Types of responses

Example Response 200

{
    "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": "john.doe@example.com",
                "name": "John Doe",
                "email": "john.doe@example.com",
                "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": "john.doe@techcorp.com",
                "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
        }
    ]
}

Get the data of a given claim

GET https://app.insurehero.io/api/shield/v1/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

Types of responses

Example Response 200

{
    "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": "john.doe@example.com",
            "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": "info@abccompany.com",
            "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
    }
}

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


{
  "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"
  }
}

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

{
    "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": "34619066223@vamospasajes.com",
                        "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": "34619066223@vamospasajes.com",
            "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
            }
        ]
    }
}

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.

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

Headers

Name
Type
Description

Authorization*

string

Bearer access token

Request Body

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

Types of responses

Example Response 201

{
    "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": "mail@example.com",
            "name": "John Doe",
            "email": "mail@example.com",
            "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
        }
    }
}

IncidentType

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

PreviousClaims OverviewNextClaim Creation Examples

Last updated