> For the complete documentation index, see [llms.txt](https://docs.insurehero.io/shield-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.insurehero.io/shield-api/policies/risk-item-management.md). # 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](/shield-api/policies/risk-item-management/risk-item-creation-examples.md), showcasing pre-configured payloads. These examples are illustrative, and adjustments may be necessary based on the insurance product and jurisdiction. ## Endpoints
MethodEndpoint
POSThttps://app.insurehero.io/api/shield/v1/risk-items
POSThttps://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/events
PUThttps://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/beneficiaries
GEThttps://app.insurehero.io/api/shield/v1/risk-items
GEThttps://app.insurehero.io/api/shield/v1/risk-items/:riskItemId
GEThttps://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/events
GEThttps://app.insurehero.io/api/shield/v1/users/:userId/risk-items
PATCHhttps://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/cancel
DELETEhttps://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/rescissions
All error responses use the `{ "error": string, "details": any }` envelope. The examples on this page show the most common cases for each endpoint; see [Error Handling](https://docs.insurehero.io/shield-api/data-dictionary#error-handling) for the general format, including unexpected internal errors, which return `422` with an `event_id` you can share with support. ## 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. The package must be part of the policy's product. | | policy\_uid\* | string | The uid of the policy associated. | | uid\* | string | Unique identifier of the risk item in your channel (1 to 64 characters). | | start\_date\* | string | Risk item starting date, ISO 8601 date-time with time zone (for example `2026-03-15T00:00:00.000Z`). | | end\_date | string \| null | Risk item ending date, ISO 8601 date-time with time zone. If omitted or `null`, the default end date configured for your channel is used, or `2099-12-31` when there is none. | | insured\_subject\* | object | Insured information to be included in the risk item. It is validated against the subject schema of the policy. `identifier_value` and `identifier_type` are optional strings of up to 100 characters. | | beneficiaries\* | object \[] | List of beneficiaries. Send `[]` when there are none. Each item must include the `email` or the `phone` key (its value can be `null`); any other field is stored as sent. | | authorized\_claimants | object \[] | List of users authorized to file claims. `email`, `phone` and `document_number` are optional; any other field is stored as sent. | | metadata | object | Additional data to include in the risk item | | payment\_model | string | `direct`, `channel_billed` or `included`. If omitted, it takes `payment.model`, or `direct` when no `payment` block is sent. | | payment | object | Payment information (see the table below). Required when `payment_model` is `direct`, unless `metadata.payment` includes `paymentTransactionId` and `merchantID`. | | payment\_status | string | `pending`, `confirmed`, `failed`, `channel_due` or `cancelled`. If omitted, it takes `payment.status`, or `confirmed` when no `payment` block is sent. | | current\_installment | number | Current installment number (integer, 0 or greater). Defaults to `1`. | | consents | object \[] | Consents accepted by the insured. Each item has `type` (string), `accepted` (boolean), `accepted_at` (ISO 8601 date-time with time zone) and `version` (string or `null`). | The `payment` object supports these fields: | Name | Type | Description | | --------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- | | model\* | string | `direct`, `channel_billed` or `included` | | status\* | string | `pending`, `confirmed`, `failed`, `channel_due` or `cancelled` | | billing\_entity\* | string | Entity that bills the payment | | billing\_cycle\* | string | `single`, `monthly`, `annual` or `per_event` | | channel\_sale\_id\* | string | Identifier of the sale in your channel | | sale\_origin\* | string | `pos`, `api`, `web_checkout`, `agent` or `batch` | | unit\_cost | number | Unit cost. For `direct` and `channel_billed` it is replaced by the catalog price of the package. | | unit\_cost\_currency | string | Unit cost currency. For `direct` and `channel_billed` it is replaced by the currency of your channel. | | transaction | object \| null | Transaction data from the payment processor | | processor | object \| null | Payment processor data | | method\_saved | object \| null | Saved payment method data | The risk item is created with status `ACTIVE`, and an order is created for it. For `direct` and `channel_billed`, the price is always taken from the package catalog. If the order cannot be created, the risk item is rolled back and the request returns `422`. #### Example response {% tabs %} {% tab title="201: Created Created successfully" %} ```json { "data": { "id": "f2131218-d320-5b45-9d26-29402855d2db", "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c", "authorized_claimants": [ { "email": "lucia.martinez@example.com", "name": "Lucia Martinez", "phone": "+593991234504" }, { "email": "marco.reyes@example.com", "name": "Marco Reyes", "phone": "+593991234505" } ], "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd", "start_date": "2026-03-15T00:00:00+00:00", "end_date": "2026-03-31T23:59:59.999+00:00", "beneficiaries": [ { "email": "ana.torres@example.com", "name": "Ana Torres", "phone": "+593991234503", "group_uid": "GRP-0001" } ], "insured_subject": { "identifier_value": "GN789", "identifier_type": "Guide Number", "ruc": "1790000001001", "driver_id": "1700000003", "group_uid": "GRP-0001", "group_name": "Andes Logistics S.A.", "policy_note": "Insured against theft and damage", "guide_number": "GN789", "plate_number": "PICH1234", "subject_type": "cargo", "invoice_count": 10, "departure_city": "Guayaquil", "departure_date": "2026-03-15T09:00:00Z", "content_category": "Clothing", "departure_coords": "-2.1894, -79.8891", "destination_city": "Quito", "driver_full_name": "Luis Paredes", "primary_category": "Men's Apparel", "business_industry": "Consumer goods", "policy_observations": "Fragile items inside", "total_insured_value": 75000 }, "status": "ACTIVE", "uid": "RI-0001", "assets": [], "payment_model": "included", "payment_status": "confirmed", "current_installment": 1, "consents": [], "payment": null, "metadata": { "delivery_stops": { "Delivery 1": { "items": [ { "item_sku": "LAP1234A", "item_cost": 1200, "item_name": "Laptop", "item_expiry": "2026-12-31", "item_quantity": 10 } ], "final_coords": "-0.1807, -78.4678", "destination_invoice_id": "INV-0001" } } } } } ``` {% endtab %} {% tab title="400: Bad Request Request contains malformed data" %} ```json { "error": "Request contains malformed data", "details": "Missing bearer token" } ``` {% endtab %} {% tab title="401: Unauthorized Invalid or expired access token" %} ```json { "error": "Invalid or expired access token", "details": "Invalid access token" } ``` {% endtab %} {% tab title="422: Unprocessable Entity Invalid request" %} ```json { "error": "Internal validation failed", "details": { "issues": [ { "code": "invalid_type", "expected": "string", "received": "undefined", "path": [ "body", "uid" ], "message": "Required" } ], "name": "ZodError" } } ``` {% endtab %} {% tab title="422: Unprocessable Entity Business rule" %} ```json { "error": "Internal validation failed", "details": "Package does not exist in this policy" } ``` {% endtab %} {% tab title="422: Unprocessable Entity Missing payment" %} ```json { "error": "Internal validation failed", "details": "payment_model 'direct' requires a payment block or metadata.payment with paymentTransactionId and merchantID" } ``` {% endtab %} {% tab title="422: Unprocessable Entity Invalid insured subject" %} ```json { "error": "Internal validation failed", "details": { "message": "Validation failed in insured_subject", "details": [ { "message": "Required", "path": "identifier_value" } ] } } ``` {% endtab %} {% tab title="422: Unprocessable Entity Duplicated uid" %} ```json { "error": "Internal validation failed", "details": { "code": "P0001", "details": null, "hint": null, "message": "Risk Item uid must be unique within the same channel" } } ``` {% endtab %} {% tab title="422: Unprocessable Entity Internal error" %} ```json { "error": "Internal validation failed", "details": { "message": "Internal error", "event_id": "4f6c1d2a9b8e4c7f8a1d3e5b7c9f0a2d" } } ``` {% endtab %} {% endtabs %} Other business rule messages returned in `details` are `"Package does not exist in this channel"`, `"Policy does not exist in this channel"` and `"Risk item rolled back: order creation failed - "`. #### Attributes | Name | Type | Description | | -------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- | | data | object | Object containing information about a risk item | | id | uuid | Unique identifier for the risk item | | policy\_id | uuid \| null | 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 \| null | 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: `ACTIVE`, `INACTIVE`, `PENDING`, `RESCISSION`, `EXPIRED` or `CANCELLED` | | uid | string \| null | Unique identifier | | assets | object \[] | List of associated assets | | metadata | object | Additional structured data | | payment\_model | string \| null | Payment model: `direct`, `channel_billed` or `included` | | payment\_status | string | Payment status: `pending`, `confirmed`, `failed`, `channel_due` or `cancelled` | | current\_installment | number | Current installment number | | consents | object \[] | Consents accepted by the insured | | payment | object \| null | Payment information sent when the risk item was created | ### 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\* | uuid | Risk item identifier (`id`) | #### Request Body | Name | Type | Description | | --------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | event\_data\* | object | Additional data related to an event. `start_date` and `end_date` are required (ISO 8601 date-time with time zone); any other field is stored as sent. | | metadata | object | Additional data to include in the event. Defaults to `{}` | | uid | string \| null | Unique identifier for the event (1 to 64 characters) | #### Example response {% tabs %} {% tab title="201: Created Created successfully" %} ```json { "data": { "id": "0d2e5561-9fba-585b-83d7-1ab564c2cd9d", "risk_item_id": "f2131218-d320-5b45-9d26-29402855d2db", "event_data": { "start_date": "2026-03-15T00:00:00.000Z", "end_date": "2026-03-31T00:00:00.000Z" }, "metadata": { "description": "Event description" }, "uid": "EVT-0001" } } ``` {% endtab %} {% tab title="400: Bad Request Request contains malformed data" %} ```json { "error": "Request contains malformed data", "details": "Missing bearer token" } ``` {% endtab %} {% tab title="401: Unauthorized Invalid or expired access token" %} ```json { "error": "Invalid or expired access token", "details": "Invalid access token" } ``` {% endtab %} {% tab title="422: Unprocessable Entity Invalid request" %} ```json { "error": "Internal validation failed", "details": { "issues": [ { "code": "invalid_type", "expected": "string", "received": "undefined", "path": [ "body", "event_data", "end_date" ], "message": "Required" } ], "name": "ZodError" } } ``` {% endtab %} {% tab title="422: Unprocessable Entity Risk item not found" %} ```json { "error": "Internal validation failed", "details": "Risk item does not exist in this channel" } ``` {% endtab %} {% endtabs %} #### 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 \| null | 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 with `401`. #### 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\* | uuid | Risk item identifier (`id`) | #### 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 | | isTraveler\* | boolean | Indicates if the beneficiary is a traveler | | 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 | | added\_at | string | Date when the beneficiary was added | | insuredId | number \| null | Insured identifier | Additional fields are accepted and preserved. #### Example request ```json { "beneficiaries": [ { "name": "Ana", "lastname": "Torres", "isHolder": true, "isTraveler": true, "dateOfBirth": "1992-11-03", "fiscalType": "CI", "fiscalId": "1700000004", "documentCountry": "EC", "email": "ana.torres@example.com", "phone": "+593991234503", "mobilePrefix": "593", "source": "channel" } ] } ``` #### Example response The response contains the full updated risk item record; the example below is abbreviated. {% tabs %} {% tab title="200: OK Beneficiaries updated" %} ```json { "data": { "id": "f2131218-d320-5b45-9d26-29402855d2db", "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c", "status": "ACTIVE", "beneficiaries": [ { "name": "Ana", "lastname": "Torres", "isHolder": true, "isTraveler": true, "dateOfBirth": "1992-11-03", "fiscalType": "CI", "fiscalId": "1700000004", "documentCountry": "EC", "email": "ana.torres@example.com", "phone": "+593991234503", "mobilePrefix": "593", "source": "channel" } ] } } ``` {% endtab %} {% tab title="400: Bad Request Invalid JSON or beneficiaries payload" %} ```json { "data": { "message": "beneficiaries inválido" } } ``` {% endtab %} {% tab title="401: Unauthorized Invalid, expired, or unauthorized token" %} ```json { "error": "Invalid or expired access token", "details": "Token inválido o expirado (post-sales o JWT de canal /auth/authorize)" } ``` {% endtab %} {% tab title="422: Unprocessable Entity Risk item not found" %} ```json { "error": "Internal validation failed", "details": { "code": "PGRST116", "details": "The result contains 0 rows", "hint": null, "message": "Cannot coerce the result to a single JSON object" } } ``` {% endtab %} {% endtabs %} When the body is not valid JSON, the `400` message is `"Body JSON inválido"`. When the risk item belongs to another channel, the `401` `details` is `"No tienes acceso a este risk item"`. #### Attributes | Name | Type | Description | | ------------------ | ------------ | ----------------------------- | | data | object | Updated risk item | | data.id | uuid | Risk item identifier | | data.policy\_id | uuid \| null | 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
NameTypeDescription
from*numberStarting record index (0-based)
to*numberEnding record index (inclusive). Must be greater than from; the range cannot exceed 100 records
policyIduuidReturns only the risk items of this policy
start_datedateReturns only the risk items created from this date. Must be sent together with end_date
end_datedateReturns only the risk items created up to this date (the whole day is included). Must be sent together with start_date; the range cannot exceed 6 months
statusstringReturns only the risk items with this status: ACTIVE, INACTIVE, PENDING, RESCISSION, EXPIRED or CANCELLED
#### Example response {% tabs %} {% tab title="200: OK Retrieved successfully" %} ```json { "data": [ { "id": "7ee10950-2b16-5718-bb99-c80eb7387cca", "authorized_claimants": [ { "email": "lucia.martinez@example.com", "name": "Lucia Martinez", "phone": "+593991234504" }, { "email": "marco.reyes@example.com", "name": "Marco Reyes", "phone": "+593991234505" } ], "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd", "start_date": "2026-03-15T00:00:00+00:00", "end_date": "2026-03-31T23:59:59.999+00:00", "beneficiaries": [ { "email": "ana.torres@example.com", "phone": "+593991234503" } ], "insured_subject": { "identifier_value": "GN789", "identifier_type": "Guide Number", "ruc": "1790000001001", "driver_id": "1700000003", "group_uid": "GRP-0001", "group_name": "Andes Logistics S.A.", "policy_note": "Insured against theft and damage", "guide_number": "GN789", "plate_number": "PICH1234", "subject_type": "cargo", "invoice_count": 10, "departure_city": "Guayaquil", "departure_date": "2026-03-15T09:00:00Z", "content_category": "Clothing", "departure_coords": "-2.1894, -79.8891", "destination_city": "Quito", "driver_full_name": "Luis Paredes", "primary_category": "Men's Apparel", "business_industry": "Consumer goods", "policy_observations": "Fragile items inside", "total_insured_value": 75000 }, "status": "ACTIVE", "uid": null, "assets": [], "payment_model": "included", "payment_status": "confirmed", "current_installment": 1, "consents": [], "payment": null, "metadata": { "delivery_stops": { "Delivery 1": { "items": [ { "item_sku": "LAP1234A", "item_cost": 1200, "item_name": "Laptop", "item_expiry": "2026-12-31", "item_quantity": 10 } ], "final_coords": "-0.1807, -78.4678", "destination_invoice_id": "INV-0001" } } }, "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c" }, { "id": "f2131218-d320-5b45-9d26-29402855d2db", "authorized_claimants": [ { "email": "lucia.martinez@example.com", "name": "Lucia Martinez", "phone": "+593991234504" }, { "email": "marco.reyes@example.com", "name": "Marco Reyes", "phone": "+593991234505" } ], "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd", "start_date": "2026-03-15T00:00:00+00:00", "end_date": "2026-03-31T23:59:59.999+00:00", "beneficiaries": [ { "email": "ana.torres@example.com", "name": "Ana Torres", "phone": "+593991234503", "group_uid": "GRP-0001" } ], "insured_subject": { "identifier_value": "GN789", "identifier_type": "Guide Number", "ruc": "1790000001001", "driver_id": "1700000003", "group_uid": "GRP-0001", "group_name": "Andes Logistics S.A.", "policy_note": "Insured against theft and damage", "guide_number": "GN789", "plate_number": "PICH1234", "subject_type": "cargo", "invoice_count": 10, "departure_city": "Guayaquil", "departure_date": "2026-03-15T09:00:00Z", "content_category": "Clothing", "departure_coords": "-2.1894, -79.8891", "destination_city": "Quito", "driver_full_name": "Luis Paredes", "primary_category": "Men's Apparel", "business_industry": "Consumer goods", "policy_observations": "Fragile items inside", "total_insured_value": 75000 }, "status": "ACTIVE", "uid": null, "assets": [], "payment_model": "included", "payment_status": "confirmed", "current_installment": 1, "consents": [], "payment": null, "metadata": { "delivery_stops": { "Delivery 1": { "items": [ { "item_sku": "LAP1234A", "item_cost": 1200, "item_name": "Laptop", "item_expiry": "2026-12-31", "item_quantity": 10 } ], "final_coords": "-0.1807, -78.4678", "destination_invoice_id": "INV-0001" } } }, "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c" } ] } ``` {% endtab %} {% tab title="400: Bad Request Request contains malformed data" %} ```json { "error": "Request contains malformed data", "details": "Missing bearer token" } ``` {% endtab %} {% tab title="401: Unauthorized Invalid or expired access token" %} ```json { "error": "Invalid or expired access token", "details": "Invalid access token" } ``` {% endtab %} {% tab title="422: Unprocessable Entity Internal validation failed" %} ```json { "error": "Internal validation failed", "details": { "issues": [ { "code": "custom", "path": [ "searchParams", "from" ], "message": "Invalid range. 'from' must be less than or equal to 'to'" } ], "name": "ZodError" } } ``` {% endtab %} {% endtabs %} #### Attributes | Name | Type | Description | | -------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------- | | data | object \[] | List of risk items | | id | uuid | Unique identifier for the risk item | | policy\_id | uuid \| null | 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 \| null | 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: `ACTIVE`, `INACTIVE`, `PENDING`, `RESCISSION`, `EXPIRED` or `CANCELLED` | | uid | string \| null | Unique identifier | | assets | object \[] | List of associated assets | | metadata | object | Additional structured data | | payment\_model | string \| null | Payment model: `direct`, `channel_billed` or `included` | | payment\_status | string | Payment status: `pending`, `confirmed`, `failed`, `channel_due` or `cancelled` | | current\_installment | number | Current installment number | | consents | object \[] | Consents accepted by the insured | | payment | object \| null | Payment information sent when the risk item was created | | external\_id | number | Numeric identifier assigned to the risk item within your channel. Only present when one has been assigned | ### 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 (`id` by default, or its `uid`) | #### Query Parameters | Name | Type | Description | | -------- | ------ | ----------------------------------------------------------------------------------------------- | | searchBy | string | Field used to find the risk item: `id` (default) or `uid`. Use `?searchBy=uid` to send the uid. | #### Example response {% tabs %} {% tab title="200: OK Retrieved successfully" %} ```json { "data": { "id": "7ee10950-2b16-5718-bb99-c80eb7387cca", "authorized_claimants": [ { "email": "lucia.martinez@example.com", "name": "Lucia Martinez", "phone": "+593991234504" }, { "email": "marco.reyes@example.com", "name": "Marco Reyes", "phone": "+593991234505" } ], "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd", "start_date": "2026-03-15T00:00:00+00:00", "end_date": "2026-03-31T23:59:59.999+00:00", "beneficiaries": [ { "email": "ana.torres@example.com", "phone": "+593991234503" } ], "insured_subject": { "identifier_value": "GN789", "identifier_type": "Guide Number", "ruc": "1790000001001", "driver_id": "1700000003", "group_uid": "GRP-0001", "group_name": "Andes Logistics S.A.", "policy_note": "Insured against theft and damage", "guide_number": "GN789", "plate_number": "PICH1234", "subject_type": "cargo", "invoice_count": 10, "departure_city": "Guayaquil", "departure_date": "2026-03-15T09:00:00Z", "content_category": "Clothing", "departure_coords": "-2.1894, -79.8891", "destination_city": "Quito", "driver_full_name": "Luis Paredes", "primary_category": "Men's Apparel", "business_industry": "Consumer goods", "policy_observations": "Fragile items inside", "total_insured_value": 75000 }, "status": "ACTIVE", "uid": null, "assets": [], "payment_model": "included", "payment_status": "confirmed", "current_installment": 1, "consents": [], "payment": null, "metadata": { "delivery_stops": { "Delivery 1": { "items": [ { "item_sku": "LAP1234A", "item_cost": 1200, "item_name": "Laptop", "item_expiry": "2026-12-31", "item_quantity": 10 } ], "final_coords": "-0.1807, -78.4678", "destination_invoice_id": "INV-0001" } } }, "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c" } } ``` {% endtab %} {% tab title="400: Bad Request Request contains malformed data" %} ```json { "error": "Request contains malformed data", "details": "Missing bearer token" } ``` {% endtab %} {% tab title="401: Unauthorized Invalid or expired access token" %} ```json { "error": "Invalid or expired access token", "details": "Invalid access token" } ``` {% endtab %} {% tab title="404: Not Found Risk item not found" %} ```json { "error": "Resource not found", "details": "Risk item not found" } ``` {% endtab %} {% endtabs %} #### Attributes | Name | Type | Description | | -------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------- | | data | object | Object containing information about a risk item | | id | uuid | Unique identifier for the risk item | | policy\_id | uuid \| null | 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 \| null | 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: `ACTIVE`, `INACTIVE`, `PENDING`, `RESCISSION`, `EXPIRED` or `CANCELLED` | | uid | string \| null | Unique identifier | | assets | object \[] | List of associated assets | | metadata | object | Additional structured data | | payment\_model | string \| null | Payment model: `direct`, `channel_billed` or `included` | | payment\_status | string | Payment status: `pending`, `confirmed`, `failed`, `channel_due` or `cancelled` | | current\_installment | number | Current installment number | | consents | object \[] | Consents accepted by the insured | | payment | object \| null | Payment information sent when the risk item was created | | external\_id | number | Numeric identifier assigned to the risk item within your channel. Only present when one has been assigned | ## Additional resources ### Get Risk Item events `GET` `https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/events` Returns the risk item together with its events. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------- | | Authorization\* | string | Bearer access token | #### Path Parameters | Name | Type | Description | | -------------------------------------------- | ---- | -------------------------------------------------- | | riskItemId\* | uuid | The id of the risk item associated with the events | #### Example response {% tabs %} {% tab title="200: OK Retrieved successfully" %} ```json { "data": { "id": "f2131218-d320-5b45-9d26-29402855d2db", "authorized_claimants": [ { "email": "lucia.martinez@example.com", "name": "Lucia Martinez", "phone": "+593991234504" }, { "email": "marco.reyes@example.com", "name": "Marco Reyes", "phone": "+593991234505" } ], "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd", "start_date": "2026-03-15T00:00:00+00:00", "end_date": "2026-03-31T23:59:59.999+00:00", "beneficiaries": [ { "email": "ana.torres@example.com", "name": "Ana Torres", "phone": "+593991234503", "group_uid": "GRP-0001" } ], "insured_subject": { "identifier_value": "GN789", "identifier_type": "Guide Number", "ruc": "1790000001001", "driver_id": "1700000003", "group_uid": "GRP-0001", "group_name": "Andes Logistics S.A.", "policy_note": "Insured against theft and damage", "guide_number": "GN789", "plate_number": "PICH1234", "subject_type": "cargo", "invoice_count": 10, "departure_city": "Guayaquil", "departure_date": "2026-03-15T09:00:00Z", "content_category": "Clothing", "departure_coords": "-2.1894, -79.8891", "destination_city": "Quito", "driver_full_name": "Luis Paredes", "primary_category": "Men's Apparel", "business_industry": "Consumer goods", "policy_observations": "Fragile items inside", "total_insured_value": 75000 }, "status": "ACTIVE", "uid": null, "assets": [], "payment_model": "included", "payment_status": "confirmed", "current_installment": 1, "consents": [], "payment": null, "metadata": { "delivery_stops": { "Delivery 1": { "items": [ { "item_sku": "LAP1234A", "item_cost": 1200, "item_name": "Laptop", "item_expiry": "2026-12-31", "item_quantity": 10 } ], "final_coords": "-0.1807, -78.4678", "destination_invoice_id": "INV-0001" } } }, "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c", "events": [ { "id": "0d2e5561-9fba-585b-83d7-1ab564c2cd9d", "risk_item_id": "f2131218-d320-5b45-9d26-29402855d2db", "metadata": { "clientName": "Andes Logistics S.A.", "policyNote": "Insured against theft, damage, and loss during transportation.", "guideNumber": "GN789", "plateNumber": "PICH1234", "invoiceCount": 10, "departureCity": "Guayaquil", "contentCategory": "Clothing", "destinationCity": "Quito", "primaryCategory": "Men's Apparel", "totalInsuredValue": 75000, "policyObservations": "Fragile items inside" }, "event_data": { "invoiceCount": 3, "contentCategory": "Shirt" }, "uid": "EVT-0001" }, { "id": "f04d2072-88cd-53c8-89fb-16c02fb23d29", "risk_item_id": "f2131218-d320-5b45-9d26-29402855d2db", "metadata": { "clientName": "Andes Logistics S.A.", "policyNote": "Insured against theft, damage, and loss during transportation.", "guideNumber": "GN789", "plateNumber": "PICH1234", "invoiceCount": 10, "departureCity": "Guayaquil", "contentCategory": "Clothing", "destinationCity": "Quito", "primaryCategory": "Men's Apparel", "totalInsuredValue": 75000, "policyObservations": "Fragile items inside" }, "event_data": { "invoiceCount": 3, "contentCategory": "Shirt" }, "uid": null } ] } } ``` {% endtab %} {% tab title="400: Bad Request Request contains malformed data" %} ```json { "error": "Request contains malformed data", "details": "Missing bearer token" } ``` {% endtab %} {% tab title="401: Unauthorized Invalid or expired access token" %} ```json { "error": "Invalid or expired access token", "details": "Invalid access token" } ``` {% endtab %} {% tab title="422: Unprocessable Entity Risk item not found" %} ```json { "error": "Internal validation failed", "details": { "code": "PGRST116", "details": "The result contains 0 rows", "hint": null, "message": "Cannot coerce the result to a single JSON object" } } ``` {% endtab %} {% endtabs %} A risk item that does not exist in your channel returns `422` with the database error `PGRST116`, not `404`. #### Attributes The response contains the same risk item attributes described in [Get the data of a given Risk Item](#get-the-data-of-a-given-risk-item), plus: | Name | Type | Description | | --------------------- | -------------- | ---------------------------------------------- | | events | object \[] | List of events of the risk item | | events.id | uuid | Unique identifier for the event | | events.risk\_item\_id | uuid | Unique identifier for the associated risk item | | events.metadata | object | Additional event metadata | | events.event\_data | object \| null | Event-related details. Free-form JSON | | events.uid | string \| null | Unique event identifier | ### Get Risk Item by user Returns the risk items where the user is an authorized claimant. `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, in the format given by `searchBy` | #### Query Parameters | Name | Type | Description | | -------- | ------ | ------------------------------------------------------------------------------------------ | | searchBy | string | Field used to find the user: `id` (default), `uid`, `email`, `phone` or `document_number`. | #### Example response {% tabs %} {% tab title="200: OK Retrieved successfully" %} ```json { "data": [ { "id": "7ee10950-2b16-5718-bb99-c80eb7387cca", "authorized_claimants": [ { "email": "lucia.martinez@example.com", "name": "Lucia Martinez", "phone": "+593991234504" }, { "email": "marco.reyes@example.com", "name": "Marco Reyes", "phone": "+593991234505" } ], "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd", "start_date": "2026-03-15T00:00:00+00:00", "end_date": "2026-03-31T23:59:59.999+00:00", "beneficiaries": [ { "email": "ana.torres@example.com", "phone": "+593991234503" } ], "insured_subject": { "identifier_value": "GN789", "identifier_type": "Guide Number", "ruc": "1790000001001", "driver_id": "1700000003", "group_uid": "GRP-0001", "group_name": "Andes Logistics S.A.", "policy_note": "Insured against theft and damage", "guide_number": "GN789", "plate_number": "PICH1234", "subject_type": "cargo", "invoice_count": 10, "departure_city": "Guayaquil", "departure_date": "2026-03-15T09:00:00Z", "content_category": "Clothing", "departure_coords": "-2.1894, -79.8891", "destination_city": "Quito", "driver_full_name": "Luis Paredes", "primary_category": "Men's Apparel", "business_industry": "Consumer goods", "policy_observations": "Fragile items inside", "total_insured_value": 75000 }, "status": "ACTIVE", "uid": null, "assets": [], "payment_model": "included", "payment_status": "confirmed", "current_installment": 1, "consents": [], "payment": null, "metadata": { "delivery_stops": { "Delivery 1": { "items": [ { "item_sku": "LAP1234A", "item_cost": 1200, "item_name": "Laptop", "item_expiry": "2026-12-31", "item_quantity": 10 } ], "final_coords": "-0.1807, -78.4678", "destination_invoice_id": "INV-0001" } } }, "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c" }, { "id": "f2131218-d320-5b45-9d26-29402855d2db", "authorized_claimants": [ { "email": "lucia.martinez@example.com", "name": "Lucia Martinez", "phone": "+593991234504" }, { "email": "marco.reyes@example.com", "name": "Marco Reyes", "phone": "+593991234505" } ], "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd", "start_date": "2026-03-15T00:00:00+00:00", "end_date": "2026-03-31T23:59:59.999+00:00", "beneficiaries": [ { "email": "ana.torres@example.com", "name": "Ana Torres", "phone": "+593991234503", "group_uid": "GRP-0001" } ], "insured_subject": { "identifier_value": "GN789", "identifier_type": "Guide Number", "ruc": "1790000001001", "driver_id": "1700000003", "group_uid": "GRP-0001", "group_name": "Andes Logistics S.A.", "policy_note": "Insured against theft and damage", "guide_number": "GN789", "plate_number": "PICH1234", "subject_type": "cargo", "invoice_count": 10, "departure_city": "Guayaquil", "departure_date": "2026-03-15T09:00:00Z", "content_category": "Clothing", "departure_coords": "-2.1894, -79.8891", "destination_city": "Quito", "driver_full_name": "Luis Paredes", "primary_category": "Men's Apparel", "business_industry": "Consumer goods", "policy_observations": "Fragile items inside", "total_insured_value": 75000 }, "status": "ACTIVE", "uid": null, "assets": [], "payment_model": "included", "payment_status": "confirmed", "current_installment": 1, "consents": [], "payment": null, "metadata": { "delivery_stops": { "Delivery 1": { "items": [ { "item_sku": "LAP1234A", "item_cost": 1200, "item_name": "Laptop", "item_expiry": "2026-12-31", "item_quantity": 10 } ], "final_coords": "-0.1807, -78.4678", "destination_invoice_id": "INV-0001" } } }, "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c" } ] } ``` {% endtab %} {% tab title="400: Bad Request Request contains malformed data" %} ```json { "error": "Request contains malformed data", "details": "Missing bearer token" } ``` {% endtab %} {% tab title="401: Unauthorized Invalid or expired access token" %} ```json { "error": "Invalid or expired access token", "details": "Invalid access token" } ``` {% endtab %} {% tab title="404: Not Found User not found" %} ```json { "error": "Resource not found", "details": "User not found" } ``` {% endtab %} {% endtabs %} #### 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 \| null | 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 \| null | 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: `ACTIVE`, `INACTIVE`, `PENDING`, `RESCISSION`, `EXPIRED` or `CANCELLED` | | uid | string \| null | Unique identifier | | assets | object \[] | List of associated assets | | metadata | object | Additional structured data | | payment\_model | string \| null | Payment model: `direct`, `channel_billed` or `included` | | payment\_status | string | Payment status: `pending`, `confirmed`, `failed`, `channel_due` or `cancelled` | | current\_installment | number | Current installment number | | consents | object \[] | Consents accepted by the insured | | payment | object \| null | Payment information sent when the risk item was created | ### 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 (`id` by default, or its `uid`) | #### Query Parameters | Name | Type | Description | | -------- | ------ | ----------------------------------------------------------------------------------------------- | | searchBy | string | Field used to find the risk item: `id` (default) or `uid`. Use `?searchBy=uid` to send the uid. | #### Body | Name | Type | Description | | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | | end\_date | string | New end date of the Risk item, ISO 8601 date-time with time zone, or `"cancel"`. If omitted or `"cancel"`, the current date is used. | The body must be a JSON object; send `{}` to cancel with the current date. * If `end_date` is today (or omitted, or `"cancel"`), the risk item status changes to `CANCELLED`, its `end_date` is set, and the subscription of the risk item, if any, expires on that date. * If `end_date` is a future date, only the `end_date` of the risk item changes; its status does not change. * If `end_date` is earlier than today, the request returns `422`. * If the risk item is already `CANCELLED`, it is returned unchanged. #### Example response {% tabs %} {% tab title="200: OK Retrieved successfully" %} ```json { "data": { "id": "7ee10950-2b16-5718-bb99-c80eb7387cca", "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c", "authorized_claimants": [ { "email": "lucia.martinez@example.com", "name": "Lucia Martinez", "phone": "+593991234504" }, { "email": "marco.reyes@example.com", "name": "Marco Reyes", "phone": "+593991234505" } ], "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd", "start_date": "2026-03-15T00:00:00+00:00", "end_date": "2026-03-20T15:02:11.381+00:00", "beneficiaries": [ { "email": "ana.torres@example.com", "phone": "+593991234503" } ], "insured_subject": { "identifier_value": "GN789", "identifier_type": "Guide Number", "ruc": "1790000001001", "driver_id": "1700000003", "group_uid": "GRP-0001", "group_name": "Andes Logistics S.A.", "policy_note": "Insured against theft and damage", "guide_number": "GN789", "plate_number": "PICH1234", "subject_type": "cargo", "invoice_count": 10, "departure_city": "Guayaquil", "departure_date": "2026-03-15T09:00:00Z", "content_category": "Clothing", "departure_coords": "-2.1894, -79.8891", "destination_city": "Quito", "driver_full_name": "Luis Paredes", "primary_category": "Men's Apparel", "business_industry": "Consumer goods", "policy_observations": "Fragile items inside", "total_insured_value": 75000 }, "status": "CANCELLED", "uid": null, "assets": [], "payment_model": "included", "payment_status": "confirmed", "current_installment": 1, "consents": [], "payment": null, "metadata": { "delivery_stops": { "Delivery 1": { "items": [ { "item_sku": "LAP1234A", "item_cost": 1200, "item_name": "Laptop", "item_expiry": "2026-12-31", "item_quantity": 10 } ], "final_coords": "-0.1807, -78.4678", "destination_invoice_id": "INV-0001" } } } } } ``` {% endtab %} {% tab title="400: Bad Request Request contains malformed data" %} ```json { "error": "Request contains malformed data", "details": "Missing bearer token" } ``` {% endtab %} {% tab title="401: Unauthorized Invalid or expired access token" %} ```json { "error": "Invalid or expired access token", "details": "Invalid access token" } ``` {% endtab %} {% tab title="422: Unprocessable Entity Risk item not found" %} ```json { "error": "Internal validation failed", "details": { "code": "PGRST116", "details": "The result contains 0 rows", "hint": null, "message": "Cannot coerce the result to a single JSON object" } } ``` {% endtab %} {% tab title="422: Unprocessable Entity Past end date" %} ```json { "error": "Internal validation failed", "details": "end_date cannot be earlier than the current date" } ``` {% endtab %} {% tab title="422: Unprocessable Entity Invalid request body" %} ```json { "error": "Internal validation failed", "details": { "issues": [ { "code": "custom", "path": [ "body" ], "message": "Invalid request body" } ], "name": "ZodError" } } ``` {% endtab %} {% endtabs %} #### Attributes | Name | Type | Description | | -------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- | | data | object | Object containing information about a risk item | | id | uuid | Unique identifier for the risk item | | policy\_id | uuid \| null | 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 \| null | 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: `ACTIVE`, `INACTIVE`, `PENDING`, `RESCISSION`, `EXPIRED` or `CANCELLED` | | uid | string \| null | Unique identifier | | assets | object \[] | List of associated assets | | metadata | object | Additional structured data | | payment\_model | string \| null | Payment model: `direct`, `channel_billed` or `included` | | payment\_status | string | Payment status: `pending`, `confirmed`, `failed`, `channel_due` or `cancelled` | | current\_installment | number | Current installment number | | consents | object \[] | Consents accepted by the insured | | payment | object \| null | Payment information sent when the risk item was created | ### Risk Item Rescission This endpoint is useful to cancel a risk-item immediately `DELETE` `https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/rescissions` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------- | | Authorization\* | string | Bearer access token | #### Path Parameters | Name | Type | Description | | -------------------------------------------- | ------ | ---------------------------------------------------- | | riskItemId\* | string | Risk item identifier (`id` by default, or its `uid`) | #### Query Parameters | Name | Type | Description | | -------- | ------ | ----------------------------------------------------------------------------------------------- | | searchBy | string | Field used to find the risk item: `id` (default) or `uid`. Use `?searchBy=uid` to send the uid. | A rescission is only allowed within the `max_rescission_window` of the policy (in minutes, counted from the creation of the risk item). After that window, or when the policy has no window configured, the request returns `422`. A rescinded risk item gets status `INACTIVE` and the current date as `end_date`, its subscription expires, and its orders are cancelled. #### Example response {% tabs %} {% tab title="200: OK Retrieved successfully" %} ```json { "data": { "id": "7ee10950-2b16-5718-bb99-c80eb7387cca", "policy_id": "9b53e9c9-17b3-5d9c-b5fd-e1780096cc8c", "authorized_claimants": [ { "email": "lucia.martinez@example.com", "name": "Lucia Martinez", "phone": "+593991234504" }, { "email": "marco.reyes@example.com", "name": "Marco Reyes", "phone": "+593991234505" } ], "package_id": "af9c0bd9-37d9-51b7-b03f-0a04c13345dd", "start_date": "2026-03-15T00:00:00+00:00", "end_date": "2026-03-15T17:33:41.524+00:00", "beneficiaries": [ { "email": "ana.torres@example.com", "phone": "+593991234503" } ], "insured_subject": { "identifier_value": "GN789", "identifier_type": "Guide Number", "ruc": "1790000001001", "driver_id": "1700000003", "group_uid": "GRP-0001", "group_name": "Andes Logistics S.A.", "policy_note": "Insured against theft and damage", "guide_number": "GN789", "plate_number": "PICH1234", "subject_type": "cargo", "invoice_count": 10, "departure_city": "Guayaquil", "departure_date": "2026-03-15T09:00:00Z", "content_category": "Clothing", "departure_coords": "-2.1894, -79.8891", "destination_city": "Quito", "driver_full_name": "Luis Paredes", "primary_category": "Men's Apparel", "business_industry": "Consumer goods", "policy_observations": "Fragile items inside", "total_insured_value": 75000 }, "status": "INACTIVE", "uid": null, "assets": [], "payment_model": "included", "payment_status": "confirmed", "current_installment": 1, "consents": [], "payment": null, "metadata": { "delivery_stops": { "Delivery 1": { "items": [ { "item_sku": "LAP1234A", "item_cost": 1200, "item_name": "Laptop", "item_expiry": "2026-12-31", "item_quantity": 10 } ], "final_coords": "-0.1807, -78.4678", "destination_invoice_id": "INV-0001" } } } } } ``` {% endtab %} {% tab title="400: Bad Request Request contains malformed data" %} ```json { "error": "Request contains malformed data", "details": "Missing bearer token" } ``` {% endtab %} {% tab title="401: Unauthorized Invalid or expired access token" %} ```json { "error": "Invalid or expired access token", "details": "Invalid access token" } ``` {% endtab %} {% tab title="422: Unprocessable Entity Rescission window expired" %} ```json { "error": "Internal validation failed", "details": "The maximum rescission time has expired." } ``` {% endtab %} {% tab title="422: Unprocessable Entity Risk item not found" %} ```json { "error": "Internal validation failed", "details": { "code": "PGRST116", "details": "The result contains 0 rows", "hint": null, "message": "Cannot coerce the result to a single JSON object" } } ``` {% endtab %} {% endtabs %} #### Attributes | Name | Type | Description | | -------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- | | data | object | Object containing information about a risk item | | id | uuid | Unique identifier for the risk item | | policy\_id | uuid \| null | 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 \| null | 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: `ACTIVE`, `INACTIVE`, `PENDING`, `RESCISSION`, `EXPIRED` or `CANCELLED` | | uid | string \| null | Unique identifier | | assets | object \[] | List of associated assets | | metadata | object | Additional structured data | | payment\_model | string \| null | Payment model: `direct`, `channel_billed` or `included` | | payment\_status | string | Payment status: `pending`, `confirmed`, `failed`, `channel_due` or `cancelled` | | current\_installment | number | Current installment number | | consents | object \[] | Consents accepted by the insured | | payment | object \| null | Payment information sent when the risk item was created |