Risk Item management

Adding a Risk Item to a policy defines the "insured subject," such as personal items (eyewear, bicycles), larger assets (vehicles), an individual's life or health, and shipping cargo. This step tailors the subject to specific coverage plans, optimizing pricing and operational efficiency.

For practical guidance, we encourage you to explore our Risk Item creation examples, showcasing pre-configured payloads. These examples are illustrative, and adjustments may be necessary based on the insurance product and jurisdiction.

Endpoints

Method	Endpoint
POST	https://app.insurehero.io/api/shield/v1/risk-items
POST	https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/events
PUT	https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/beneficiaries
GET	https://app.insurehero.io/api/shield/v1/risk-items
GET	https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId
GET	https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/events
GET	https://app.insurehero.io/api/shield/v1/users/:userId/risk-items
PATCH	https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/cancel
DELETE	https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/rescission

How to get the data

To gather the requisite data for creating a risk-item, it's advisable to utilize the endpoints detailed in the policy management section. There, you can access information on available policies, enabling you to procure the necessary details for the required package. This facilitates obtaining insights into the package's variants and coverages.

Add a Risk Item to a policy

POST https://app.insurehero.io/api/shield/v1/risk-items

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Request Body

Name	Type	Description
package_uid*	string	The uid of the package to subscribe to.
policy_uid*	string	The uid of the policy associated.
start_date*	string	Risk item starting date (ISO 8601 format)
end_date*	string	Risk item ending date (ISO 8601 format)
insured_subject*	object	Insured information to be included in the risk item. identifier_value and identifier_type are required fields.
uid*	string	Unique identifier
beneficiaries	object []	List of users who could be beneficiaries. Email or phone are the only required field, the others are optional.
authorized_claimants	object []	List of users who would be authorized claimants. Email is the only required field, the others are optional.
metadata	object	Additional data to include in the risk item

Example response

201: Created Created successfully

{
    "data": {
        "id": "4729a579-7121-4926-92eb-19f9f0ed1158",
        "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b",
        "authorized_claimants": [
            {
                "email": "[email protected]",
                "name": "Lucia Martinez",
                "phone": "593999002823"
            },
            {
                "email": "[email protected]",
                "name": "Marco Reyes",
                "phone": "593999002824"
            }
        ],
        "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
        "start_date": "2024-03-15T00:00:00+00:00",
        "end_date": "2024-03-31T23:59:59.999+00:00",
        "beneficiaries": [
            {
                "email": "[email protected]",
                "name": "Ana Torres",
                "phone": "593999002825",
                "group_uid": "yourUID01"
            }
        ],
        "insured_subject": {
            "identifier_value": "GN789",
            "identifier_type": "Guide Number",
            "ruc": "1711186642001",
            "driver_id": "1714486642",
            "group_uid": "yourUID01",
            "group_name": "Ecuador Transport",
            "policy_note": "Insured against theft and damage",
            "guide_number": "GN789",
            "plate_number": "PICH1234",
            "subject_type": "cargo",
            "invoice_count": 10,
            "departure_city": "Guayaquil",
            "departure_date": "2024-01-24T09:00:00Z",
            "content_category": "Clothing",
            "departure_coords": "-2.170998, -79.922359",
            "destination_city": "Quito",
            "driver_full_name": "Luis Andrade",
            "primary_category": "Men's Apparel",
            "business_industry": "Consumo Masivo",
            "policy_observations": "Fragile items inside",
            "total_insured_value": 75000
        },
        "status": "ACTIVE",
        "uid": null,
        "assets": [],
        "metadata": {
            "delivery_stops": {
                "Delivery 1": {
                    "items": [
                        {
                            "item_sku": "LAP1234A",
                            "item_cost": 1200,
                            "item_name": "Laptop",
                            "item_expiry": "2024-12-31",
                            "item_quantity": 10
                        }
                    ],
                    "final_coords": "-0.180653, -78.467838",
                    "destination_invoice_id": "INV1001"
                }
            }
        }
    }
}

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
data	object	Object containing information about a risk item
id	uuid	Unique identifier for the risk item
policy_id	uuid	Unique identifier for the associated policy
authorized_claimants	object []	List of authorized claimants
authorized_claimants.email	string	Email of the authorized claimant
authorized_claimants.name	string	Name of the authorized claimant
authorized_claimants.phone	string	Phone number of the authorized claimant
package_id	uuid	Unique identifier for the coverage package
start_date	string	Start date of the coverage period
end_date	string	End date of the coverage period
beneficiaries	object []	List of beneficiaries
beneficiaries.email	string	Email of the beneficiary
beneficiaries.name	string	Name of the beneficiary
beneficiaries.phone	string	Phone number of the beneficiary
beneficiaries.group_uid	string	Unique identifier for the beneficiary’s group
insured_subject	object	Details of the insured subject
insured_subject.identifier_value	string	Identifier of the insured subject
insured_subject.identifier_type	string	Type of identifier
insured_subject.ruc	string	Taxpayer identification number
insured_subject.driver_id	string	Driver's identification number
insured_subject.group_uid	string	Unique identifier of the insured group
insured_subject.group_name	string	Name of the insured group
insured_subject.policy_note	string	Policy coverage notes
insured_subject.guide_number	string	Tracking number for the shipment
insured_subject.plate_number	string	License plate of the transport vehicle
insured_subject.subject_type	string	Type of insured subject
insured_subject.invoice_count	number	Number of invoices related to the insured subject
insured_subject.departure_city	string	City of departure
insured_subject.departure_date	string	Departure date and time
insured_subject.content_category	string	Category of the transported content
insured_subject.departure_coords	string	GPS coordinates of departure location
insured_subject.destination_city	string	Destination city
insured_subject.driver_full_name	string	Full name of the driver
insured_subject.primary_category	string	Main category of insured items
insured_subject.business_industry	string	Industry related to the insured subject
insured_subject.policy_observations	string	Additional observations about the policy
insured_subject.total_insured_value	number	Total insured value in policy currency
status	string	Current status of the risk item
uid	string	Unique identifier
assets	object []	List of associated assets
metadata	object	Additional structured data

