Skip to navigation
API ReferenceAccounts

Create account

Opens an account for a customer from their BVN. Halo checks the BVN with the bank, and the phone number you send must match the phone number on the BVN record. The customer’s names are taken from the BVN record.

Each customer can hold one account with your business. If the customer already has one, it is returned.

When the bank is still opening the account the answer is 202. Call again with the same details to get the account; no second account is opened.

The customer is returned as user.id only.

Authentication

AuthorizationBearer

Your Halo partner API key, sent as Authorization: Bearer <key>.

Request

This endpoint expects an object.
BVNstringRequired
The customer's Bank Verification Number.
PhoneNostringRequired
Must match the phone number on the BVN record.
EmailstringRequired
The customer's email address.
LastNamestringRequired
The customer's last name. The name on the BVN record is used.
OtherNamesstringRequired
The customer's other names. The names on the BVN record are used.
isVirtualbooleanRequired
Set to true to link the account to your business pool account.
FirstNamestring or nullOptional
The customer's first name. The name on the BVN record is used.
FullNamestring or nullOptional
The customer's full name.
NationalIdentityNostring or nullOptional
The customer's NIN.
Genderstring or nullOptional
The customer's gender.
AccountNamestring or nullOptional
The name on the account.

Response

The account is open.
statusboolean
True on success, false otherwise.
messagestring or map from strings to lists of strings
A short message. On a 422 validation failure it is an object of field names to error lists.
status_codeinteger
The HTTP status code.
dataanyOptional
The result. Left out on most errors.

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error
429
Too Many Requests Error