> 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/claims/claims-management/claim-creation-examples.md).

# Claim Creation Examples

### Claim to a cargo risk item

In this example we will make a claim to a risk item that covered cargo damage and theft.

Important! We recommend use v2 claim integration

{% hint style="info" %}
The v2 examples send `claimant_email`. It is only taken into account in channels enabled for handshake (see [Post a Claim without User-Authorization token](https://docs.insurehero.io/shield-api/claims/claims-management#post-a-claim-without-user-authorization-token)). In any other channel, leave it out and send the user token in the `User-Authorization` header. The v1 examples do not send `claimant_email`, so they always need that header.
{% endhint %}

**/claims** body payload:

{% tabs %}
{% tab title="v1" %}

```json
{
    "risk_item_id": "cde0defc-641c-5d09-8eb8-38bec31c4931",
    "subject": "Cargo Theft Incident",
    "variant_id": "c97a1111-89f8-5fbe-bc00-544bb019e476",
    "incident": {
        "date": "2026-03-20T15:00:00.000Z",
        "details": {
            "transaction": {},
            "description": "The cargo was stolen during a scheduled delivery stop. The incident occurred while the cargo was en route to its next destination."
        },
        "additional_properties": {
            "claim_type": "THEFT",
            "incident_coords": "-0.1807, -78.4678",
            "fast_track": true
        }
    },
    "metadata": {}
}
```

{% endtab %}

{% tab title="v2" %}

```json
{
  "risk_item_uid": "RI-0001",
  "variant_uid": "VAR-GOLD",
  "claimant_email": "maria.lopez@example.com",
  "incident": {
    "date": "2026-03-20T15:00:00.000Z",
    "subject": "Cargo Theft Incident",
    "description": "The cargo was stolen during a scheduled delivery stop. The incident occurred while the cargo was en route to its next destination"
  }
}
```

{% endtab %}
{% endtabs %}

### Claim to a personal accident risk item

In this example, we will make a claim to a risk item that covered medical expenses due to an accident or accidental death.

**/claims** body payload:

{% tabs %}
{% tab title="v1" %}

```json
{
    "risk_item_id": "cde0defc-641c-5d09-8eb8-38bec31c4931",
    "subject": "Personal Accident Claim",
    "variant_id": "c97a1111-89f8-5fbe-bc00-544bb019e476",
    "incident": {
        "date": "2026-03-20T15:00:00.000Z",
        "details": {
            "transaction": {},
            "description": "While I was playing sports, a player tackled me and my right ankle twisted."
        },
        "additional_properties": {
            "incident_coords": "-0.1807, -78.4678"
        }
    },
    "metadata": {}
}
```

{% endtab %}

{% tab title="v2" %}

```json
{
  "risk_item_uid": "RI-0002",
  "variant_uid": "VAR-SILVER",
  "claimant_email": "maria.lopez@example.com",
  "incident": {
    "date": "2026-03-20T15:00:00.000Z",
    "subject": "Personal Accident Claim",
    "description": "While I was playing sports, a player tackled me and my right ankle twisted.",
    "claim_amount": 500
  }
}
```

{% endtab %}
{% endtabs %}

A claim will be returned if the endpoint call succeeds.

### Claim event example

In this example, we will create an event for a claim.

**/claims/:claimId/events** body payload:

```json
{
  "metadata": {
    
  },
  "event_data": {
    "start_date": "2026-03-15T00:00:00.000Z",
    "end_date": "2026-06-15T00:00:00.000Z",
    "amountPaid": 500,
    "eventType": "PAYMENT_RECEIVED"
  }
}
```