Add Event to Risk Item

Add a new event with asynchronous data to a risk item

POST https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/events

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
riskItemId*	string	Risk item 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
uid	text	Unique identifier for the event

Example response

201: Created Created successfully

{
    "data": {
        "id": "e680dd13-99d4-42a9-bd67-40e3069cfc6c",
        "risk_item_id": "2140618c-522c-493c-a81d-c28ccfa9d86e",
        "event_data": {
            "start_date": "2024-03-15T00:00:00.000Z",
            "end_date": "2024-06-15T00:00:00.000Z"
        },
        "metadata": {
            "description": "Event description"
        },
        "uid": "uid-event-001"
    }
}

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
data	object	Contains event details
id	uuid	Unique identifier for the event
risk_item_id	uuid	Unique identifier for the associated risk item
event_data	object	Event-related details
event_data.start_date	string	Start date of the event
event_data.end_date	string	End date of the event
metadata	object	Additional event metadata
metadata.description	string	Description of the event
uid	string	Unique event identifier

Update Risk Item Beneficiaries

Replace the full beneficiaries array for a given risk item.

PUT https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/beneficiaries

Use this endpoint when a channel updates beneficiaries for one of its risk items.

The token must belong to the same channel as the target risk item. Otherwise, the request is rejected.

Update beneficiaries

This operation fully replaces the stored beneficiaries array with the payload you send. Any existing beneficiaries not included in the request are removed.

Path Parameters

Name	Type	Description
riskItemId*	string	Risk item identifier

Headers

Name	Type	Description
Authorization*	string	Bearer access token
Content-Type*	string	application/json

Request Body

Name	Type	Description
beneficiaries*	object []	Full beneficiaries array to persist

Each beneficiaries item supports these fields:

Name	Type	Description
name*	string	Beneficiary first name
lastname*	string	Beneficiary last name
isHolder*	boolean	Indicates if the beneficiary is the policy holder
isBeneficiary*	boolean	Indicates who the beneficiary is
dateOfBirth*	string	Birth date in YYYY-MM-DD format
fiscalType*	string	Fiscal document type
fiscalId*	string	Fiscal document identifier
documentCountry*	string	ISO country code for the document
email	string | null	Beneficiary email
phone	string | null	Beneficiary phone number
mobilePrefix	string | null	Beneficiary mobile prefix
source*	string	Source field

Additional fields are accepted and preserved.

Example request

{
  "beneficiaries": [
    {
      "name": "Juan",
      "lastname": "Pérez",
      "isHolder": true,
      "isTraveler": true,
      "dateOfBirth": "1990-01-15",
      "fiscalType": "DNI",
      "fiscalId": "12345678A",
      "documentCountry": "ES",
      "email": "[email protected]",
      "phone": "[phone]",
      "mobilePrefix": "34",
      "source": "channel"
    }
  ]
}

Example response

200: OK Beneficiaries updated

{
  "data": {
    "id": "4729a579-7121-4926-92eb-19f9f0ed1158",
    "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b",
    "status": "ACTIVE",
    "beneficiaries": [
      {
        "name": "Juan",
        "lastname": "Pérez",
        "isHolder": true,
        "isTraveler": true,
        "dateOfBirth": "1990-01-15",
        "fiscalType": "DNI",
        "fiscalId": "12345678A",
        "documentCountry": "ES",
        "email": "[email protected]",
        "phone": "[phone]",
        "mobilePrefix": "34",
        "source": "channel"
      }
    ]
  }
}

400: Bad Request Invalid JSON or beneficiaries payload

401: Unauthorized Invalid, expired, or unauthorized token

404: Not Found Risk item not found

422: Unprocessable Entity Database persistence failed

Attributes

Name	Type	Description
data	object	Updated risk item
data.id	uuid	Risk item identifier
data.policy_id	uuid	Related policy identifier
data.status	string	Current risk item status
data.beneficiaries	object []	Persisted beneficiaries array

