A customer is an entity (individual or business) created by an institution. Customers represent the institution's end-users who will transact using the platform. Each customer has a profile containing identification details and can own multiple sub-accounts across currencies.
The Create Customer API allows institutions to create Individuals or Business Customers
Request Parameters
The request must include the following parameters in JSON format:
Parameter
Type
Required
Description
currency
string
✅
The currency of the sub-account (e.g., USD, NGN, EUR).
client_reference
string
❌
Optional Institution-generated reference
email
string
❌
The email address of the customer.
type
string
❌
The type of customer (BUSINESS or INDIVIDUAL).
individual
object
❌
Required if type is INDIVIDUAL
business
object
❌
Required if type is BUSINESS
country_data
object
❌
Optional object containing country specific data
Country Data
Parameter
Type
Required
Description
ng.bvn
string
❌
11 chars Nigerian BVN
ng.nin
string
❌
11 chars Nigerian NIN
Individual
Parameter
Type
Required
Description
first_name
string
✅
First name of Individual customer
last_name
string
✅
Last name of Individual customer
other_name
string
❌
Other names
date_of_birth
string
❌
Date of birth in ISO 8601 format (YYYY-MM-DD)
residential_address
object
❌
See Address below
phone_number
string
❌
Phone number in E.164, e.g. (+234XXXXXXXX).
Business
Parameter
Type
Required
Description
name
string
✅
The name of the business
phone_number
string
❌
Phone number in E.164, e.g. (+234XXXXXXXX).
incorporation_number
string
❌
Business registration or incorporation number
incorporation_date
string
❌
Date of incorporation in ISO 8601 format (YYYY-MM-DD)
incorporation_country
string
❌
Two-letter country code where business is incorporated. This must always exist with incorporation_number
registered_address
object
❌
See the Address object below
tax_id
string
❌
Business tax identification number
business_type
string
❌
The legal structure of the business (CORPORATION, LLC, PARTNERSHIP, SOLE_PROPRIETORSHIP)
website
string
❌
Business website URL
contact_person
object
❌
Details of contact person for the business
contact_person.first_name
string
✅
First name of the business contact person
contact_person.last_name
string
✅
Last name of the business contact person
contact_person.email
string
❌
Last name of the business contact person
contact_person.phone_number
string
❌
Phone number of business contact in E.164 format
contact_person.position
string
❌
Job title or position of contact within the business
Indicates KYC/KYB verification state of the customer. Can be VERIFIED or UNVERIFIED
state
string
✅
ACTIVE, INACTIVE, BLOCKED
🚧
Customers must be in ACTIVE state before accounts can be created for them
📘
Some account types may be unavailable to some customers depending on the verification_status
Customer Updates
Updates can be made to customers by calling the appropriate patch endpoint for the field that needs an update. Properties can be removed by setting them explicitly to null as far as they are optional fields.
Update Endpoints
Endpoint
HTTP Method
Description
/customer/{id}/individual
PATCH
Update individual customer details
/customer/{id}/business
PATCH
Update business customer details
/customer/{id}/country_data
PATCH
Update country-specific data
Update Rules
Partial Updates: Only include fields you want to update
Required Fields: Cannot be set to null (e.g., first_name, last_name for individuals; name for businesses)
Optional Fields: Can be set to null to remove the value
At Least One Field: Each update request must include at least one field
Address Updates: Address fields must be updated as a complete object - partial address updates are not supported
Update Individual Customer
Request Parameters
Include any individual customer fields you want to update.
When updating address fields, you must provide a complete address object with all required fields. Partial address updates are not supported.
Parameter
Type
Required
Description
line_1
string
✓
First line of address
line_2
string
Second line of address
city
string
City name
state
string
State, province, or region
postal_code
string
Postal or ZIP code
country
string
✓
Two-letter country code
Contact Person Object
When updating the contact person, you must provide a complete contact person object with all required fields. Partial contact person updates are not supported.
Parameter
Type
Required
Description
first_name
string
✓
First name of contact person
last_name
string
✓
Last name of contact person
email
string
Email address of contact person
phone_number
string
Phone number in E.164 format
position
string
Job title or position
Customer Response Schema Definitions
Common Fields (Always Present)
Field
Data Type
Description
data.type
string
Type of customer ("INDIVIDUAL" or "BUSINESS")
data.client_reference
string
Client's custom identifier
data.email
string
Customer's email address
data.id
string
Unique identifier for the customer (UUID format)
data.created_date
string
ISO timestamp of when the customer record was created
data.updated_date
string
ISO timestamp of when the customer record was last updated
data.state
string
Current state of the customer record (e.g., "CREATED")
data.verification_status
string
Status of customer verification (e.g., "VERIFIED")
