# Claims

The `Claims API` allows shippers to automate submitting and managing insurance claims for lost, damaged, or stolen packages. This endpoint streamlines claim submissions and provides an automated experience. Claims can be submitted via the EasyPost Dashboard, a Claim Submission Form, or the Claims API.

---

## Functionality

The Claims endpoint offers the following functionalities:

- **Claims Creation**: Accepts necessary information to create a claim.
- **Claims Validation**: Ensures claims meet specific criteria before processing.
- **Claims Storage**: Stores claim details and attachments.
- **Claims Responses**: Provides automated responses for successful and unsuccessful claims.

---

## Claims process

1. **Claim Submission**: The claim is submitted via the EasyPost Dashboard, a Claim Submission Form, or Claims API endpoint.
2. **Claim Validation**: The system validates the claim to ensure it meets the necessary criteria (e.g., valid tracking code, proper claim type, sufficient evidence for the type of claim).
3. **Claim Storage**: Once validated, the claim details and attachments are stored.
4. **Claim Review**: The claim undergoes a review process, which may involve manual review by the support team to verify the claim’s validity and completeness.
5. **Claim Updates**: The status of the claim is updated based on the outcome of the review. Possible statuses include:
   1. submitted
   2. in_review
   3. approved
   4. approved_partial
   5. rejected
   6. cancelled
   7. needs_action
6. **Automated Response**: An automated response is sent to the user with the current status of the claim.
7. **Notifications**: Users are notified of changes to their Claim via Webhook Events.
8. **Claim Resolution**: Approved claims are processed for reimbursement, while rejected claims are communicated to the user with reasons for rejection.

---

## Claim object

| Property | Type | Description |
|----------|------|-------------|
| id | string | Unique identifier for the claim. |
| object | string | Type of object, which is 'Claim' |
| insurance_id | string | Identifier for the associated insurance. |
| shipment_id | string | Identifier for the associated shipment. |
| reference | string | The reference for this Claim, if any |
| tracking_code | string | Tracking code for the shipment. |
| status | enum | submitted in_review approved rejected approved_partial cancelled needs_action |
| status_detail | string | Reason for the current status. |
| status_timestamp | datetime | Timestamp for when the status changed (could differ from the updated_at field, which is specific to the Claim object). |
| type | enum | Type of claim being filed: loss, theft, damage |
| history | ClaimHistoryEntry array | History of status changes for the Claim. |
| insurance_amount | string | Amount of insurance coverage. |
| requested_amount | string | Amount requested for the claim. |
| approved_amount | string | Amount approved for reimbursement. |
| salvage_value | string | Salvage value of the damaged item. |
| description | string | Detailed description of of the claim. |
| attachments | array | A list of links to supporting evidence attachments. |
| recipient_name | string | The name of the entity to be paid from EasyPost for this Insurance Claim. |
| contact_email | string | The email of the entity to be paid from EasyPost for this Insurance Claim. |
| payment_method | enum | Method of payment for the claim reimbursement: mailed_check easypost_wallet |
| check_delivery_address | string | Address where the check should be mailed, if applicable. |
| created_at | datetime | Timestamp for when the claim was created. |
| updated_at | datetime | Timestamp for the last update to the claim. |

Example Object:

```json
{
  "approved_amount": null,
  "attachments": [
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/a915d0e238074fff9729afa1bfb87a0e.png",
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/3020f31a57374dc3ace477f7a4ec860d.png",
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/88aada9e505f4e77bd6060710d78e497.png"
  ],
  "check_delivery_address": null,
  "contact_email": "test@example.com",
  "created_at": "2025-05-12T19:08:04Z",
  "description": "Test description",
  "history": [
    {
      "status": "submitted",
      "status_detail": "Claim was created.",
      "timestamp": "2025-05-12T19:08:04Z"
    }
  ],
  "id": "clm_09d89e88a0c943d59018bc26b041c41c",
  "insurance_amount": "100.00",
  "insurance_id": "ins_da31156b6335407da23ee06fa2fe8a28",
  "mode": "test",
  "object": "Claim",
  "payment_method": "easypost_wallet",
  "recipient_name": null,
  "requested_amount": "100.00",
  "salvage_value": null,
  "shipment_id": "shp_531f76e4a4de491183f5cabb738cb828",
  "status": "submitted",
  "status_detail": "Claim was created.",
  "status_timestamp": "2025-05-12T19:08:04Z",
  "tracking_code": "9405500208303109888319",
  "type": "damage",
  "updated_at": "2025-05-12T19:08:04Z"
}
```