Get all Risk Items

Paginated list of all risk items. Page size cannot exceed 100 records at a time.

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

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Query Parameters

Name	Type	Description
from*	string	Starting record index
to*	string	Ending record index

Example response

200: OK Retrieved successfully

{
    "data": [
        {
            "id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
            "authorized_claimants": [
                {
                    "email": "[email protected]",
                    "name": "Lucia Martinez",
                    "phone": "593999002823"
                },
                {
                    "email": "[email protected]",
                    "name": "Marco Reyes",
                    "phone": "593999002824"
                }
            ],
            "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
            "start_date": "2024-03-15T00:00:00+00:00",
            "end_date": "2024-03-31T23:59:59.999+00:00",
            "beneficiaries": [
                {
                    "email": "[email protected]",
                    "phone": "593999002825"
                }
            ],
            "insured_subject": {
                "identifier_value": "GN789",
                "identifier_type": "Guide Number",
                "ruc": "1711186642001",
                "driver_id": "1714486642",
                "group_uid": "yourUID01",
                "group_name": "Ecuador Transport",
                "policy_note": "Insured against theft and damage",
                "guide_number": "GN789",
                "plate_number": "PICH1234",
                "subject_type": "cargo",
                "invoice_count": 10,
                "departure_city": "Guayaquil",
                "departure_date": "2024-01-24T09:00:00Z",
                "content_category": "Clothing",
                "departure_coords": "-2.170998, -79.922359",
                "destination_city": "Quito",
                "driver_full_name": "Luis Andrade",
                "primary_category": "Men's Apparel",
                "business_industry": "Consumo Masivo",
                "policy_observations": "Fragile items inside",
                "total_insured_value": 75000
            },
            "status": "ACTIVE",
            "uid": null,
            "assets": [],
            "metadata": {
                "delivery_stops": {
                    "Delivery 1": {
                        "items": [
                            {
                                "item_sku": "LAP1234A",
                                "item_cost": 1200,
                                "item_name": "Laptop",
                                "item_expiry": "2024-12-31",
                                "item_quantity": 10
                            }
                        ],
                        "final_coords": "-0.180653, -78.467838",
                        "destination_invoice_id": "INV1001"
                    }
                }
            },
            "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b"
        },
        {
            "id": "4729a579-7121-4926-92eb-19f9f0ed1158",
            "authorized_claimants": [
                {
                    "email": "[email protected]",
                    "name": "Lucia Martinez",
                    "phone": "593999002823"
                },
                {
                    "email": "[email protected]",
                    "name": "Marco Reyes",
                    "phone": "593999002824"
                }
            ],
            "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
            "start_date": "2024-03-15T00:00:00+00:00",
            "end_date": "2024-03-31T23:59:59.999+00:00",
            "beneficiaries": [
                {
                    "email": "[email protected]",
                    "name": "Ana Torres",
                    "phone": "593999002825",
                    "group_uid": "yourUID01"
                }
            ],
            "insured_subject": {
                "identifier_value": "GN789",
                "identifier_type": "Guide Number",
                "ruc": "1711186642001",
                "driver_id": "1714486642",
                "group_uid": "yourUID01",
                "group_name": "Ecuador Transport",
                "policy_note": "Insured against theft and damage",
                "guide_number": "GN789",
                "plate_number": "PICH1234",
                "subject_type": "cargo",
                "invoice_count": 10,
                "departure_city": "Guayaquil",
                "departure_date": "2024-01-24T09:00:00Z",
                "content_category": "Clothing",
                "departure_coords": "-2.170998, -79.922359",
                "destination_city": "Quito",
                "driver_full_name": "Luis Andrade",
                "primary_category": "Men's Apparel",
                "business_industry": "Consumo Masivo",
                "policy_observations": "Fragile items inside",
                "total_insured_value": 75000
            },
            "status": "ACTIVE",
            "uid": null,
            "assets": [],
            "metadata": {
                "delivery_stops": {
                    "Delivery 1": {
                        "items": [
                            {
                                "item_sku": "LAP1234A",
                                "item_cost": 1200,
                                "item_name": "Laptop",
                                "item_expiry": "2024-12-31",
                                "item_quantity": 10
                            }
                        ],
                        "final_coords": "-0.180653, -78.467838",
                        "destination_invoice_id": "INV1001"
                    }
                }
            },
            "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b"
        }
    ]
}

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 []	List of risk items
id	uuid	Unique identifier for the risk item
policy_id	uuid	Unique identifier for the associated policy
authorized_claimants	object []	List of authorized claimants
authorized_claimants.email	string	Email of the authorized claimant
authorized_claimants.name	string	Name of the authorized claimant
authorized_claimants.phone	string	Phone number of the authorized claimant
package_id	uuid	Unique identifier for the coverage package
start_date	string	Start date of the coverage period
end_date	string	End date of the coverage period
beneficiaries	object []	List of beneficiaries
beneficiaries.email	string	Email of the beneficiary
beneficiaries.name	string	Name of the beneficiary
beneficiaries.phone	string	Phone number of the beneficiary
beneficiaries.group_uid	string	Unique identifier for the beneficiary’s group
insured_subject	object	Details of the insured subject
insured_subject.identifier_value	string	Identifier of the insured subject
insured_subject.identifier_type	string	Type of identifier
insured_subject.ruc	string	Taxpayer identification number
insured_subject.driver_id	string	Driver's identification number
insured_subject.group_uid	string	Unique identifier of the insured group
insured_subject.group_name	string	Name of the insured group
insured_subject.policy_note	string	Policy coverage notes
insured_subject.guide_number	string	Tracking number for the shipment
insured_subject.plate_number	string	License plate of the transport vehicle
insured_subject.subject_type	string	Type of insured subject
insured_subject.invoice_count	number	Number of invoices related to the insured subject
insured_subject.departure_city	string	City of departure
insured_subject.departure_date	string	Departure date and time
insured_subject.content_category	string	Category of the transported content
insured_subject.departure_coords	string	GPS coordinates of departure location
insured_subject.destination_city	string	Destination city
insured_subject.driver_full_name	string	Full name of the driver
insured_subject.primary_category	string	Main category of insured items
insured_subject.business_industry	string	Industry related to the insured subject
insured_subject.policy_observations	string	Additional observations about the policy
insured_subject.total_insured_value	number	Total insured value in policy currency
status	string	Current status of the risk item
uid	string	Unique identifier
assets	object []	List of associated assets
metadata	object	Additional structured data

