API Docs

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.

Endpoints
POST
/claims
GET
/claims
GET
/claims/:id
POST
/claims/:id/cancel

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

id
string
Unique identifier for the claim.
object
string
Type of object, which is 'Claim'
mode
string
Indicates whether the claim is in test or production mode.
insurance_id
string
Identifier for the associated insurance.
shipment_id
string
Identifier for the associated shipment.
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
Name of the recipient.
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.
contact_email
string
The email address EasyPost will contact if additional information is required.
Claims Object
{
  "approved_amount": null,
  "attachments": [
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/836a3784a67e429ca0d30f10f64cb0bc.png",
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/a1316f8afc5843d7b2d1370dfb7e73d3.png",
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/4d3502f6a6e64972913e43fc4191b4cd.png"
  ],
  "check_delivery_address": null,
  "contact_email": "test@example.com",
  "created_at": "2024-07-23T17:53:36",
  "description": "Test description",
  "history": [
    {
      "status": "submitted",
      "status_detail": "Claim was created.",
      "timestamp": "2024-07-23T17:53:36"
    }
  ],
  "id": "clm_097eb623597146bab94e9ef701364d4f",
  "insurance_amount": "100.00",
  "insurance_id": "ins_6aa59cf8618843c09b4707e1f3f74486",
  "mode": "test",
  "object": "Claim",
  "payment_method": "easypost_wallet",
  "recipient_name": null,
  "requested_amount": "100.00",
  "salvage_value": null,
  "shipment_id": "shp_d692021679d54c0c9da828499fb1a8de",
  "status": "submitted",
  "status_detail": "Claim was created.",
  "status_timestamp": "2024-07-23T17:53:36",
  "tracking_code": "9400100110368066361827",
  "type": "damage",
  "updated_at": "2024-07-23T17:53:36"
}

ClaimHistoryEntry Object

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).
ClaimHistoryEntry Object
{
  "approved_amount": null,
  "attachments": [
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/836a3784a67e429ca0d30f10f64cb0bc.png",
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/a1316f8afc5843d7b2d1370dfb7e73d3.png",
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/4d3502f6a6e64972913e43fc4191b4cd.png"
  ],
  "check_delivery_address": null,
  "contact_email": "test@example.com",
  "created_at": "2024-07-23T17:53:36",
  "description": "Test description",
  "history": [
    {
      "status": "submitted",
      "status_detail": "Claim was created.",
      "timestamp": "2024-07-23T17:53:36"
    }
  ],
  "id": "clm_097eb623597146bab94e9ef701364d4f",
  "insurance_amount": "100.00",
  "insurance_id": "ins_6aa59cf8618843c09b4707e1f3f74486",
  "mode": "test",
  "object": "Claim",
  "payment_method": "easypost_wallet",
  "recipient_name": null,
  "requested_amount": "100.00",
  "salvage_value": null,
  "shipment_id": "shp_d692021679d54c0c9da828499fb1a8de",
  "status": "submitted",
  "status_detail": "Claim was created.",
  "status_timestamp": "2024-07-23T17:53:36",
  "tracking_code": "9400100110368066361827",
  "type": "damage",
  "updated_at": "2024-07-23T17:53:36"
}

Create a Claim

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

Request Parameters