---

## ClaimHistoryEntry Object

| Property | Type | Description |
|----------|------|-------------|
| status | enum | submitted, in_review, approved, rejected, approved_partial, cancelled, needs_action |
| status_detail | string | Reason for the current status. |
| status_timestamp | datetime | Timestamp for when the status changed (could differ from the updated_at field, which is specific to the Claim object). |

Example Object:

```json
{
  "approved_amount": null,
  "attachments": [
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/a915d0e238074fff9729afa1bfb87a0e.png",
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/3020f31a57374dc3ace477f7a4ec860d.png",
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/88aada9e505f4e77bd6060710d78e497.png"
  ],
  "check_delivery_address": null,
  "contact_email": "test@example.com",
  "created_at": "2025-05-12T19:08:04Z",
  "description": "Test description",
  "history": [
    {
      "status": "submitted",
      "status_detail": "Claim was created.",
      "timestamp": "2025-05-12T19:08:04Z"
    }
  ],
  "id": "clm_09d89e88a0c943d59018bc26b041c41c",
  "insurance_amount": "100.00",
  "insurance_id": "ins_da31156b6335407da23ee06fa2fe8a28",
  "mode": "test",
  "object": "Claim",
  "payment_method": "easypost_wallet",
  "recipient_name": null,
  "requested_amount": "100.00",
  "salvage_value": null,
  "shipment_id": "shp_531f76e4a4de491183f5cabb738cb828",
  "status": "submitted",
  "status_detail": "Claim was created.",
  "status_timestamp": "2025-05-12T19:08:04Z",
  "tracking_code": "9405500208303109888319",
  "type": "damage",
  "updated_at": "2025-05-12T19:08:04Z"
}
```

---

## Create a Claim

### Example: POST /claims

#### cURL

```shell
curl -X POST https://api.easypost.com/v2/claims \
  -u "EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "damage",
    "email_evidence_attachments": ["REPLACE_WITH_BASE64_STRING"],
    "invoice_attachments": ["REPLACE_WITH_BASE64_STRING"],
    "supporting_documentation_attachments": ["REPLACE_WITH_BASE64_STRING"],
    "description": "Test description",
    "contact_email": "test@example.com",
    "tracking_code": "YOUR_TRACKING_CODE",
    "amount": "100.00"
  }'
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func create() {
	client := easypost.New("EASYPOST_API_KEY")

	claim, _ := client.CreateClaim(
		&easypost.CreateClaimParameters{
			Amount:                             100.00,
			TrackingCode:                       "EZ1000000001",
			EmailEvidenceAttachments:           []string{"REPLACE_WITH_BASE64_STRING"},
			InvoiceAttachments:                 []string{"REPLACE_WITH_BASE64_STRING"},
			SupportingDocumentationAttachments: []string{"REPLACE_WITH_BASE64_STRING"},
			Description:                        "Test Description",
			ContactEmail:                       "test@example.com",
		},
	)

	fmt.Println(claim)
}
```

#### Java