Get the data of a given Risk Item

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

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
riskItemId*	string	Risk item identifier

Example response

200: OK Retrieved successfully

{
    "data": {
        "id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
        "authorized_claimants": [
            {
                "email": "[email protected]",
                "name": "Lucia Martinez",
                "phone": "593999002823"
            },
            {
                "email": "[email protected]",
                "name": "Marco Reyes",
                "phone": "593999002824"
            }
        ],
        "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
        "start_date": "2024-03-15T00:00:00+00:00",
        "end_date": "2024-03-31T23:59:59.999+00:00",
        "beneficiaries": [
            {
                "email": "[email protected]",
                "phone": "593999002825"
            }
        ],
        "insured_subject": {
            "identifier_value": "GN789",
            "identifier_type": "Guide Number",
            "ruc": "1711186642001",
            "driver_id": "1714486642",
            "group_uid": "yourUID01",
            "group_name": "Ecuador Transport",
            "policy_note": "Insured against theft and damage",
            "guide_number": "GN789",
            "plate_number": "PICH1234",
            "subject_type": "cargo",
            "invoice_count": 10,
            "departure_city": "Guayaquil",
            "departure_date": "2024-01-24T09:00:00Z",
            "content_category": "Clothing",
            "departure_coords": "-2.170998, -79.922359",
            "destination_city": "Quito",
            "driver_full_name": "Luis Andrade",
            "primary_category": "Men's Apparel",
            "business_industry": "Consumo Masivo",
            "policy_observations": "Fragile items inside",
            "total_insured_value": 75000
        },
        "status": "ACTIVE",
        "uid": null,
        "assets": [],
        "metadata": {
            "delivery_stops": {
                "Delivery 1": {
                    "items": [
                        {
                            "item_sku": "LAP1234A",
                            "item_cost": 1200,
                            "item_name": "Laptop",
                            "item_expiry": "2024-12-31",
                            "item_quantity": 10
                        }
                    ],
                    "final_coords": "-0.180653, -78.467838",
                    "destination_invoice_id": "INV1001"
                }
            }
        },
        "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b"
    }
}

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	Object containing information about a risk item
id	uuid	Unique identifier for the risk item
policy_id	uuid	Unique identifier for the associated policy
authorized_claimants	object []	List of authorized claimants
authorized_claimants.email	string	Email of the authorized claimant
authorized_claimants.name	string	Name of the authorized claimant
authorized_claimants.phone	string	Phone number of the authorized claimant
package_id	uuid	Unique identifier for the coverage package
start_date	string	Start date of the coverage period
end_date	string	End date of the coverage period
beneficiaries	object []	List of beneficiaries
beneficiaries.email	string	Email of the beneficiary
beneficiaries.name	string	Name of the beneficiary
beneficiaries.phone	string	Phone number of the beneficiary
beneficiaries.group_uid	string	Unique identifier for the beneficiary’s group
insured_subject	object	Details of the insured subject
insured_subject.identifier_value	string	Identifier of the insured subject
insured_subject.identifier_type	string	Type of identifier
insured_subject.ruc	string	Taxpayer identification number
insured_subject.driver_id	string	Driver's identification number
insured_subject.group_uid	string	Unique identifier of the insured group
insured_subject.group_name	string	Name of the insured group
insured_subject.policy_note	string	Policy coverage notes
insured_subject.guide_number	string	Tracking number for the shipment
insured_subject.plate_number	string	License plate of the transport vehicle
insured_subject.subject_type	string	Type of insured subject
insured_subject.invoice_count	number	Number of invoices related to the insured subject
insured_subject.departure_city	string	City of departure
insured_subject.departure_date	string	Departure date and time
insured_subject.content_category	string	Category of the transported content
insured_subject.departure_coords	string	GPS coordinates of departure location
insured_subject.destination_city	string	Destination city
insured_subject.driver_full_name	string	Full name of the driver
insured_subject.primary_category	string	Main category of insured items
insured_subject.business_industry	string	Industry related to the insured subject
insured_subject.policy_observations	string	Additional observations about the policy
insured_subject.total_insured_value	number	Total insured value in policy currency
status	string	Current status of the risk item
uid	string	Unique identifier
assets	object []	List of associated assets
metadata	object	Additional structured data