tracking_code
i.e. 123456789
Tracking code for the shipment.
type
i.e. damage
Type of claim being filed.
amount
i.e. 25.50
Amount being claimed for reimbursement.
email_evidence_attachments
i.e. base64 encoded string (TWFueSBoYW5kcyBtYW….)
Attachments providing evidence via email.
invoice_attachments
i.e. base64 encoded string (TWFueSBoYW5kcyBtYW….)
Attachments of invoices as evidence.
description
i.e. My package arrived damaged; the box was crushed.
Detailed description of the claim.
recipient_name
i.e. Carrie Parcel (optional)
Name of the recipient.
supporting_documentation_attachments
i.e. (required if “type” is “theft” or “damage”) i.e., base64 encoded string (TWFueSBoYW5kcyBtYW….) (optional)
Supporting documents for the claim.
contact_email
i.e. support@easypost.com
The email address EasyPost will contact if additional information is required
POST /claims
1curl -X POST https://api.easypost.com/v2/claims \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "type": "damage",
6    "email_evidence_attachments": ["REPLACE_WITH_BASE64_STRING"],
7    "invoice_attachments": ["REPLACE_WITH_BASE64_STRING"],
8    "supporting_documentation_attachments": ["REPLACE_WITH_BASE64_STRING"],
9    "description": "Test description",
10    "contact_email": "test@example.com",
11    "tracking_code": "YOUR_TRACKING_CODE",
12    "amount": "100.00"
13  }'
Response
1{
2  "approved_amount": null,
3  "attachments": [
4    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/836a3784a67e429ca0d30f10f64cb0bc.png",
5    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/a1316f8afc5843d7b2d1370dfb7e73d3.png",
6    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/4d3502f6a6e64972913e43fc4191b4cd.png"
7  ],
8  "check_delivery_address": null,
9  "contact_email": "test@example.com",
10  "created_at": "2024-07-23T17:53:36",
11  "description": "Test description",
12  "history": [
13    {
14      "status": "submitted",
15      "status_detail": "Claim was created.",
16      "timestamp": "2024-07-23T17:53:36"
17    }
18  ],
19  "id": "clm_097eb623597146bab94e9ef701364d4f",
20  "insurance_amount": "100.00",
21  "insurance_id": "ins_6aa59cf8618843c09b4707e1f3f74486",
22  "mode": "test",
23  "object": "Claim",
24  "payment_method": "easypost_wallet",
25  "recipient_name": null,
26  "requested_amount": "100.00",
27  "salvage_value": null,
28  "shipment_id": "shp_d692021679d54c0c9da828499fb1a8de",
29  "status": "submitted",
30  "status_detail": "Claim was created.",
31  "status_timestamp": "2024-07-23T17:53:36",
32  "tracking_code": "9400100110368066361827",
33  "type": "damage",
34  "updated_at": "2024-07-23T17:53:36"
35}

Retrieve all Claims

Retrieve a list of claims.

Request Parameters

