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 through the persons subresource of the account, and we check them. How a person is checked depends on what the account does:
  • Paid out, holding money, or a virtual account. We check the details you send. In Nigeria, the BVN is checked against the national register. No selfie, no ID document.
  • Taking payments. The person does a selfie video check of their face and ID, on their phone. You cannot do it for them through the API: send them a hosted link. See The selfie video check.
This guide creates and reads the representative, attaches an ID document where one is still asked for, and reads the outcome. 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: unverified until a decision is made, then verified or failed. It reads not_required when nothing the account asked for needs this person’s identity checked. See Read the outcome. 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

Do this only when the account’s requirements ask for persons.<id>.id_document. A person who does the selfie video check does not usually need a separate 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
Send X-Account-Id with the connected account’s id. A file belongs to the account it was uploaded for. If you leave the header out, the file belongs to your platform account, and the next step returns 404 NOT_FOUND with Attachment not found. Upload the file again with the header.The upload returns a file id and nothing about a person yet. See Upload a compliance file for the 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: the document passing its check is what moves verification.status to verified.
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.
An account that only receives money, such as one that gets transfers and pays out to a bank account, is asked for the person’s name and a payout destination. Its persons read not_required, even when an ID document is attached. Do not wait on verification.status to pay these accounts. Wait for capability.updated with status: "active" instead.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 live. If a selfie video check fails, requirements.errors says why, on persons.<id>.identity_check. Send the person a liveness link to try again. See Onboard with a hosted link. See Monitor onboarding.

Next steps