Additional resources

Get Risk Item events

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

Events in a risk item

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
riskItemId*	string	The id of the risk item associated with the events

Example response

200: OK Retrieved successfully

{
    "data": {
        "id": "4729a579-7121-4926-92eb-19f9f0ed1158",
        "authorized_claimants": [
            {
                "email": "[email protected]",
                "name": "Lucia Martinez",
                "phone": "593999002823"
            },
            {
                "email": "[email protected]",
                "name": "Marco Reyes",
                "phone": "593999002824"
            }
        ],
        "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
        "start_date": "2024-03-15T00:00:00+00:00",
        "end_date": "2024-03-31T23:59:59.999+00:00",
        "beneficiaries": [
            {
                "email": "[email protected]",
                "name": "Ana Torres",
                "phone": "593999002825",
                "group_uid": "yourUID01"
            }
        ],
        "insured_subject": {
            "identifier_value": "GN789",
            "identifier_type": "Guide Number",
            "ruc": "1711186642001",
            "driver_id": "1714486642",
            "group_uid": "yourUID01",
            "group_name": "Ecuador Transport",
            "policy_note": "Insured against theft and damage",
            "guide_number": "GN789",
            "plate_number": "PICH1234",
            "subject_type": "cargo",
            "invoice_count": 10,
            "departure_city": "Guayaquil",
            "departure_date": "2024-01-24T09:00:00Z",
            "content_category": "Clothing",
            "departure_coords": "-2.170998, -79.922359",
            "destination_city": "Quito",
            "driver_full_name": "Luis Andrade",
            "primary_category": "Men's Apparel",
            "business_industry": "Consumo Masivo",
            "policy_observations": "Fragile items inside",
            "total_insured_value": 75000
        },
        "status": "ACTIVE",
        "uid": null,
        "assets": [],
        "metadata": {
            "delivery_stops": {
                "Delivery 1": {
                    "items": [
                        {
                            "item_sku": "LAP1234A",
                            "item_cost": 1200,
                            "item_name": "Laptop",
                            "item_expiry": "2024-12-31",
                            "item_quantity": 10
                        }
                    ],
                    "final_coords": "-0.180653, -78.467838",
                    "destination_invoice_id": "INV1001"
                }
            }
        },
        "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b",
        "events": [
            {
                "id": "e680dd13-99d4-42a9-bd67-40e3069cfc6c",
                "risk_item_id": "4729a579-7121-4926-92eb-19f9f0ed1158",
                "metadata": {
                    "clientName": "ABC Logistics Inc.",
                    "policyNote": "Insured against theft, damage, and loss during transportation.",
                    "guideNumber": "GN789",
                    "plateNumber": "CA4567",
                    "invoiceCount": 10,
                    "departureCity": "Los Angeles",
                    "contentCategory": "Clothing",
                    "destinationCity": "New York",
                    "primaryCategory": "Men's Apparel",
                    "totalInsuredValue": 75000,
                    "policyObservations": "Fragile items inside"
                },
                "event_data": {
                    "invoiceCount": 3,
                    "contentCategory": "Shirt"
                }
            },
            {
                "id": "cb3ef0d6-0939-42fc-b8cf-1dcac6aebed5",
                "risk_item_id": "4729a579-7121-4926-92eb-19f9f0ed1158",
                "metadata": {
                    "clientName": "ABC Logistics Inc.",
                    "policyNote": "Insured against theft, damage, and loss during transportation.",
                    "guideNumber": "GN789",
                    "plateNumber": "CA4567",
                    "invoiceCount": 10,
                    "departureCity": "Los Angeles",
                    "contentCategory": "Clothing",
                    "destinationCity": "New York",
                    "primaryCategory": "Men's Apparel",
                    "totalInsuredValue": 75000,
                    "policyObservations": "Fragile items inside"
                },
                "event_data": {
                    "invoiceCount": 3,
                    "contentCategory": "Shirt"
                }
            }
        ]
    }
}

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

Get Risk Item by user

GET https://app.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	user identifier

Example response

200: OK Retrieved successfully