type
string
status
string
before_id
i.e. ins_...
Optional pagination parameter. Only records created before the given ID will be included. May not be used with after_id.
after_id
i.e. ins_...
Optional pagination parameter. Only records created after the given ID will be included. May not be used with before_id.
start_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created after this timestamp. Defaults to 1 month ago, or 1 month before a passed end_datetime.
end_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created before this timestamp. Defaults to end of the current day, or 1 month after a passed start_datetime.
page_size
i.e. 30
The number of records to return on each page. The maximum value is 100, and default is 20.
GET /claims
1curl -X GET "https://api.easypost.com/v2/claims?page_size=5" \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "claims": [
3    {
4      "approved_amount": null,
5      "attachments": [
6        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/7b9b0171ae7b4e258f765822e7cddb71.png",
7        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/2cd9fdd33a7d40fc84ac8f87c3da1f86.png",
8        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/d3aebbc42e884769ad810c92c26ad8ad.png"
9      ],
10      "check_delivery_address": null,
11      "contact_email": "test@example.com",
12      "created_at": "2024-07-23T17:53:40",
13      "description": "Test description",
14      "history": [
15        {
16          "status": "submitted",
17          "status_detail": "Claim was created.",
18          "timestamp": "2024-07-23T17:53:40"
19        }
20      ],
21      "id": "clm_097e86d630e44e83b736c48c1271fed3",
22      "insurance_amount": "100.00",
23      "insurance_id": "ins_33a9255ab9f443c18a1c1876bc6e25a4",
24      "mode": "test",
25      "object": "Claim",
26      "payment_method": "easypost_wallet",
27      "recipient_name": null,
28      "requested_amount": "100.00",
29      "salvage_value": null,
30      "shipment_id": "shp_8ae4d3d1cf78409fbabd93c5b13c5f98",
31      "status": "submitted",
32      "status_detail": "Claim was created.",
33      "status_timestamp": "2024-07-23T17:53:40",
34      "tracking_code": "9400100110368066361841",
35      "type": "damage",
36      "updated_at": "2024-07-23T17:53:40"
37    },
38    {
39      "approved_amount": null,
40      "attachments": [
41        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/836a3784a67e429ca0d30f10f64cb0bc.png",
42        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/a1316f8afc5843d7b2d1370dfb7e73d3.png",
43        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/4d3502f6a6e64972913e43fc4191b4cd.png"
44      ],
45      "check_delivery_address": null,
46      "contact_email": "test@example.com",
47      "created_at": "2024-07-23T17:53:36",
48      "description": "Test description",
49      "history": [
50        {
51          "status": "submitted",
52          "status_detail": "Claim was created.",
53          "timestamp": "2024-07-23T17:53:36"
54        }
55      ],
56      "id": "clm_097eb623597146bab94e9ef701364d4f",
57      "insurance_amount": "100.00",
58      "insurance_id": "ins_6aa59cf8618843c09b4707e1f3f74486",
59      "mode": "test",
60      "object": "Claim",
61      "payment_method": "easypost_wallet",
62      "recipient_name": null,
63      "requested_amount": "100.00",
64      "salvage_value": null,
65      "shipment_id": "shp_d692021679d54c0c9da828499fb1a8de",
66      "status": "submitted",
67      "status_detail": "Claim was created.",
68      "status_timestamp": "2024-07-23T17:53:36",
69      "tracking_code": "9400100110368066361827",
70      "type": "damage",
71      "updated_at": "2024-07-23T17:53:36"
72    },
73    {
74      "approved_amount": null,
75      "attachments": [
76        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/7280de6a4ce249e6af34cfd8fc2c8613.png",
77        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/9faca9b590ed4616aaa385e717969828.png",
78        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/5c641ae1e5a54a53ab6ded433ebfabdc.png"
79      ],
80      "check_delivery_address": null,
81      "contact_email": "test@example.com",
82      "created_at": "2024-07-23T17:10:33",
83      "description": "Test description",
84      "history": [
85        {
86          "status": "cancelled",
87          "status_detail": "Claim cancellation was requested.",
88          "timestamp": "2024-07-23T17:12:03"
89        },
90        {
91          "status": "submitted",
92          "status_detail": "Claim was created.",
93          "timestamp": "2024-07-23T17:10:33"
94        }
95      ],
96      "id": "clm_097e39b748d24c32a0bd61840fc0763f",
97      "insurance_amount": "249.99",
98      "insurance_id": "ins_d15880e5772c4373aec497744fa4da54",
99      "mode": "test",
100      "object": "Claim",
101      "payment_method": "easypost_wallet",
102      "recipient_name": null,
103      "requested_amount": "100.00",
104      "salvage_value": null,
105      "shipment_id": "shp_09a808dae97442f3aa7fbd994a3533d4",
106      "status": "cancelled",
107      "status_detail": "Claim cancellation was requested.",
108      "status_timestamp": "2024-07-23T17:12:03",
109      "tracking_code": "9470100110368066351889",
110      "type": "damage",
111      "updated_at": "2024-07-23T17:12:03"
112    },
113    {
114      "approved_amount": null,
115      "attachments": [
116        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240722/1d0c4ff3d71c4f5d8ec5c21bcfeaf419.png",
117        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240722/8f78018b1c6941cdafd1ca9d36579e40.png",
118        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240722/973d2a48b6b04423b1d112dff79e85e3.png"
119      ],
120      "check_delivery_address": null,
121      "contact_email": "test@example.com",
122      "created_at": "2024-07-22T20:47:51",
123      "description": "Test description",
124      "history": [
125        {
126          "status": "submitted",
127          "status_detail": "Claim was created.",
128          "timestamp": "2024-07-22T20:47:51"
129        }
130      ],
131      "id": "clm_097ed32c795141499bb0a5e17a4fe24f",
132      "insurance_amount": "249.99",
133      "insurance_id": "ins_fa5c89fcf765494b921a96c4e4004476",
134      "mode": "test",
135      "object": "Claim",
136      "payment_method": "easypost_wallet",
137      "recipient_name": null,
138      "requested_amount": "100.00",
139      "salvage_value": null,
140      "shipment_id": "shp_5bcff1867a1f4a29a67db9a84a2082c5",
141      "status": "submitted",
142      "status_detail": "Claim was created.",
143      "status_timestamp": "2024-07-22T20:47:51",
144      "tracking_code": "9434600110368065978707",
145      "type": "damage",
146      "updated_at": "2024-07-22T20:47:51"
147    },
148    {
149      "approved_amount": null,
150      "attachments": [
151        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240722/1d0c4ff3d71c4f5d8ec5c21bcfeaf419.png",
152        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240722/8f78018b1c6941cdafd1ca9d36579e40.png",
153        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240722/973d2a48b6b04423b1d112dff79e85e3.png"
154      ],
155      "check_delivery_address": null,
156      "contact_email": "test@example.com",
157      "created_at": "2024-07-22T20:47:51",
158      "description": "Test description",
159      "history": [
160        {
161          "status": "submitted",
162          "status_detail": "Claim was created.",
163          "timestamp": "2024-07-22T20:47:51"
164        }
165      ],
166      "id": "clm_097ed32c795141499bb0a5e17a4fe24f",
167      "insurance_amount": "249.99",
168      "insurance_id": "ins_fa5c89fcf765494b921a96c4e4004476",
169      "mode": "test",
170      "object": "Claim",
171      "payment_method": "easypost_wallet",
172      "recipient_name": null,
173      "requested_amount": "100.00",
174      "salvage_value": null,
175      "shipment_id": "shp_5bcff1867a1f4a29a67db9a84a2082c5",
176      "status": "submitted",
177      "status_detail": "Claim was created.",
178      "status_timestamp": "2024-07-22T20:47:51",
179      "tracking_code": "9434600110368065978707",
180      "type": "damage",
181      "updated_at": "2024-07-22T20:47:51"
182    }
183  ],
184  "has_more": true
185}