```java
package claims;

import com.easypost.exception.EasyPostException;
import com.easypost.model.Claim;
import com.easypost.service.EasyPostClient;

import java.util.HashMap;

public class Create {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        HashMap<String, Object> params = new HashMap<String, Object>();
        params.put("type", "damage");
        params.put("email_evidence_attachments",
            new String[]{"REPLACE_WITH_BASE64_STRING"});
        params.put("invoice_attachments",
            new String[]{"REPLACE_WITH_BASE64_STRING"});
        params.put("supporting_documentation_attachments",
            new String[]{"REPLACE_WITH_BASE64_STRING"});
        params.put("description", "Test Description");
        params.put("contact_email", "test@example.com");
        params.put("tracking_code", "YOUR_TRACKING_CODE");
        params.put("amount", "100");

        Claim claim = client.claim.create(params);

        System.out.println(claim);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Parameters.Claim.Create parameters = new()
            {
                Amount = 100.00,
                Type = ClaimType.Damage,
                EmailEvidenceAttachments = new string[]
                {
                    "REPLACE_WITH_BASE64_STRING"
                },
                InvoiceAttachments = new string[]
                {
                    "REPLACE_WITH_BASE64_STRING"
                },
                SupportingDocumentationAttachments = new string[]
                {
                    "REPLACE_WITH_BASE64_STRING"
                },
                Description = "Test description",
                ContactEmail = "test@example.com",
                TrackingCode = "YOUR_TRACKING_CODE",
            };

            EasyPost.Models.API.Claim claim = await client.Claim.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(claim, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const claim = await client.Claim.create({
    type: 'damage',
    email_evidence_attachments: ['REPLACE_WITH_BASE64_STRING'],
    invoice_attachments: ['REPLACE_WITH_BASE64_STRING'],
    supporting_documentation_attachments: ['REPLACE_WITH_BASE64_STRING'],
    description: 'Test Description',
    contact_email: 'test@example.com',
    tracking_code: 'YOUR_TRACKING_CODE',
    amount: '100',
  });

  console.log(claim);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$claim = $client->claim->create([
    'type' => 'damage',
    'email_evidence_attachments' =>
        ['REPLACE_WITH_BASE64_STRING'],
    'invoice_attachments' =>
        ['REPLACE_WITH_BASE64_STRING'],
    'supporting_documentation_attachments' =>
        ['REPLACE_WITH_BASE64_STRING'],
    'description' => 'Test Description',
    'contact_email' => 'test@example.com',
    'tracking_code' => 'YOUR_TRACKING_CODE',
    'amount' => '100',
]);

echo $claim;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

claim = client.claim.create(
    type="damage",
    email_evidence_attachments=["REPLACE_WITH_BASE64_STRING"],
    invoice_attachments=["REPLACE_WITH_BASE64_STRING"],
    supporting_documentation_attachments=["REPLACE_WITH_BASE64_STRING"],
    description="Test Description",
    contact_email="test@example.com",
    tracking_code="YOUR_TRACKING_CODE",
    amount="100",
)

print(claim)
```

Create a new claim for a shipment. This endpoint accepts the necessary information to create and validate a claim and store the details.

---

## Retrieve all Claims

### Example: GET /claims

#### cURL

```shell
curl -X GET "https://api.easypost.com/v2/claims?page_size=5" \
  -u "EASYPOST_API_KEY":
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func list() {
	client := easypost.New("EASYPOST_API_KEY")

	claims, _ := client.ListClaims(
		&easypost.ListClaimsParameters{
			PageSize: 5,
		},
	)

	fmt.Println(claims)
}
```

#### Java

```java
package claims;

import com.easypost.exception.EasyPostException;
import com.easypost.model.ClaimCollection;
import com.easypost.service.EasyPostClient;

import java.util.HashMap;

public class All {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        HashMap<String, Object> params = new HashMap<>();
        params.put("page_size", 5);

        ClaimCollection claims = client.claim.all(params);

        System.out.println(claims);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Parameters.Claim.All parameters = new()
            {
                PageSize = 5
            };

            EasyPost.Models.API.ClaimCollection claimCollection = await client.Claim.All(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(claimCollection, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const claims = await client.Claim.all({
    page_size: 5,
  });

  console.log(claims);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$claims = $client->claim->all([
    'page_size' => 5,
]);

echo $claims;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

claims = client.claim.all(page_size=5)

print(claims)
```

Retrieve a list of claims.

---

## Retrieve a Claim

### Example: GET /claims/:id

#### cURL

```shell
curl -X GET https://api.easypost.com/v2/claims/clm_... \
  -u "EASYPOST_API_KEY":
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func retrieve() {
	client := easypost.New("EASYPOST_API_KEY")

	claim, _ := client.GetClaim("clm_...")

	fmt.Println(claim)
}
```

#### Java

```java
package claims;

import com.easypost.exception.EasyPostException;
import com.easypost.model.Claim;
import com.easypost.service.EasyPostClient;

public class Retrieve {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        Claim claim = client.claim.retrieve("clm_...");

        System.out.println(claim);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Models.API.Claim claim = await client.Claim.Retrieve("ins_...");

            Console.WriteLine(JsonConvert.SerializeObject(claim, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const claim = await client.Claim.retrieve('clm_...');

  console.log(claim);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$claim = $client->claim->retrieve('clm_...');

echo $claim;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

claim = client.claim.retrieve("clm_...")

print(claim)
```

Retrieve details of a specific claim using the `id`.

---

## Cancel a Claim

