LateShipment.com API Documentation - Shipping Insurance

Modified on: Fri, 18 Jul, 2025 at 4:19 AM

LateShipment.com API Documentation: Shipping Insurance

Welcome to the LateShipment.com API documentation. This guide will help you integrate our Shipping Insurance services directly into your systems.

Authentication

Authentication is handled via request headers. You will need your account's Admin Email ID and an API Key (x-auth-key).

You can find and generate your API key in your LateShipment.com account under Settings > My Profile > API Credentials.

Headers:

Header	Description
`x-user-email`	Your account's administrator email address.
`x-auth-key`	Your unique API key.
`Content-Type`	`application/json`

Example Authentication Header:

x-user-email: admin@yourcompany.com
x-auth-key: sk_live_a1b2c3d4e5f6g7h8
Content-Type: application/json

API Endpoints

The base URL for all API endpoints is: https://api.lateshipment.com

Policies

- POST /v1/insurance/policies

Buy (issue) a new shipping insurance policy for a single shipment.

Request Body:

{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "insured_value": 150.75,
  "currency": "USD",
  "order_id": "ORD-2024-00123",
  "parcel": {
    "length": 10,
    "width": 8,
    "height": 6,
    "unit": "in"
  },
  "shipper": {
    "name": "John Doe",
    "company": "ACME Corp",
    "address_line1": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "90210",
    "country": "US"
  },
  "recipient": {
    "name": "Jane Smith",
    "address_line1": "456 Oak Ave",
    "city": "Someplace",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  }
}

Example Call (cURL):

curl -X POST https://api.lateshipment.com/v1/insurance/policies \
-H "Content-Type: application/json" \
-H "x-user-email: admin@yourcompany.com" \
-H "x-auth-key: sk_live_a1b2c3d4e5f6g7h8" \
-d '{...payload...}'

Success Response (201 Created):

{
  "status": "success",
  "data": {
    "policy_id": "pol_1a2b3c4d5e6f7g8h",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS",
    "insured_value": 150.75,
    "premium_charged": 1.25,
    "currency": "USD",
    "status": "active",
    "created_at": "2024-07-18T10:00:00Z"
  }
}

Failure Response (400 Bad Request):

{
  "status": "error",
  "message": "Validation failed.",
  "errors": {
    "tracking_number": "The tracking number field is required."
  }
}

- GET /v1/insurance/policies/{policy_id}

Get the details and status of a specific insurance policy.

Example Call (cURL):

curl -X GET https://api.lateshipment.com/v1/insurance/policies/pol_1a2b3c4d5e6f7g8h \
-H "x-user-email: admin@yourcompany.com" \
-H "x-auth-key: sk_live_a1b2c3d4e5f6g7h8"

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "policy_id": "pol_1a2b3c4d5e6f7g8h",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS",
    "insured_value": 150.75,
    "premium_charged": 1.25,
    "currency": "USD",
    "status": "active",
    "order_id": "ORD-2024-00123",
    "created_at": "2024-07-18T10:00:00Z",
    "updated_at": "2024-07-18T10:00:00Z"
  }
}

Failure Response (404 Not Found):

{
  "status": "error",
  "message": "Policy with ID pol_invalid123 not found."
}

- GET /v1/insurance/policies

List and search all your insurance policies. Supports pagination and filtering.

Query Parameters:

limit (integer, default: 20): Number of results per page.
offset (integer, default: 0): Number of results to skip for pagination.
tracking_number (string): Filter by tracking number.
status (string): Filter by status (active, cancelled, expired).

Example Call (cURL):

curl -X GET "https://api.lateshipment.com/v1/insurance/policies?limit=10&status=active" \
-H "x-user-email: admin@yourcompany.com" \
-H "x-auth-key: sk_live_a1b2c3d4e5f6g7h8"

Success Response (200 OK):

{
  "status": "success",
  "pagination": {
    "total": 150,
    "limit": 10,
    "offset": 0
  },
  "data": [
    {
      "policy_id": "pol_1a2b3c4d5e6f7g8h",
      "tracking_number": "1Z999AA10123456784",
      "status": "active",
      "insured_value": 150.75,
      "created_at": "2024-07-18T10:00:00Z"
    }
    // ... more policies
  ]
}

- POST /v1/insurance/policies/{policy_id}/cancel

Cancel or void an active insurance policy. This is typically only possible before the package has been shipped.

Example Call (cURL):

curl -X POST https://api.lateshipment.com/v1/insurance/policies/pol_1a2b3c4d5e6f7g8h/cancel \
-H "x-user-email: admin@yourcompany.com" \
-H "x-auth-key: sk_live_a1b2c3d4e5f6g7h8"

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "policy_id": "pol_1a2b3c4d5e6f7g8h",
    "status": "cancelled",
    "message": "Policy has been successfully cancelled. The premium will be refunded."
  }
}

Failure Response (400 Bad Request):

{
  "status": "error",
  "message": "This policy cannot be cancelled as the shipment is already in transit."
}

- POST /v1/insurance/policies/bulk

Issue multiple insurance policies in a single API call.

Request Body:

{
  "policies": [
    {
      "tracking_number": "1Z999AA10123456784",
      "carrier": "UPS",
      "insured_value": 150.75
    },
    {
      "tracking_number": "9405511899560000000000",
      "carrier": "USPS",
      "insured_value": 50.00
    }
  ]
}

Success Response (202 Accepted): The request is processed asynchronously. The response will indicate the job has been queued.

{
  "status": "success",
  "data": {
    "job_id": "bulk_job_xyz789",
    "status": "queued",
    "message": "Bulk policy issuance job has been accepted and is being processed."
  }
}

