> 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.

# Create a parcel customer

POST https://api.trysend.com/v1/parcel-customers
Content-Type: application/json

Create a new parcel customer (sender profile) for the authenticated business.

### Dedup behavior

- If `address_suffix` is provided and a customer with that suffix already exists for this business+mode, returns the existing customer with `200`.
- If `address_suffix` is omitted, deduplicates by `mobile`/`email` match.

### Auto-generation

When `address_suffix` is omitted, one is auto-generated using your business prefix (e.g. `PQSFX-042`).

### Pickup address

If any sender detail is provided (`first_name`, `email`, `mobile`, `origin_*`), then `origin_address`, `origin_city`, `origin_state`, and `origin_country` must all be present.


Reference: https://docs.trysend.com/api-reference/send-parcels-api/parcel-customers/create-parcel-customer

## Authentication

- `X-Api-Key` header (required)

## Request

### Body (application/json)

- `parcel_customer` (object, required)
  - `address_suffix` (string, optional) — Unique customer ID. Auto-generated if omitted.
  - `first_name` (string, optional)
  - `last_name` (string, optional)
  - `email` (string, optional)
  - `mobile` (string, optional)
  - `origin_address` (string, optional) — Pickup street. Required if any sender detail is provided.
  - `origin_city` (string, optional) — Required if origin_address is provided.
  - `origin_zip_code` (string, optional)
  - `origin_state` (string, optional) — Required if origin_address is provided.
  - `origin_country` (string, optional) — Required if origin_address is provided. ISO-2/ISO-3 or country name.

## Response

### 200

Already exists (dedup by address_suffix or contact)

- `status` (string, optional)
- `message` (string, optional)
- `data` (object, optional) — Sender profile for a parcel customer. Reusable across quotes and bookings.
  - `parcel_customer_id` (string, optional) — Internal token for this customer
  - `first_name` (string, optional, nullable)
  - `last_name` (string, optional, nullable)
  - `email` (string, optional, nullable)
  - `mobile` (string, optional, nullable)
  - `address_suffix` (string, optional) — Unique customer ID (e.g. ACME-001)
  - `full_name` (string, optional)
  - `status` (enum, optional)
    - Allowed values: `active`, `inactive`
  - `mode` (enum, optional)
    - Allowed values: `test`, `live`
  - `origin_address` (string, optional, nullable)
  - `origin_city` (string, optional, nullable)
  - `origin_zip_code` (string, optional, nullable)
  - `origin_state` (string, optional, nullable)
  - `origin_country` (string, optional, nullable)
  - `created_at` (datetime, optional)

### 201

Created

- `status` (string, optional)
- `message` (string, optional)
- `data` (object, optional) — Sender profile for a parcel customer. Reusable across quotes and bookings.
  - `parcel_customer_id` (string, optional) — Internal token for this customer
  - `first_name` (string, optional, nullable)
  - `last_name` (string, optional, nullable)
  - `email` (string, optional, nullable)
  - `mobile` (string, optional, nullable)
  - `address_suffix` (string, optional) — Unique customer ID (e.g. ACME-001)
  - `full_name` (string, optional)
  - `status` (enum, optional)
    - Allowed values: `active`, `inactive`
  - `mode` (enum, optional)
    - Allowed values: `test`, `live`
  - `origin_address` (string, optional, nullable)
  - `origin_city` (string, optional, nullable)
  - `origin_zip_code` (string, optional, nullable)
  - `origin_state` (string, optional, nullable)
  - `origin_country` (string, optional, nullable)
  - `created_at` (datetime, optional)

## Examples

### Create with address suffix only

**Request**

```json
{
  "parcel_customer": {
    "address_suffix": "ACME-001"
  }
}
```

**Response**

```json
{
  "status": "string",
  "message": "string",
  "data": {
    "parcel_customer_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "mobile": "string",
    "address_suffix": "string",
    "full_name": "string",
    "status": "active",
    "mode": "test",
    "origin_address": "string",
    "origin_city": "string",
    "origin_zip_code": "string",
    "origin_state": "string",
    "origin_country": "string",
    "created_at": "2024-01-15T09:30:00Z"
  }
}
```

**SDK Code**

```python Create with address suffix only
import requests

url = "https://api.trysend.com/v1/parcel-customers"

payload = { "parcel_customer": { "address_suffix": "ACME-001" } }
headers = {
    "X-Api-Key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```ruby Create with address suffix only
require 'uri'
require 'net/http'

url = URI("https://api.trysend.com/v1/parcel-customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parcel_customer\": {\n    \"address_suffix\": \"ACME-001\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

### Create with address suffix only

**Request**

```json
{
  "parcel_customer": {
    "address_suffix": "ACME-001"
  }
}
```

**Response**

```json
{
  "status": "string",
  "message": "string",
  "data": {
    "parcel_customer_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "mobile": "string",
    "address_suffix": "string",
    "full_name": "string",
    "status": "active",
    "mode": "test",
    "origin_address": "string",
    "origin_city": "string",
    "origin_zip_code": "string",
    "origin_state": "string",
    "origin_country": "string",
    "created_at": "2024-01-15T09:30:00Z"
  }
}
```

**SDK Code**

```python Create with address suffix only
import requests

url = "https://api.trysend.com/v1/parcel-customers"

payload = { "parcel_customer": { "address_suffix": "ACME-001" } }
headers = {
    "X-Api-Key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```ruby Create with address suffix only
require 'uri'
require 'net/http'

url = URI("https://api.trysend.com/v1/parcel-customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parcel_customer\": {\n    \"address_suffix\": \"ACME-001\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

### Create with full sender details

**Request**

```json
{
  "parcel_customer": {
    "address_suffix": "ACME-002",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "mobile": "+2348012345678",
    "origin_address": "12 Broad Street",
    "origin_city": "Lagos",
    "origin_zip_code": "100001",
    "origin_state": "Lagos",
    "origin_country": "Nigeria"
  }
}
```

**Response**

```json
{
  "status": "string",
  "message": "string",
  "data": {
    "parcel_customer_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "mobile": "string",
    "address_suffix": "string",
    "full_name": "string",
    "status": "active",
    "mode": "test",
    "origin_address": "string",
    "origin_city": "string",
    "origin_zip_code": "string",
    "origin_state": "string",
    "origin_country": "string",
    "created_at": "2024-01-15T09:30:00Z"
  }
}
```

**SDK Code**

```python Create with full sender details
import requests

url = "https://api.trysend.com/v1/parcel-customers"

payload = { "parcel_customer": {
        "address_suffix": "ACME-002",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "mobile": "+2348012345678",
        "origin_address": "12 Broad Street",
        "origin_city": "Lagos",
        "origin_zip_code": "100001",
        "origin_state": "Lagos",
        "origin_country": "Nigeria"
    } }
headers = {
    "X-Api-Key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```ruby Create with full sender details
require 'uri'
require 'net/http'

url = URI("https://api.trysend.com/v1/parcel-customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parcel_customer\": {\n    \"address_suffix\": \"ACME-002\",\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"email\": \"john@example.com\",\n    \"mobile\": \"+2348012345678\",\n    \"origin_address\": \"12 Broad Street\",\n    \"origin_city\": \"Lagos\",\n    \"origin_zip_code\": \"100001\",\n    \"origin_state\": \"Lagos\",\n    \"origin_country\": \"Nigeria\"\n  }\n}"

response = http.request(request)
puts response.read_body
```