### Example: POST /claims/:id/cancel

#### cURL

```shell
curl -X POST https://api.easypost.com/v2/claims \
  -u "EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "damage",
    "email_evidence_attachments": ["REPLACE_WITH_BASE64_STRING"],
    "invoice_attachments": ["REPLACE_WITH_BASE64_STRING"],
    "supporting_documentation_attachments": ["REPLACE_WITH_BASE64_STRING"],
    "description": "Test description",
    "contact_email": "test@example.com",
    "tracking_code": "YOUR_TRACKING_CODE",
    "amount": "100.00"
  }'
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func create() {
	client := easypost.New("EASYPOST_API_KEY")

	claim, _ := client.CreateClaim(
		&easypost.CreateClaimParameters{
			Amount:                             100.00,
			TrackingCode:                       "EZ1000000001",
			EmailEvidenceAttachments:           []string{"REPLACE_WITH_BASE64_STRING"},
			InvoiceAttachments:                 []string{"REPLACE_WITH_BASE64_STRING"},
			SupportingDocumentationAttachments: []string{"REPLACE_WITH_BASE64_STRING"},
			Description:                        "Test Description",
			ContactEmail:                       "test@example.com",
		},
	)

	fmt.Println(claim)
}
```

#### Java

```java
package claims;

import com.easypost.exception.EasyPostException;
import com.easypost.model.Claim;
import com.easypost.service.EasyPostClient;

import java.util.HashMap;

public class Create {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        HashMap<String, Object> params = new HashMap<String, Object>();
        params.put("type", "damage");
        params.put("email_evidence_attachments",
            new String[]{"REPLACE_WITH_BASE64_STRING"});
        params.put("invoice_attachments",
            new String[]{"REPLACE_WITH_BASE64_STRING"});
        params.put("supporting_documentation_attachments",
            new String[]{"REPLACE_WITH_BASE64_STRING"});
        params.put("description", "Test Description");
        params.put("contact_email", "test@example.com");
        params.put("tracking_code", "YOUR_TRACKING_CODE");
        params.put("amount", "100");

        Claim claim = client.claim.create(params);

        System.out.println(claim);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Parameters.Claim.Create parameters = new()
            {
                Amount = 100.00,
                Type = ClaimType.Damage,
                EmailEvidenceAttachments = new string[]
                {
                    "REPLACE_WITH_BASE64_STRING"
                },
                InvoiceAttachments = new string[]
                {
                    "REPLACE_WITH_BASE64_STRING"
                },
                SupportingDocumentationAttachments = new string[]
                {
                    "REPLACE_WITH_BASE64_STRING"
                },
                Description = "Test description",
                ContactEmail = "test@example.com",
                TrackingCode = "YOUR_TRACKING_CODE",
            };

            EasyPost.Models.API.Claim claim = await client.Claim.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(claim, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const claim = await client.Claim.create({
    type: 'damage',
    email_evidence_attachments: ['REPLACE_WITH_BASE64_STRING'],
    invoice_attachments: ['REPLACE_WITH_BASE64_STRING'],
    supporting_documentation_attachments: ['REPLACE_WITH_BASE64_STRING'],
    description: 'Test Description',
    contact_email: 'test@example.com',
    tracking_code: 'YOUR_TRACKING_CODE',
    amount: '100',
  });

  console.log(claim);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$claim = $client->claim->create([
    'type' => 'damage',
    'email_evidence_attachments' =>
        ['REPLACE_WITH_BASE64_STRING'],
    'invoice_attachments' =>
        ['REPLACE_WITH_BASE64_STRING'],
    'supporting_documentation_attachments' =>
        ['REPLACE_WITH_BASE64_STRING'],
    'description' => 'Test Description',
    'contact_email' => 'test@example.com',
    'tracking_code' => 'YOUR_TRACKING_CODE',
    'amount' => '100',
]);

echo $claim;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

claim = client.claim.create(
    type="damage",
    email_evidence_attachments=["REPLACE_WITH_BASE64_STRING"],
    invoice_attachments=["REPLACE_WITH_BASE64_STRING"],
    supporting_documentation_attachments=["REPLACE_WITH_BASE64_STRING"],
    description="Test Description",
    contact_email="test@example.com",
    tracking_code="YOUR_TRACKING_CODE",
    amount="100",
)

print(claim)
```

Cancel an existing claim using the `id`