Retrieve a Claim

Retrieve details of a specific claim using the id.

GET /claims/:id
1curl -X GET https://api.easypost.com/v2/claims/clm_... \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "approved_amount": null,
3  "attachments": [
4    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/7b9b0171ae7b4e258f765822e7cddb71.png",
5    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/2cd9fdd33a7d40fc84ac8f87c3da1f86.png",
6    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/d3aebbc42e884769ad810c92c26ad8ad.png"
7  ],
8  "check_delivery_address": null,
9  "contact_email": "test@example.com",
10  "created_at": "2024-07-23T17:53:40",
11  "description": "Test description",
12  "history": [
13    {
14      "status": "submitted",
15      "status_detail": "Claim was created.",
16      "timestamp": "2024-07-23T17:53:40"
17    }
18  ],
19  "id": "clm_097e86d630e44e83b736c48c1271fed3",
20  "insurance_amount": "100.00",
21  "insurance_id": "ins_33a9255ab9f443c18a1c1876bc6e25a4",
22  "mode": "test",
23  "object": "Claim",
24  "payment_method": "easypost_wallet",
25  "recipient_name": null,
26  "requested_amount": "100.00",
27  "salvage_value": null,
28  "shipment_id": "shp_8ae4d3d1cf78409fbabd93c5b13c5f98",
29  "status": "submitted",
30  "status_detail": "Claim was created.",
31  "status_timestamp": "2024-07-23T17:53:40",
32  "tracking_code": "9400100110368066361841",
33  "type": "damage",
34  "updated_at": "2024-07-23T17:53:40"
35}

Cancel a Claim

Cancel an existing claim using the id

POST /claims/:id/cancel
1curl -X POST https://api.easypost.com/v2/claims/clm_.../cancel \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "approved_amount": null,
3  "attachments": [
4    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/533eff379afa47759cdc14f19e190fc7.png",
5    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/4715d1ddc5e448ad924c029d8407b9e4.png",
6    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20240723/987f3e1a094044219e640163b1074ff7.png"
7  ],
8  "check_delivery_address": null,
9  "contact_email": "test@example.com",
10  "created_at": "2024-07-23T17:53:44",
11  "description": "Test description",
12  "history": [
13    {
14      "status": "cancelled",
15      "status_detail": "Claim cancellation was requested.",
16      "timestamp": "2024-07-23T17:53:45"
17    },
18    {
19      "status": "submitted",
20      "status_detail": "Claim was created.",
21      "timestamp": "2024-07-23T17:53:44"
22    }
23  ],
24  "id": "clm_097eda66d06e42ec84449bbd34671a7d",
25  "insurance_amount": "100.00",
26  "insurance_id": "ins_8d75d3dcf398461aaa330e48dbd4c19e",
27  "mode": "test",
28  "object": "Claim",
29  "payment_method": "easypost_wallet",
30  "recipient_name": null,
31  "requested_amount": "100.00",
32  "salvage_value": null,
33  "shipment_id": "shp_82fecc386f314823ad6b1a35365b7f4e",
34  "status": "cancelled",
35  "status_detail": "Claim cancellation was requested.",
36  "status_timestamp": "2024-07-23T17:53:45",
37  "tracking_code": "9400100110368066361872",
38  "type": "damage",
39  "updated_at": "2024-07-23T17:53:45"
40}