Failure Response (400 Bad Request):

{
    "status": "error",
    "message": "Request body must be an array of policy objects under the 'policies' key."
}

Claims

- POST /v1/insurance/claims

Initiate a new insurance claim for a lost, stolen, or damaged shipment.

Request Body:

{
  "policy_id": "pol_1a2b3c4d5e6f7g8h",
  "claim_type": "damage",
  "claim_amount": 150.75,
  "reason": "Package arrived crushed and contents were broken.",
  "contact_email": "claims@yourcompany.com",
  "attachments": [
    {
      "file_name": "photo_of_damage.jpg",
      "file_data": "base64_encoded_string_of_image"
    }
  ]
}

Success Response (201 Created):

{
  "status": "success",
  "data": {
    "claim_id": "clm_z1y2x3w4v5u6t7s8",
    "policy_id": "pol_1a2b3c4d5e6f7g8h",
    "status": "submitted",
    "message": "Your claim has been submitted successfully and is now under review.",
    "created_at": "2024-07-25T14:30:00Z"
  }
}

Failure Response (404 Not Found):

{
  "status": "error",
  "message": "Policy with ID pol_1a2b3c4d5e6f7g8h not found or is not active."
}

-GET /v1/insurance/claims/{claim_id}

Get the status and details of a specific insurance claim.

Example Call (cURL):

curl -X GET https://api.lateshipment.com/v1/insurance/claims/clm_z1y2x3w4v5u6t7s8 \
-H "x-user-email: admin@yourcompany.com" \
-H "x-auth-key: sk_live_a1b2c3d4e5f6g7h8"

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "claim_id": "clm_z1y2x3w4v5u6t7s8",
    "policy_id": "pol_1a2b3c4d5e6f7g8h",
    "status": "under_review",
    "claim_type": "damage",
    "claim_amount": 150.75,
    "reason": "Package arrived crushed and contents were broken.",
    "timeline": [
      { "status": "submitted", "timestamp": "2024-07-25T14:30:00Z" },
      { "status": "under_review", "timestamp": "2024-07-26T09:00:00Z" }
    ],
    "created_at": "2024-07-25T14:30:00Z"
  }
}

- PATCH /v1/insurance/claims/{claim_id}

Update a claim with additional notes or attachments.

Request Body:

{
  "notes": "Adding a note from the customer: The box was left in the rain.",
  "attachments": [
    {
      "file_name": "customer_email.pdf",
      "file_data": "base64_encoded_string_of_pdf"
    }
  ]
}

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "claim_id": "clm_z1y2x3w4v5u6t7s8",
    "status": "under_review",
    "message": "Claim has been updated successfully.",
    "updated_at": "2024-07-27T11:00:00Z"
  }
}

Failure Response (400 Bad Request):

{
  "status": "error",
  "message": "Claim cannot be updated as it has already been closed."
}

- GET /v1/insurance/claims

List and search all your insurance claims.

Query Parameters:

limit (integer, default: 20)
offset (integer, default: 0)
status (string): Filter by status (submitted, under_review, approved, rejected).
policy_id (string): Filter by policy ID.

Success Response (200 OK):

{
  "status": "success",
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  },
  "data": [
    {
      "claim_id": "clm_z1y2x3w4v5u6t7s8",
      "policy_id": "pol_1a2b3c4d5e6f7g8h",
      "status": "under_review",
      "claim_amount": 150.75,
      "created_at": "2024-07-25T14:30:00Z"
    }
    // ... more claims
  ]
}

- POST /v1/insurance/claims/bulk

Initiate multiple insurance claims in a single API call.

Request Body:

{
  "claims": [
    {
      "policy_id": "pol_1a2b3c4d5e6f7g8h",
      "claim_type": "loss",
      "claim_amount": 150.75
    },
    {
      "policy_id": "pol_p0o9i8u7y6t5r4e3",
      "claim_type": "damage",
      "claim_amount": 75.00,
      "reason": "Item broken in transit."
    }
  ]
}

Success Response (202 Accepted):

{
  "status": "success",
  "data": {
    "job_id": "bulk_job_abc123",
    "status": "queued",
    "message": "Bulk claim initiation job has been accepted and is being processed."
  }
}

Webhooks

Receive real-time notifications for critical insurance events by configuring a webhook endpoint. We will send an HTTP POST request with a JSON payload to the URL you provide.

You can set up your webhook URL in the LateShipment.com dashboard under My Profile > Webhooks.

Your endpoint must respond with a 200 OK status code to acknowledge receipt of the webhook. Any other response code will be considered a failure, and we will retry sending the webhook.

Webhook Events

policy.created Triggered when a new insurance policy is successfully created.

{
  "event_id": "evt_12345",
  "event_type": "policy.created",
  "created_at": "2024-07-18T10:00:00Z",
  "data": {
    "object": "policy",
    "policy_id": "pol_1a2b3c4d5e6f7g8h",
    "tracking_number": "1Z999AA10123456784",
    "status": "active",
    "insured_value": 150.75,
    "premium_charged": 1.25
  }
}

claim.status.updated Triggered when the status of a claim changes.

{
  "event_id": "evt_67890",
  "event_type": "claim.status.updated",
  "created_at": "2024-07-28T16:00:00Z",
  "data": {
    "object": "claim",
    "claim_id": "clm_z1y2x3w4v5u6t7s8",
    "policy_id": "pol_1a2b3c4d5e6f7g8h",
    "old_status": "under_review",
    "new_status": "approved",
    "resolution_amount": 150.75,
    "resolution_notes": "Claim approved. Payout will be processed within 3-5 business days."
  }
}