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.

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

Path Parameters

Query Parameters

Or using its email.

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

Path Parameters

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

Path Parameters

Query Parameters

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

Path Parameters

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

Request Body

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

DetailsType

TransactionType

User claims

Fetch all claims from a given user

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

Path Parameters

Query Parameters

Headers

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

Query Parameters

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

Path Parameters

Query Params

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