> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trysend.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trysend.com/_mcp/server.

# Example cURL requests

Replace `YOUR_API_KEY` with your test or live key.

## Parcel customers

**Create a parcel customer (address suffix only)**

```bash
curl -X POST "https://api.trysend.com/v1/parcel-customers" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parcel_customer": {
      "address_suffix": "JUNIGO-001"
    }
  }'
```

**Create a parcel customer (full details)**

```bash
curl -X POST "https://api.trysend.com/v1/parcel-customers" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parcel_customer": {
      "address_suffix": "JUNIGO-002",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@junigo.com",
      "mobile": "+2348012345678",
      "origin_address": "12 Broad Street",
      "origin_city": "Lagos",
      "origin_state": "Lagos",
      "origin_zip_code": "100001",
      "origin_country": "Nigeria"
    }
  }'
```

**List parcel customers**

```bash
curl -X GET "https://api.trysend.com/v1/parcel-customers" \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Get one parcel customer**

```bash
curl -X GET "https://api.trysend.com/v1/parcel-customers/pc_abc123def456" \
  -H "X-Api-Key: YOUR_API_KEY"
```

## Packages

**Retrieve a package**

```bash
curl -X GET "https://api.trysend.com/v1/packages/ABC123XYZ" \
  -H "X-Api-Key: YOUR_API_KEY"
```

**List packages (filter by status)**

```bash
curl -X GET "https://api.trysend.com/v1/packages?status=warehouse" \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Track a package**

```bash
curl -X GET "https://api.trysend.com/v1/packages/ABC123XYZ/track" \
  -H "X-Api-Key: YOUR_API_KEY"
```

## Parcel quotes

### Export air (carrier rates)

```bash
curl -X POST "https://api.trysend.com/v1/parcel_quotes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parcel": {
      "direction": "export",
      "transport_mode": "air",
      "sender": {
        "name": "John Sender",
        "email": "sender@example.com",
        "phone": "+1234567890",
        "address": {
          "street": "123 Main St",
          "city": "New York",
          "state": "NY",
          "postal_code": "10001",
          "country": "US"
        }
      },
      "recipient": {
        "name": "Jane Receiver",
        "email": "receiver@example.com",
        "phone": "+0987654321",
        "address": {
          "street": "456 Oak Ave",
          "city": "Los Angeles",
          "state": "CA",
          "postal_code": "90001",
          "country": "US"
        }
      },
      "package": {
        "weight": 5.0,
        "length": 10,
        "width": 8,
        "height": 6,
        "item_description": "Electronics"
      }
    }
  }'
```

### Import air (warehouse intake, pending)

Identify the customer with `address_suffix` (unique ID). Send cargo rows in `packages[]`:

```bash
curl -X POST "https://api.trysend.com/v1/parcel_quotes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parcel": {
      "direction": "import",
      "transport_mode": "air",
      "address_suffix": "YSDX-UGTE-1234",
      "recipient": {
        "name": "Your Warehouse",
        "email": "warehouse@example.com",
        "phone": "+2348012345678",
        "address": {
          "street": "1 Warehouse Road",
          "city": "Lagos",
          "state": "Lagos",
          "postal_code": "100001",
          "country": "NG"
        }
      },
      "packages": [
        {
          "package_type": "Pallet",
          "weight": 120,
          "length": 120,
          "width": 100,
          "height": 80
        }
      ]
    }
  }'
```

### Import ocean — flat fields (Send dashboard shape)

Same body as the Send dashboard. Link the customer with `parcel_customer_token` (origin is filled automatically). Returns **`pending`** with one `Ocean Freight` rate in `rates[]` — no warehouse parcel until Incoming intake:

```bash
curl -X POST "https://api.trysend.com/v1/parcel_quotes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parcel": {
      "direction": "import",
      "transport_mode": "ocean",
      "parcel_customer_token": "YOUR_PARCEL_CUSTOMER_TOKEN",
      "dest_name": "Your Business Ltd",
      "dest_mobile": "+2348012345678",
      "dest_email": "ops@example.com",
      "dest_address": "1 Warehouse Road",
      "dest_city": "Lagos",
      "dest_state": "Lagos",
      "destination_country": "Nigeria",
      "packages": [
        {
          "container_size": "40'",
          "quantity": 2,
          "commodity": "Textiles"
        }
      ]
    }
  }'
```

