Customers

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.

Customers API Endpoints

Create a new customer

Use Case

This endpoint is used to create a new customer.

Base URL

Create Customer Request Body

first_namestringNot Required

First name of the customer. This is typically used for identification and personalization in communications.

last_namestringNot Required

Last name or surname of the customer. Combined with the first name to form the full legal name.

emailstringRequired

A valid and unique email address used to identify and contact the customer. It also serves as a primary login credential.

phonestringNot Required

Customer’s active phone number, formatted in international standard (e.g., +233XXXXXXXXX). May be used for verification and notifications.

country_codestringNot Required

The country dial code used for phone number formatting (e.g., '+234' for Nigeria, '+1' for United States).

customer_typestringRequired

The type of customer account to create. Accepted values: 'individual' for personal accounts or 'business' for company accounts.

Request Body

Create Customer Response

Returns a Customer Response.

Standard response structure for all customer endpoints.

successBoolean

Top-level flag indicating whether the request was processed successfully.

messageString

Human-readable status message describing the outcome.

dataObject

Envelope wrapping the created customer record.

data.idUUID

Unique identifier assigned to the customer. Use it in subsequent endpoints (get, update, blacklist).

data.first_nameString

The customer's given name.

data.last_nameString

The customer's family name or surname.

data.emailString

Email address associated with the customer.

data.customer_typeString

The customer account type: 'individual' or 'business'.

data.company_idUUID

Identifier of the company this customer belongs to.

data.created_byUUID

Identifier of the user or API client that created this customer.

data.is_activeBoolean

Whether the customer account is currently active. Blacklisted customers return false.

data.metadataString

Stringified JSON of additional metadata attached to the customer (e.g. '{}' when empty).

data.created_atDate

RFC 3339 / ISO 8601 timestamp of when the customer was created (UTC).

data.updated_atDate

RFC 3339 / ISO 8601 timestamp of the most recent update to the customer record (UTC).

metadataObject

Top-level response metadata (support and debugging info).

metadata.request_idString

Unique identifier for this API request, useful for log correlation and support.

timestampDate

Top-level RFC 3339 / ISO 8601 server timestamp of when the response was generated (UTC).

Response

Update Customer

Use Case

This endpoint is used to update an existing customer's information.

idstring (UUID)Required

The unique identifier of the customer you want to update

Update Customer

Update Customer Request Body

emailstringOptional

Customer's valid email address.

first_namestringOptional

Customer's first name.

last_namestringOptional

Customer's last name.

Partial Updates

Only include the fields you want to change — any field omitted from the request body keeps its current value.

Request Body

Update Customer Response

Returns an updated CustomerResponse..

Note

The response is identical to that of Customer Response. Refer to the Customer Response. section for field explanations.

Update Customer Response

Get Customer by ID or Query Parameters

Use Case

Retrieve a customer by 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

idUUIDOptional

Filter by the customer's system-generated UUID.

referencestringOptional

Filter by the customer's external reference if you attached one.

emailstringOptional

Filter by the customer's email address (exact match).

customer_typestringOptional

Filter by account type: 'individual' or 'business'.

is_activebooleanOptional

Filter by active status — 'true' for active customers, 'false' for blacklisted/inactive.

Get Customer

Response

The response shape depends on how you called the endpoint.

By Query Parameters: returns data.customers[] with page, page_size, and total for pagination — even when a single match is found.

By ID: returns the customer object directly at data.

Field Reference

Customer fields are identical to the Create Customer Response shape. Refer to that section for per-field explanations.

Get Customer Response