{
    "data": [
        {
            "id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
            "authorized_claimants": [
                {
                    "email": "[email protected]",
                    "name": "Lucia Martinez",
                    "phone": "593999002823"
                },
                {
                    "email": "[email protected]",
                    "name": "Marco Reyes",
                    "phone": "593999002824"
                }
            ],
            "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
            "start_date": "2024-03-15T00:00:00+00:00",
            "end_date": "2024-03-31T23:59:59.999+00:00",
            "beneficiaries": [
                {
                    "email": "[email protected]",
                    "phone": "593999002825"
                }
            ],
            "insured_subject": {
                "identifier_value": "GN789",
                "identifier_type": "Guide Number",
                "ruc": "1711186642001",
                "driver_id": "1714486642",
                "group_uid": "yourUID01",
                "group_name": "Ecuador Transport",
                "policy_note": "Insured against theft and damage",
                "guide_number": "GN789",
                "plate_number": "PICH1234",
                "subject_type": "cargo",
                "invoice_count": 10,
                "departure_city": "Guayaquil",
                "departure_date": "2024-01-24T09:00:00Z",
                "content_category": "Clothing",
                "departure_coords": "-2.170998, -79.922359",
                "destination_city": "Quito",
                "driver_full_name": "Luis Andrade",
                "primary_category": "Men's Apparel",
                "business_industry": "Consumo Masivo",
                "policy_observations": "Fragile items inside",
                "total_insured_value": 75000
            },
            "status": "ACTIVE",
            "uid": null,
            "assets": [],
            "metadata": {
                "delivery_stops": {
                    "Delivery 1": {
                        "items": [
                            {
                                "item_sku": "LAP1234A",
                                "item_cost": 1200,
                                "item_name": "Laptop",
                                "item_expiry": "2024-12-31",
                                "item_quantity": 10
                            }
                        ],
                        "final_coords": "-0.180653, -78.467838",
                        "destination_invoice_id": "INV1001"
                    }
                }
            },
            "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b"
        },
        {
            "id": "4729a579-7121-4926-92eb-19f9f0ed1158",
            "authorized_claimants": [
                {
                    "email": "[email protected]",
                    "name": "Lucia Martinez",
                    "phone": "593999002823"
                },
                {
                    "email": "[email protected]",
                    "name": "Marco Reyes",
                    "phone": "593999002824"
                }
            ],
            "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
            "start_date": "2024-03-15T00:00:00+00:00",
            "end_date": "2024-03-31T23:59:59.999+00:00",
            "beneficiaries": [
                {
                    "email": "[email protected]",
                    "name": "Ana Torres",
                    "phone": "593999002825",
                    "group_uid": "yourUID01"
                }
            ],
            "insured_subject": {
                "identifier_value": "GN789",
                "identifier_type": "Guide Number",
                "ruc": "1711186642001",
                "driver_id": "1714486642",
                "group_uid": "yourUID01",
                "group_name": "Ecuador Transport",
                "policy_note": "Insured against theft and damage",
                "guide_number": "GN789",
                "plate_number": "PICH1234",
                "subject_type": "cargo",
                "invoice_count": 10,
                "departure_city": "Guayaquil",
                "departure_date": "2024-01-24T09:00:00Z",
                "content_category": "Clothing",
                "departure_coords": "-2.170998, -79.922359",
                "destination_city": "Quito",
                "driver_full_name": "Luis Andrade",
                "primary_category": "Men's Apparel",
                "business_industry": "Consumo Masivo",
                "policy_observations": "Fragile items inside",
                "total_insured_value": 75000
            },
            "status": "ACTIVE",
            "uid": null,
            "assets": [],
            "metadata": {
                "delivery_stops": {
                    "Delivery 1": {
                        "items": [
                            {
                                "item_sku": "LAP1234A",
                                "item_cost": 1200,
                                "item_name": "Laptop",
                                "item_expiry": "2024-12-31",
                                "item_quantity": 10
                            }
                        ],
                        "final_coords": "-0.180653, -78.467838",
                        "destination_invoice_id": "INV1001"
                    }
                }
            },
            "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b"
        }
    ]
}

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 []	List of risk items associated with a user
id	uuid	Unique identifier for the risk item
policy_id	uuid	Unique identifier for the associated policy
authorized_claimants	object []	List of authorized claimants
authorized_claimants.email	string	Email of the authorized claimant
authorized_claimants.name	string	Name of the authorized claimant
authorized_claimants.phone	string	Phone number of the authorized claimant
package_id	uuid	Unique identifier for the coverage package
start_date	string	Start date of the coverage period
end_date	string	End date of the coverage period
beneficiaries	object []	List of beneficiaries
beneficiaries.email	string	Email of the beneficiary
beneficiaries.name	string	Name of the beneficiary
beneficiaries.phone	string	Phone number of the beneficiary
beneficiaries.group_uid	string	Unique identifier for the beneficiary’s group
insured_subject	object	Details of the insured subject
insured_subject.identifier_value	string	Identifier of the insured subject
insured_subject.identifier_type	string	Type of identifier
insured_subject.ruc	string	Taxpayer identification number
insured_subject.driver_id	string	Driver's identification number
insured_subject.group_uid	string	Unique identifier of the insured group
insured_subject.group_name	string	Name of the insured group
insured_subject.policy_note	string	Policy coverage notes
insured_subject.guide_number	string	Tracking number for the shipment
insured_subject.plate_number	string	License plate of the transport vehicle
insured_subject.subject_type	string	Type of insured subject
insured_subject.invoice_count	number	Number of invoices related to the insured subject
insured_subject.departure_city	string	City of departure
insured_subject.departure_date	string	Departure date and time
insured_subject.content_category	string	Category of the transported content
insured_subject.departure_coords	string	GPS coordinates of departure location
insured_subject.destination_city	string	Destination city
insured_subject.driver_full_name	string	Full name of the driver
insured_subject.primary_category	string	Main category of insured items
insured_subject.business_industry	string	Industry related to the insured subject
insured_subject.policy_observations	string	Additional observations about the policy
insured_subject.total_insured_value	number	Total insured value in policy currency
status	string	Current status of the risk item
uid	string	Unique identifier
assets	object []	List of associated assets
metadata	object	Additional structured data

