Skip to main content
POST
Apply for an account

Authorizations

​
Authorization
string
header
required

Authorization: Bearer <key>. Sandbox keys start with mgw_test_ and live keys start with mgw_live_. Each key works only in its own environment, and a live key works only from the IP addresses or ranges registered for it.

Headers

​
Idempotency-Key
string
required

A key you choose to identify this request. Send the same key every time you retry the request. Once used, a key stays tied to that request permanently. It must be printable ASCII with no spaces, and we compare it byte for byte. Send the header only once.

Required string length: 1 - 255
Pattern: ^[!-~]+$

Body

application/json

Every field is a string of at most 200 bytes, trimmed at both ends, with no control or invisible characters. We reject unknown fields and any field that appears twice, even with different letter case.

​
first_name
string
required
Maximum string length: 200
​
last_name
string
required
Maximum string length: 200
​
gender
enum<string>
required
Available options:
M,
F
​
date_of_birth
string<date>
required

Must be after 1900-01-01, and no later than today in Lagos.

​
email
string
required
Maximum string length: 200
​
phone
string
required
Maximum string length: 200
​
street
string
required
Maximum string length: 200
​
city
string
required
Maximum string length: 200
​
state
string
required

A code from GET /v1/reference/states.

Pattern: ^[A-Za-z0-9-]{1,32}$
​
postcode
string
required
Maximum string length: 200
​
state_of_origin
string
required

A code from GET /v1/reference/states.

Pattern: ^[A-Za-z0-9-]{1,32}$
​
lga_of_origin
string
required

A code from GET /v1/reference/states/{state}/lgas.

Pattern: ^[A-Za-z0-9-]{1,32}$
​
next_of_kin_name
string
required
Maximum string length: 200
​
next_of_kin_phone
string
required
Maximum string length: 200
​
bank
string
required

A code from GET /v1/reference/banks.

Pattern: ^[A-Za-z0-9-]{1,32}$
​
bank_account_name
string
required
Maximum string length: 200
​
bank_account_number
string
required
Maximum string length: 200
​
bank_account_opened
string<date>
required

Can't be before date_of_birth or after today in Lagos.

​
bvn
string
required
Pattern: ^[0-9]{11}$
​
middle_name
string
Maximum string length: 200
​
mothers_maiden_name
string
Maximum string length: 200
​
next_of_kin_relationship
string
Maximum string length: 200
​
next_of_kin_address
string
Maximum string length: 200
​
nin
string
Pattern: ^[0-9]{11}$
​
tax_id
string
Maximum string length: 200

Response

This idempotency key was already used for this same application, so we didn't send anything new.

​
object
string
required
Allowed value: "application"
​
id
string
required

Unique identifier for the application. Starts with app_.

​
state
enum<string>
required

sending: stored, and the send is in progress. submitted: the broker accepted it. opened: account is the new account, and you can trade for it. uncertain: we don't know whether the broker received it. We don't send it again; we reconcile it with the broker. rejected: see reject_reason and param. refused: it never reached the broker. unplaced: we found that the broker never had it.

Available options:
sending,
submitted,
opened,
uncertain,
rejected,
refused,
unplaced
​
reference
string | null
required

The broker's reference for the application, once the broker has accepted it.

​
account
string | null
required

The account code, once the account is opened.

​
reason
string | null
required

A sentence explaining the application's current state. It's for people to read, so don't use it in your logic.

​
reject_reason
enum<string> | null
required

Why the application was rejected. Set only when state is rejected.

Available options:
invalid_field,
already_at_broker,
rejected_by_broker,
declined_by_broker,
null
​
param
string | null
required

The field that caused the rejection, when the rejection names one. Never includes the field's value.

​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required