Use the canonical customer endpoint instead. New integrations should create customers with
POST /api/v1/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.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
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. |
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
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": "[email protected]",
"phone": "08012345678",
"firstName": "John",
"lastName": "Doe",
"country": "NG",
"metadataJson": "{\"tier\":\"gold\"}"
}'
Response
{
"data": {
"id": 4021,
"externalId": "user_10231",
"email": "[email protected]",
"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 |