'/%3e%3cdefs%3e%3cpattern%20id='pattern0_2104_4598'%20patternContentUnits='objectBoundingBox'%20width='1'%20height='1'%3e%3cuse%20xlink:href='%23image0_2104_4598'%20transform='matrix(0.00376176%200%200%200.0172414%20-0.00219436%200)'/%3e%3c/pattern%3e%3cimage%20id='image0_2104_4598'%20width='267'%20height='58'%20preserveAspectRatio='none'%20xlink:href='data:image/png;base64,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'/%3e%3c/defs%3e%3c/svg%3e)
Overview
The Customers API enables you to create, retrieve, update, and delete customer profiles. Use these endpoints to manage customer identity details, contact information, and track customers across transactions for reporting and compliance.
Create a new customer
Use Case
This endpoint is used to create a new customer.
Create Customer Request Body
Creating a customer for a naira virtual account, or for a card, takes different fields from the ones below. See Customer Requirements for virtual accounts, and Card KYC for cardholders. Not sure which applies? Read Which KYC endpoint do I use?.
A valid and unique email address used to identify and contact the customer. It also serves as a primary login credential.
First name of the customer. This is typically used for identification and personalization in communications.
Last name or surname of the customer. Combined with the first name to form the full legal name.
Customer’s active phone number, formatted in international standard (e.g., +233XXXXXXXXX). May be used for verification and notifications. Must be unique across your customers: see the note below.
Three-letter ISO 3166-1 alpha-3 country code (e.g. 'NGA', 'USA', 'GBR').
The type of customer account to create. Accepted values: 'individual' for personal accounts or 'business' for company accounts.
A unique, client-generated identifier for the customer. Useful for idempotency and for correlating the customer with records in your own system.
We match customers on email, phone_number and BVN (id_number). If you send an email, phone number or BVN that already belongs to one of your customers, you get 201 Created with that existing customer, and the other fields you sent are ignored. Compare the returned email, phone number and name with what you sent, and if they differ, one of those details is already taken.
Create Customer Response
Returns a Customer Response.
Standard response structure for all customer endpoints.
Top-level flag indicating whether the request was processed successfully.
Human-readable status message describing the outcome.
Envelope wrapping the created customer record.
Unique identifier assigned to the customer. Use it in subsequent endpoints (get, update, blacklist).
The customer's given name.
The customer's family name or surname.
Email address associated with the customer.
The customer account type: 'individual' or 'business'.
Identifier of the company this customer belongs to.
UUID of the dashboard user or API client that created this customer. It is an audit field, not something you need to supply or match.
Whether the customer account is currently active. Blacklisted customers return false.
Stringified JSON of additional metadata attached to the customer (e.g. '{}' when empty).
RFC 3339 / ISO 8601 timestamp of when the customer was created (UTC).
RFC 3339 / ISO 8601 timestamp of the most recent update to the customer record (UTC).
Top-level response metadata (support and debugging info).
Unique identifier for this API request, useful for log correlation and support.
Top-level RFC 3339 / ISO 8601 server timestamp of when the response was generated (UTC).
Update Customer
Use Case
This endpoint is used to update an existing customer's information.
The unique identifier of the customer you want to update
Update Customer Request Body
Customer's first name.
Customer's last name.
Whether the customer is active.
Only include the fields you want to change — any field omitted from the request body keeps its current value.
Update Customer Response
Returns an updated CustomerResponse..
The response is identical to that of Customer Response. Refer to that section for field explanations.
List Customers
Use Case
Retrieve a paginated list of customers, optionally filtering on id, reference, email, customer_type, or is_active. Pass any combination of these as query parameters on the GET /api/customers endpoint.
Query Parameters
Filter by the customer's system-generated UUID.
Filter by the customer's external reference if you attached one.
Filter by the customer's email address (exact match).
Filter by account type: 'individual' or 'business'.
Filter by active status — 'true' for active customers, 'false' for blacklisted/inactive.
Response
Returns data.customers[] with cursor-based pagination — has_more, next_cursor, prev_cursor, page_size, and total. Pass next_cursor on the next request to page forward.
Customer fields are identical to the Create Customer Response shape. Refer to that section for per-field explanations. Customers created with full KYC also include country, date_of_birth, id_type, id_number, dial_code, phone_number, line1, city, state, and postal_code.
Get Customer by ID
Use Case
Retrieve a single customer by its system-generated UUID, passed as a path parameter on the GET /api/customers/:customerId endpoint.
Path Parameters
The customer's system-generated UUID.
Response
Returns the customer object directly at data.
Customer fields are identical to the Create Customer Response shape. Refer to that section for per-field explanations.