Update end date of a Risk Item

You can cancel a Risk Item by modifying its end-date

PATCH https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/cancel

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
riskItemId*	string	Risk item identifier

Body

Name	Type	Description
end_date*	date	End date of the Risk item. If you send "cancel" the current date is sent.

Example response

200: OK Retrieved successfully

{
    "data": {
        "id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
        "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b",
        "authorized_claimants": [
            {
                "email": "[email protected]",
                "name": "Lucia Martinez",
                "phone": "593999002823"
            },
            {
                "email": "[email protected]",
                "name": "Marco Reyes",
                "phone": "593999002824"
            }
        ],
        "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
        "start_date": "2024-03-15T00:00:00+00:00",
        "end_date": "2024-03-31T23:59:59.999+00:00",
        "beneficiaries": [
            {
                "email": "[email protected]",
                "phone": "593999002825"
            }
        ],
        "insured_subject": {
            "identifier_value": "GN789",
            "identifier_type": "Guide Number",
            "ruc": "1711186642001",
            "driver_id": "1714486642",
            "group_uid": "yourUID01",
            "group_name": "Ecuador Transport",
            "policy_note": "Insured against theft and damage",
            "guide_number": "GN789",
            "plate_number": "PICH1234",
            "subject_type": "cargo",
            "invoice_count": 10,
            "departure_city": "Guayaquil",
            "departure_date": "2024-01-24T09:00:00Z",
            "content_category": "Clothing",
            "departure_coords": "-2.170998, -79.922359",
            "destination_city": "Quito",
            "driver_full_name": "Luis Andrade",
            "primary_category": "Men's Apparel",
            "business_industry": "Consumo Masivo",
            "policy_observations": "Fragile items inside",
            "total_insured_value": 75000
        },
        "status": "ACTIVE",
        "uid": null,
        "assets": [],
        "metadata": {
            "delivery_stops": {
                "Delivery 1": {
                    "items": [
                        {
                            "item_sku": "LAP1234A",
                            "item_cost": 1200,
                            "item_name": "Laptop",
                            "item_expiry": "2024-12-31",
                            "item_quantity": 10
                        }
                    ],
                    "final_coords": "-0.180653, -78.467838",
                    "destination_invoice_id": "INV1001"
                }
            }
        }
    }
}

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	Object containing information about a risk item
id	uuid	Unique identifier for the risk item
policy_id	uuid	Unique identifier for the associated policy
authorized_claimants	object []	List of authorized claimants
authorized_claimants.email	string	Email of the authorized claimant
authorized_claimants.name	string	Name of the authorized claimant
authorized_claimants.phone	string	Phone number of the authorized claimant
package_id	uuid	Unique identifier for the coverage package
start_date	string	Start date of the coverage period
end_date	string	End date of the coverage period
beneficiaries	object []	List of beneficiaries
beneficiaries.email	string	Email of the beneficiary
beneficiaries.name	string	Name of the beneficiary
beneficiaries.phone	string	Phone number of the beneficiary
beneficiaries.group_uid	string	Unique identifier for the beneficiary’s group
insured_subject	object	Details of the insured subject
insured_subject.identifier_value	string	Identifier of the insured subject
insured_subject.identifier_type	string	Type of identifier
insured_subject.ruc	string	Taxpayer identification number
insured_subject.driver_id	string	Driver's identification number
insured_subject.group_uid	string	Unique identifier of the insured group
insured_subject.group_name	string	Name of the insured group
insured_subject.policy_note	string	Policy coverage notes
insured_subject.guide_number	string	Tracking number for the shipment
insured_subject.plate_number	string	License plate of the transport vehicle
insured_subject.subject_type	string	Type of insured subject
insured_subject.invoice_count	number	Number of invoices related to the insured subject
insured_subject.departure_city	string	City of departure
insured_subject.departure_date	string	Departure date and time
insured_subject.content_category	string	Category of the transported content
insured_subject.departure_coords	string	GPS coordinates of departure location
insured_subject.destination_city	string	Destination city
insured_subject.driver_full_name	string	Full name of the driver
insured_subject.primary_category	string	Main category of insured items
insured_subject.business_industry	string	Industry related to the insured subject
insured_subject.policy_observations	string	Additional observations about the policy
insured_subject.total_insured_value	number	Total insured value in policy currency
status	string	Current status of the risk item
uid	string	Unique identifier
assets	object []	List of associated assets
metadata	object	Additional structured data