Response is **`pending`** with a single `Ocean Freight` rate. Use that `rate_id` with `create_shipment` to confirm the booking. After confirmation, the quote is **`booked`** with `selected_rate` and `estimated_price`. Final price may still be adjusted at warehouse receive and billed on an invoice. No warehouse parcel is created on quote create — receive it from Virtual Warehouse (Incoming).

### Import ocean — address\_suffix (unique ID) + last-mile delivery

Use `address_suffix` when the customer already exists in your directory. Sender fields are filled from their profile; only `recipient` is required for delivery:

```bash
curl -X POST "https://api.trysend.com/v1/parcel_quotes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parcel": {
      "direction": "import",
      "transport_mode": "ocean",
      "address_suffix": "YSDX-UGTE-1234",
      "recipient": {
        "name": "Jane Receiver",
        "email": "jane@example.com",
        "phone": "+2348012345678",
        "address": {
          "street": "2 Marina",
          "city": "Lagos",
          "state": "Lagos",
          "postal_code": "100001",
          "country": "NG"
        }
      },
      "packages": [
        {
          "container_size": "40'",
          "quantity": 2,
          "commodity": "Textiles"
        }
      ]
    }
  }'
```

### Import ocean — no last mile (deliver to your business/warehouse)

Use `address_suffix` **or** full `sender`. Set `recipient` to your business or warehouse address:

```bash
curl -X POST "https://api.trysend.com/v1/parcel_quotes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parcel": {
      "direction": "import",
      "transport_mode": "ocean",
      "address_suffix": "1234",
      "recipient": {
        "name": "Your Business Ltd",
        "email": "business@example.com",
        "phone": "+2348012345678",
        "address": {
          "street": "1 Warehouse Road",
          "city": "Lagos",
          "state": "Lagos",
          "postal_code": "100001",
          "country": "NG"
        }
      },
      "packages": [
        {
          "container_size": "40'",
          "quantity": 2,
          "commodity": "Textiles"
        }
      ]
    }
  }'
```

### Export ocean (pending estimate)

```bash
curl -X POST "https://api.trysend.com/v1/parcel_quotes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parcel": {
      "direction": "export",
      "transport_mode": "ocean",
      "sender": {
        "name": "Lagos Exports Ltd",
        "email": "export@example.com",
        "phone": "+2348012345678",
        "address": {
          "street": "10 Export Zone",
          "city": "Lagos",
          "state": "Lagos",
          "postal_code": "100001",
          "country": "NG"
        }
      },
      "recipient": {
        "name": "Overseas Buyer",
        "email": "buyer@example.com",
        "phone": "+442079460958",
        "address": {
          "street": "456 Elm Street",
          "city": "London",
          "state": "Greater London",
          "postal_code": "SW1A 1AA",
          "country": "GB"
        }
      },
      "packages": [
        {
          "container_size": "40'\''",
          "quantity": 1,
          "commodity": "Machinery"
        }
      ]
    }
  }'
```

**List parcel quotes**

```bash
curl -X GET "https://api.trysend.com/v1/parcel_quotes?status=pending" \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Get one parcel quote**

Pending **export air** quotes are refreshed automatically when retrieved.

```bash
curl -X GET "https://api.trysend.com/v1/parcel_quotes/pq_abc123xyz" \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Confirm quote (create shipment)**

Use `rate_id` from the quote's `rates[]` after creating an **export air** or **ocean** quote. Import air can be confirmed without a `rate_id`. Export air returns carrier tracking/label details. Ocean confirms the single Ocean Freight estimate and moves the quote to `booked`.

```bash
curl -X POST "https://api.trysend.com/v1/packages/pq_abc123xyz/create_shipment" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rate_id": "rate_123abc"}'
```