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

# Create Customer

> Create an end-customer record. Pass your own externalId to keep it idempotent and in sync with your system.

<Warning>
  **Use the canonical customer endpoint instead.** New integrations should create customers with
  [`POST /api/v1/customers`](/api-reference/waas-customers) — one record that serves wallets **and** cards, captures the full KYC ladder, and carries the same identity the card providers require. This older `/business/customers` route remains only for backward compatibility.
</Warning>

Create an end-customer record. All fields are optional, but passing an `externalId` (your own stable id for the customer) lets you reconcile customers with your system and keeps creates idempotent.

## Endpoint

```
POST /api/v1/business/customers
```

**Signature required:** Yes

## Headers

| Header                       | Required | Description                                                                                                                                                                    |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-Numero-Api-Key`           | Yes      | Your API key                                                                                                                                                                   |
| `X-Numero-Signature`         | Yes      | Base64 HMAC-SHA256 over the exact raw request body (POST) or the canonicalised query string (GET), keyed with your **Public Key**. See [Request signing](/03-request-signing). |
| `X-Numero-Signature-Version` | Yes      | Always `v2`.                                                                                                                                                                   |

## Request body

| Field          | Type   | Required | Description                               |
| -------------- | ------ | -------- | ----------------------------------------- |
| `externalId`   | string | No       | Your own stable id for this customer      |
| `email`        | string | No       | Customer's email                          |
| `phone`        | string | No       | Customer's phone number                   |
| `firstName`    | string | No       | Customer's first name                     |
| `lastName`     | string | No       | Customer's last name                      |
| `country`      | string | No       | ISO-3166 alpha-2 country code (e.g. `NG`) |
| `metadataJson` | string | No       | Free-form JSON string you control         |

## Request example

```bash theme={null}
curl -X POST "https://api.usenumero.com/numeroaccount/api/v1/business/customers" \
  -H "Content-Type: application/json" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2" \
  -d '{
    "externalId": "user_10231",
    "email": "john.doe@example.com",
    "phone": "08012345678",
    "firstName": "John",
    "lastName": "Doe",
    "country": "NG",
    "metadataJson": "{\"tier\":\"gold\"}"
  }'
```

## Response

```json theme={null}
{
  "data": {
    "id": 4021,
    "externalId": "user_10231",
    "email": "john.doe@example.com",
    "phone": "08012345678",
    "firstName": "John",
    "lastName": "Doe",
    "country": "NG",
    "kycStatus": "PENDING",
    "metadataJson": "{\"tier\":\"gold\"}",
    "createdAt": "2024-01-15T12:00:00Z",
    "updatedAt": "2024-01-15T12:00:00Z"
  },
  "error": null,
  "meta": {
    "request_id": "req_365123ebc73323f1482508560ce6400e",
    "pagination": null
  }
}
```

| Field                     | Type     | Description                                                  |
| ------------------------- | -------- | ------------------------------------------------------------ |
| `id`                      | integer  | Numero's customer id — use it on all `/customers/{id}` calls |
| `externalId`              | string   | The id you supplied                                          |
| `kycStatus`               | string   | Current KYC state for the customer                           |
| `createdAt` / `updatedAt` | datetime | Record timestamps                                            |