Skip to main content
PATCH
Update a customer

Null and absent are different

An absent field is left as it is. An explicit null clears the stored value. "middleName": null erases a middle name; omitting middleName keeps it. For an individual customer, displayName and name are recomposed from the first, middle, and last names whenever any of them changes.
A successful update emits a customer.updated webhook carrying this same response body.

Error codes

Authorizations

Authorization
string
header
required

A secret API key, sent as Authorization: Bearer sk_test_… in sandbox or Bearer sk_live_… in live.

Path Parameters

customerId
string
required

Customer ULID. A 26-character ULID.

Required string length: 26
Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

Body

application/json
externalReference
string
Required string length: 1 - 120
email
string<email>
Maximum string length: 255
phoneNumber
string
Pattern: ^\+[1-9]\d{6,19}$
address
object
firstName
string
Required string length: 1 - 100
middleName
string | null
Maximum string length: 100
lastName
string
Required string length: 1 - 100
dateOfBirth
string<date> | null
gender
enum<string> | null
Available options:
male,
female,
other
name
string
Required string length: 2 - 200
bvn
string | null
Pattern: ^\d{11}$
nin
string | null
Pattern: ^\d{11}$
passport
string | null
Maximum string length: 50
driversLicence
string | null
Maximum string length: 50
taxId
string | null
Maximum string length: 50
registrationNumber
string | null
Maximum string length: 50

Response

Successful response.

id
string
required

A 26-character ULID.

Required string length: 26
Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

type
enum<string>
required

Fixed at creation. It decides which of the fields below apply.

Available options:
individual,
business
jurisdiction
string
required

Uppercase ISO 3166-1 alpha-2 country of the relationship. Fixed at creation.

Required string length: 2
externalReference
string | null
required

Your own reference. Unique among your customers that are not archived.

displayName
string
required

The business name, or the personal names joined, or "Unnamed customer" when neither is on file. Always safe to render.

name
string | null
required
firstName
string | null
required
middleName
string | null
required
lastName
string | null
required
email
string<email> | null
required
phoneNumber
string | null
required
dateOfBirth
string<date> | null
required
gender
enum<string> | null
required
Available options:
male,
female,
other
address
object
required
tier
enum<integer>
required

Verification tier. Every customer is created at tier 1. It becomes 3 when the customer passes verification, announced by customer.kyc.approved. No endpoint sets it directly, and a later suspension does not lower it.

Available options:
1,
2,
3
hasBvn
boolean
required

Whether a BVN is on file. The number itself is never returned.

hasNin
boolean
required

Whether a NIN is on file.

hasPassport
boolean
required

Whether a passport number is on file.

hasDriversLicence
boolean
required

Whether a driving licence number is on file.

hasTaxId
boolean
required

Whether a tax identifier is on file.

hasRegistrationNumber
boolean
required

Whether a company registration number is on file. Business customers only.

createdAt
string<date-time>
required
Example:

"2026-08-14T09:00:00.000Z"

updatedAt
string<date-time>
required
Example:

"2026-08-14T09:00:00.000Z"