Skip to navigation
Customers

Create Customer

View as Markdown

Registers a new customer under your company and validates their BVN with the provider. This does not create a bank account yet — call Generate Customer Account next.

Errors: 400 BVN/email/mobile number already exists for your company, or BVN failed provider validation.

Body (JSON) - checked by Joi (customerSchema, all errors returned together). Fields not listed here are rejected.

FieldTypeRequiredRules
firstNamestringyestrimmed, 2-50 chars
lastNamestringyestrimmed, 2-50 chars
emailstringyesvalid email; lowercased
mobileNostringyesmust match ^\+234\d{10}$ (e.g. +2348031234567)
bvnstringyesexactly 11 digits
dobstringyesYYYY-MM-DD, valid date, not in the future, after 1900-01-01

Behaviour notes

  • otherName is read by the controller, but customerSchema doesn’t list it. Sending it gets "otherName" is not allowed when the schema is applied, so leave it out.
  • bvn, email and mobileNo must each be unique within your company. They are checked in that order and only the first clash is reported.
  • The BVN is then validated with the provider. A failure returns 400 Invalid BVN, and a provider OTP is sent to the BVN-linked phone, which you use in Generate Customer Account.
  • Response data contains only id, firstName and lastName.
  • Date-range failures on dob come back as the generic Joi text "dob" contains an invalid value, not the custom messages in the schema.

Authentication

AuthorizationBearer

Access token from Generate Access Token (valid 15 minutes).

Request

This endpoint expects an object.
firstNamestringOptional
lastNamestringOptional
emailstringOptional
mobileNostringOptional
bvnstringOptional
dobstringOptional

Response

Created
statusstringOptional
messagestringOptional
dataobjectOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error