> 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/risk-item-creation-examples.md).

# Risk item creation examples

{% hint style="info" %}
**Payment information**

If you do not send `payment_model`, it defaults to `direct`, which requires a `payment` block (or `metadata.payment` with `paymentTransactionId` and `merchantID`). The examples below send `payment_model` and `payment`; use the values that match your billing agreement. See [Add a Risk Item to a policy](https://docs.insurehero.io/shield-api/policies/risk-item-management#add-a-risk-item-to-a-policy) for all the fields.
{% endhint %}

### Risk item for cargo insurance

In this example, we will create a risk item for a cargo insured against damage and/or theft.

**/risk-items** body payload:

```json
{
  "package_uid": "PKG-CARGO",
  "policy_uid": "POL-0001",
  "start_date": "2026-03-15T00:00:00.000Z",
  "end_date": "2026-03-31T23:59:59.999Z",
  "insured_subject": {
    "identifier_type": "Guide Number",
    "identifier_value": "GN789",
    "group_uid": "GRP-0001",
    "group_name": "Andes Logistics S.A.",
    "business_industry": "Consumer goods",
    "subject_type": "cargo",
    "invoice_count": 10,
    "total_insured_value": 75000.00,
    "guide_number": "GN789",
    "departure_city": "Guayaquil",
    "destination_city": "Quito",
    "departure_date": "2026-03-15T09:00:00.000Z",
    "plate_number": "PICH1234",
    "primary_category": "Men's Apparel",
    "content_category": "Clothing",
    "policy_observations": "Fragile items inside",
    "policy_note": "Insured against theft and damage",
    "driver_full_name": "Luis Paredes",
    "driver_id": "1700000003",
    "departure_coords": "-2.1894, -79.8891",
    "ruc": "1790000001001"
  },
  "uid": "RI-0001",
  "beneficiaries": [
    {
      "email": "ana.torres@example.com",
      "group_uid": "GRP-0001",
      "name": "Ana Torres",
      "phone": "+593991234503"
    }
  ],
  "authorized_claimants": [
    {
      "email": "lucia.martinez@example.com",
      "name": "Lucia Martinez",
      "phone": "+593991234504"
    },
    {
      "email": "marco.reyes@example.com",
      "name": "Marco Reyes",
      "phone": "+593991234505"
    }
  ],
  "metadata": {
    "delivery_stops": {
      "Delivery 1": {
        "destination_invoice_id": "INV-0001",
        "final_coords": "-0.1807, -78.4678",
        "items": [
          {
            "item_name": "Laptop",
            "item_sku": "LAP1234A",
            "item_quantity": 10,
            "item_cost": 1200,
            "item_expiry": "2026-12-31"
          }
        ]
      }
    }
  },
  "payment_model": "channel_billed",
  "payment": {
    "model": "channel_billed",
    "status": "pending",
    "billing_entity": "ANDES-LOGISTICS",
    "billing_cycle": "monthly",
    "channel_sale_id": "SALE-0001",
    "sale_origin": "api"
  }
}
```

### Risk item for a personal accident insurance

In this example, we will create a risk item for personal accident coverage for an insured subject.

**/risk-items** body payload:

```json
{
  "package_uid": "PKG-BASIC",
  "policy_uid": "POL-0001",
  "start_date": "2026-03-15T00:00:00.000Z",
  "end_date": "2026-03-31T23:59:59.999Z",
  "insured_subject": {
    "group_uid": "GRP-0001",
    "subject_type": "ID",
    "identifier_value": "1700000002",
    "identifier_type": "National ID",
    "name": "Carlos",
    "last_name": "Andrade",
    "phone": "+593991234502",
    "email": "carlos.andrade@example.com",
    "gender": "male",
    "dob": "1985-08-21T00:00:00.000Z"
  },
  "uid": "RI-0002",
  "beneficiaries": [
    {
      "email": "ana.torres@example.com",
      "group_uid": "GRP-0001",
      "name": "Ana Torres",
      "phone": "+593991234503"
    }
  ],
  "authorized_claimants": [
    {
      "email": "lucia.martinez@example.com",
      "name": "Lucia Martinez",
      "phone": "+593991234504"
    },
    {
      "email": "marco.reyes@example.com",
      "name": "Marco Reyes",
      "phone": "+593991234505"
    }
  ],
  "metadata": {},
  "payment_model": "direct",
  "payment": {
    "model": "direct",
    "status": "confirmed",
    "billing_entity": "ANDES-LOGISTICS",
    "billing_cycle": "single",
    "channel_sale_id": "SALE-0002",
    "sale_origin": "web_checkout"
  }
}
```

A risk item will be returned if the endpoint call succeeds.

### Risk item event example

In this example, we will create an event. `start_date` and `end_date` are required in `event_data`; any other field, such as `coordinates`, is optional.

**/risk-items/:riskItemId/events** body payload:

```json
{
    "event_data": {
        "start_date": "2026-03-15T00:00:00.000Z",
        "end_date": "2026-06-15T00:00:00.000Z",
        "coordinates": "-2.1894, -79.8891"
    },
    "metadata": {
        "description": "Cargo left Guayaquil Terminal"
    }
}

```