Skip to main content
An account’s identity is carried by its people: the representative, and any owners or directors. You submit a person’s details and their ID document, and a reviewer verifies them. This guide creates and reads the representative, attaches an ID, and reads the outcome, all through the persons subresource of the account. There is no separate identity endpoint or hosted verification session to drive. A person is created, given an ID document, and verified on review, and you learn the result from the account’s requirements and a webhook.

​
Before you start

  • An account. See Create an account.
  • An API key with connected_accounts:read and connected_accounts:write.

​
Steps

1

Read the people already on the account

A returning account holder should confirm rather than re-type. List the account’s people and find the one whose relationship.representative is true. An empty list means no representative has been created yet.
verification.status is the person’s own state: pending until a reviewer decides, then passed or failed. id_number_provided and document_provided tell you what has been supplied without echoing the number or the file. Read one person on its own at GET /v1/accounts/{account_id}/persons/{person_id}.
2

Create or update the representative

Submit the person and flag them as the representative. Identifiers go in id_numbers, each naming its own scheme under type (nin, bvn, passport, a driver’s licence) and carrying its own issuing_country. The same call updates an existing person: address it by id at POST /v1/accounts/{account_id}/persons/{person_id} and only the fields you send change.
Copy the person id (per_...). One human can hold several roles at once: a founder is commonly representative, owner and director, so relationship is a set of flags rather than separate people.
3

Upload the ID document

A document is a file plus a reference to it. Upload the file first, then attach it, so a mis-filed document is re-attached rather than re-uploaded and one file can satisfy two slots without being sent twice.
Request
Response
The upload returns an upload_id and nothing about a person yet. See Upstream for the upload’s full field reference. The file is not readable back through your API key: an attached ID is retrievable only through the admin review surface.
4

Attach the document to the person

Point one of the person’s document slots at the uploaded file. document is primary_verification for a government ID or secondary_verification for address evidence. A two-sided card is two files, each attached with its own side.
The person’s verification.document_provided is now true. Attaching a document does not verify it: a reviewer accepting it is what moves verification.status to passed.
5

Read the outcome

A person’s identity state lives on the person and on the account’s requirements, not a separate status resource. Re-read the person for its own state, or read the account for the whole picture at once.
For the account-wide view, read GET /v1/accounts/{account_id}: its requirements.entries[] show which identity fields are still owed, and persons[] carries each person’s verification block. See Requirements.

​
What happens next

A verified representative satisfies the identity fields on the account’s requirements. Watch requirements.entries[] move, and wait for capability.updated before unlocking anything: a person passing is not the same as a capability being enabled. See Monitor onboarding.

​
Next steps