Create a customer
Creates an individual or business customer. A business is created with its associated persons in the same call, and each person becomes its own customer of type ubo.
Each new customer gets basic and intermediate KYC records with status not_started, and a customer.created webhook. A duplicate email or external_id is a 400, not a 409.
Headers
Required for POST requests. 1 to 255 printable ASCII characters. A retry with the same key and body within 24 hours returns the first response.
Request Body
Request Examples
{
"first_name": "Ada",
"last_name": "Obi",
"email": "ada.obi@example.com",
"phone": "+2348031234567",
"type": "individual",
"gender": "female",
"date_of_birth": "1990-04-16",
"external_id": "individual_12345",
"address": {
"address_line1": "12 Admiralty Way",
"city": "Lagos",
"postal_code": "106104",
"state": "NG-LA",
"country": "NG"
}
}
{
"type": "business",
"email": "ops@acmecorp.com",
"phone": "+2348031234567",
"business_name": "Acme Corporation",
"business_description": "Payments software",
"business_type": "private_limited",
"business_industry": "Information",
"registration_number": "RC-987654",
"external_id": "BUS-67890",
"address": {
"address_line1": "1800 N Pole St",
"address_line2": "Suite 202",
"city": "Orlando",
"postal_code": "32801",
"state": "US-FL",
"country": "US"
},
"associated_persons": [
{
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@acmecorp.com",
"date_of_birth": "1990-06-15",
"gender": "female",
"address": {
"address_line1": "1800 N Pole St",
"city": "Orlando",
"postal_code": "32801",
"state": "US-FL",
"country": "US"
}
}
]
}
Responses
| Status | Description |
|---|---|
200 |
Customer created |
400 |
Invalid request, or a duplicate email or external_id |
200 response
A customer. Empty fields are left out, so a business has no first_name and an individual has no business_name.
ubo is an associated person of a business.
Possible values: individual, business, ubo
ISO 3166-2 code, such as NG-LA or US-FL. It must belong to country.
ISO 3166-1 alpha-2 code in upper case, such as NG.
KYC records, one per level. Read the basic record's status to know whether the customer is verified. The create response may not include them. Get the customer to read them.
KYC level. basic is the level every flow checks. intermediate exists for every customer, but no developer route starts it.
Possible values: basic, intermediate
not_started, then pending while under review, then completed or failed. initiating appears briefly while card KYC starts.
Possible values: not_started, initiating, pending, completed, failed
The latest hosted verification link, once one was issued
Reason text when verification failed
The persons of a business. Returned when you get one business, not in the list. Each person's id is the ID to use for their own KYC.
ubo is an associated person of a business.
Possible values: individual, business, ubo
ISO 3166-2 code, such as NG-LA or US-FL. It must belong to country.
ISO 3166-1 alpha-2 code in upper case, such as NG.
KYC records, one per level. Read the basic record's status to know whether the customer is verified. The create response may not include them. Get the customer to read them.
KYC level. basic is the level every flow checks. intermediate exists for every customer, but no developer route starts it.
Possible values: basic, intermediate
not_started, then pending while under review, then completed or failed. initiating appears briefly while card KYC starts.
Possible values: not_started, initiating, pending, completed, failed
The latest hosted verification link, once one was issued
Reason text when verification failed
The persons of a business. Returned when you get one business, not in the list. Each person's id is the ID to use for their own KYC.
ubo is an associated person of a business.
Possible values: individual, business, ubo
ISO 3166-2 code, such as NG-LA or US-FL. It must belong to country.
ISO 3166-1 alpha-2 code in upper case, such as NG.
KYC records, one per level. Read the basic record's status to know whether the customer is verified. The create response may not include them. Get the customer to read them.
KYC level. basic is the level every flow checks. intermediate exists for every customer, but no developer route starts it.
Possible values: basic, intermediate
not_started, then pending while under review, then completed or failed. initiating appears briefly while card KYC starts.
Possible values: not_started, initiating, pending, completed, failed
The latest hosted verification link, once one was issued
Reason text when verification failed
The persons of a business. Returned when you get one business, not in the list. Each person's id is the ID to use for their own KYC.
ubo is an associated person of a business.
Possible values: individual, business, ubo
KYC records, one per level. Read the basic record's status to know whether the customer is verified. The create response may not include them. Get the customer to read them.
The persons of a business. Returned when you get one business, not in the list. Each person's id is the ID to use for their own KYC.
Six-digit code set from business_industry. 999999 when there is no match.
Time the customer was created, in RFC 3339 format.
Six-digit code set from business_industry. 999999 when there is no match.
Time the customer was created, in RFC 3339 format.
Six-digit code set from business_industry. 999999 when there is no match.
Time the customer was created, in RFC 3339 format.
Six-digit code set from business_industry. 999999 when there is no match.
Time the customer was created, in RFC 3339 format.
{
"data": {
"id": "e59daa17-20ed-4727-833c-e1c633782cc8",
"first_name": "Ada",
"last_name": "Obi",
"type": "individual",
"email": "ada.obi@example.com",
"phone": "+2348031234567",
"date_of_birth": "1990-04-16",
"gender": "female",
"address": {
"address_line1": "12 Admiralty Way",
"city": "Lagos",
"postal_code": "106104",
"state": "NG-LA",
"country": "NG"
},
"status": "active",
"date_added": "2026-10-13T09:12:44Z",
"external_id": "individual_12345"
},
"error": null
}
400 response
{
"data": null,
"error": "phone number is not valid"
}
{
"data": null,
"error": "invalid state \"FL\": expected ISO 3166-2 code (e.g. \"NG-LA\")"
}
{
"data": null,
"error": "failed to add customer: email already exists"
}
{
"data": null,
"error": "only company emails are allowed"
}
Authorization
- ApiKeyAuth