> ## Documentation Index
> Fetch the complete documentation index at: https://docs.juicyway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Customer

> Before creating a wallet, you must first create a customer. A customer can be an individual or a business and represents the entity that owns one or more wallets.

## Endpoint

```json theme={null}
POST /customers
```

## Description

This endpoint provisions a customer in the system. The customer record is required to associate wallets, transactions, and payment methods. After creation, the customer typically starts in a `pending_kyc` status until verification is completed.

## Request Body

```json theme={null}
{
  "first_name": "James",
  "last_name": "Okafor",
  "email": "james.okafor@example.com",
  "phone": "+2348012345678",
  "type": "individual",
  "billing_address": {
    "line1": "123 Test Lane",
    "line2": "Suite 456",
    "city": "Lagos",
    "state": "Lagos",
    "zip_code": "100001",
    "country": "NG"
  }
}
```

***

## Request Fields

| Field             | Type   | Required | Description                                 |
| :---------------- | :----- | :------- | :------------------------------------------ |
| `first_name`      | string | Yes      | Customer’s first name                       |
| `last_name`       | string | Yes      | Customer’s last name                        |
| `email`           | string | Yes      | Customer’s email address                    |
| `phone`           | string | Yes      | Customer’s phone number (with country code) |
| `type`            | string | Yes      | Customer type: `individual` or `business`   |
| `billing_address` | object | Yes      | Customer’s billing address                  |

### Billing Address Fields

| Field      | Type   | Required | Description               |
| :--------- | :----- | :------- | :------------------------ |
| `line1`    | string | Yes      | Street address line 1     |
| `line2`    | string | No       | Street address line 2     |
| `city`     | string | Yes      | City                      |
| `state`    | string | Yes      | State or region           |
| `zip_code` | string | Yes      | Postal code               |
| `country`  | string | Yes      | ISO 2-letter country code |

***

## Response

### Success Response (201 Created)

```
{
  "data": {
    "id": "7da75a46-a1bc-11ee-9a32-560f156a658b",
    "status": "pending_kyc",
    "created_at": "2025-09-22T09:01:09Z"
  }
}
```

***

## Response Fields

| Field        | Type   | Description                                     |
| :----------- | :----- | :---------------------------------------------- |
| `id`         | string | Unique customer identifier                      |
| `status`     | string | Customer status (`pending_kyc`, `active`, etc.) |
| `created_at` | string | Timestamp when the customer was created         |

***

## Example cURL Request

```bash theme={null}
curl -X POST https://api.yourdomain.com/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "James",
    "last_name": "Okafor",
    "email": "james.okafor@example.com",
    "phone": "+2348012345678",
    "type": "individual",
    "billing_address": {
      "line1": "123 Test Lane",
      "line2": "Suite 456",
      "city": "Lagos",
      "state": "Lagos",
      "zip_code": "100001",
      "country": "NG"
    }
  }'
```

***

## Common Errors

| Status Code | Description                                |
| :---------- | :----------------------------------------- |
| `400`       | Invalid request or missing required fields |
| `401`       | Unauthorized                               |
| `409`       | Customer already exists                    |
| `422`       | Invalid field values                       |

***

## Notes & Best Practices

* Ensure all mandatory fields are provided and formatted correctly.
* The `status` starts as `pending_kyc` if verification is required.
* Store the returned `id` as it is needed to create wallets and associate transactions.
* Validate emails and phone numbers to prevent errors in subsequent wallet creation.

***

## Typical Flow

1. Create a customer via `POST /customers`.
2. Verify customer if required (KYC).
3. Create a wallet for the customer using `POST /wallets`.
4. Add payment methods and perform transactions as needed.