Risk Item Rescission

This endpoint is useful to cancel a risk-item immediately

DELETE https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/rescission

Headers

Name	Type	Description
Authorization*	string	Bearer access token

Path Parameters

Name	Type	Description
riskItemId*	string	Risk item identifier

Example response

200: OK Retrieved successfully

{
    "data": {
        "id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
        "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b",
        "authorized_claimants": [
            {
                "email": "[email protected]",
                "name": "Lucia Martinez",
                "phone": "593999002823"
            },
            {
                "email": "[email protected]",
                "name": "Marco Reyes",
                "phone": "593999002824"
            }
        ],
        "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
        "start_date": "2024-03-15T00:00:00+00:00",
        "end_date": "2024-06-10T17:33:41.524+00:00",
        "beneficiaries": [
            {
                "email": "[email protected]",
                "phone": "593999002825"
            }
        ],
        "insured_subject": {
            "identifier_value": "GN789",
            "identifier_type": "Guide Number",
            "ruc": "1711186642001",
            "driver_id": "1714486642",
            "group_uid": "yourUID01",
            "group_name": "Ecuador Transport",
            "policy_note": "Insured against theft and damage",
            "guide_number": "GN789",
            "plate_number": "PICH1234",
            "subject_type": "cargo",
            "invoice_count": 10,
            "departure_city": "Guayaquil",
            "departure_date": "2024-01-24T09:00:00Z",
            "content_category": "Clothing",
            "departure_coords": "-2.170998, -79.922359",
            "destination_city": "Quito",
            "driver_full_name": "Luis Andrade",
            "primary_category": "Men's Apparel",
            "business_industry": "Consumo Masivo",
            "policy_observations": "Fragile items inside",
            "total_insured_value": 75000
        },
        "status": "INACTIVE",
        "uid": null,
        "assets": [],
        "metadata": {
            "delivery_stops": {
                "Delivery 1": {
                    "items": [
                        {
                            "item_sku": "LAP1234A",
                            "item_cost": 1200,
                            "item_name": "Laptop",
                            "item_expiry": "2024-12-31",
                            "item_quantity": 10
                        }
                    ],
                    "final_coords": "-0.180653, -78.467838",
                    "destination_invoice_id": "INV1001"
                }
            }
        }
    }
}

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	Object containing information about a risk item
id	uuid	Unique identifier for the risk item
policy_id	uuid	Unique identifier for the associated policy
authorized_claimants	object []	List of authorized claimants
authorized_claimants.email	string	Email of the authorized claimant
authorized_claimants.name	string	Name of the authorized claimant
authorized_claimants.phone	string	Phone number of the authorized claimant
package_id	uuid	Unique identifier for the coverage package
start_date	string	Start date of the coverage period
end_date	string	End date of the coverage period
beneficiaries	array	List of beneficiaries
beneficiaries.email	string	Email of the beneficiary
beneficiaries.name	string	Name of the beneficiary
beneficiaries.phone	string	Phone number of the beneficiary
beneficiaries.group_uid	string	Unique identifier for the beneficiary’s group
insured_subject	object	Details of the insured subject
insured_subject.identifier_value	string	Identifier of the insured subject
insured_subject.identifier_type	string	Type of identifier
insured_subject.ruc	string	Taxpayer identification number
insured_subject.driver_id	string	Driver's identification number
insured_subject.group_uid	string	Unique identifier of the insured group
insured_subject.group_name	string	Name of the insured group
insured_subject.policy_note	string	Policy coverage notes
insured_subject.guide_number	string	Tracking number for the shipment
insured_subject.plate_number	string	License plate of the transport vehicle
insured_subject.subject_type	string	Type of insured subject
insured_subject.invoice_count	number	Number of invoices related to the insured subject
insured_subject.departure_city	string	City of departure
insured_subject.departure_date	string	Departure date and time
insured_subject.content_category	string	Category of the transported content
insured_subject.departure_coords	string	GPS coordinates of departure location
insured_subject.destination_city	string	Destination city
insured_subject.driver_full_name	string	Full name of the driver
insured_subject.primary_category	string	Main category of insured items
insured_subject.business_industry	string	Industry related to the insured subject
insured_subject.policy_observations	string	Additional observations about the policy
insured_subject.total_insured_value	number	Total insured value in policy currency
status	string	Current status of the risk item
uid	string	Unique identifier
assets	object []	List of associated assets
metadata	object	Additional structured data