Onboarding overview

A signed-in user becomes a customer by completing the onboarding steps their program requires. KYC or KYB is always part of it; depending on the program there may also be a risk and compliance review and legal agreements. You create one application and then poll it, showing the screen that matches the step the server reports.

Every onboarding call uses the user’s bearer token (Authorization: Bearer <access_token>) from authentication.

How it works

Create an application once with POST /v2/applications, passing isCompany to pick the individual or company flow.
Poll GET /v2/applications and read status.currentStep. The reference app polls about once a second; slow down on IN_REVIEW (see below).
Show the screen for that step. Some steps need input from the user (a form, the identity check, accepting terms); others just wait while we process. The step advances on the next poll once the work is done.
When currentStep is COMPLETED, onboarding is finished. Send the user into the app.

After approval: from application to customer

Approval turns the applicant into a customer, and that hand-off gives you everything the rest of the API needs:

The application object (from GET /v2/applications) carries the customerId — every customer-scoped endpoint takes it.
The customer’s primary account is created automatically — you don’t call anything. Fetch it with List accounts; the accountId from that response is what cards, payments, and beneficiaries hang off.

So the sequence after currentStep: "COMPLETED" is simply: read customerId from the application → GET /v1/customers/{customerId}/accounts → build the app around the returned accountId. The server decides the order, so don’t hard-code the sequence: render whatever currentStep comes back. The order depends on the program: most collect the legal agreements first, before KYC/KYB, and some collect them after the risk review. On v2 there are ten values, one per screen, and the set doesn’t grow when we add internal processing steps: those show up as PROCESSING.

Steps

Pick the tab for the version you poll. New integrations should use v2.

v2 (recommended)
v1

status.currentStep is always one of these values. status.requiredActions lists what the user must do on that screen, and is empty while you wait.Action required

`currentStep`	Meaning	What to do	`requiredActions`
`KYC_FORM`	Our KYC (or, for a company, KYB) questionnaire, including one that was partly saved or had errors.	Get the schema, render it pre-filled from `application.kycData`, submit the answers. Uploaded documents come back as `data: null` with `provided: true`: show them as uploaded, don’t ask again.	`complete-kyc-form`
`IDENTITY_VERIFICATION`	The identity check.	Get an SDK token and run the SDK. When the SDK reports the check submitted, show a loader and keep polling until `currentStep` changes.	`complete-identity-verification`
`ADD_UBOS`	The company’s beneficial owners must verify their identity.	Show the owners from `application.ubos` with their `verification` status and keep polling. To email an owner their verification link again, or reset it, pass their `uboId`s to UBO actions.	`add-ubos`
`LEGAL_AGREEMENTS`	Terms to accept.	Accept the agreements.	`accept-terms`
`PROVIDER_DOCUMENTS`	The account provider’s own documents must be signed. Only happens on programs whose provider requires it.	Contact us to set up the signing flow for your program.	`accept-provider-docs`

Waiting — keep polling

`currentStep`	Meaning	What to do
`PROCESSING`	We’re finishing a step you just completed, e.g. processing a submitted KYC or KYB form, checking identity, or recording accepted legal agreements or provider documents. Usually seconds; up to about 20 minutes for a form or a check that runs on our side.	Show a loader and keep polling.
`IN_REVIEW`	Your application is being reviewed and set up: risk and compliance checks, verification review, and creating the account. Also covers compliance asking the program for more information, and an account set-up we have to fix on our side. Can take hours or days.	Show a read-only “in review” screen. Poll every 30 seconds or so (or when the user returns), not every second. When it’s done the application moves to its next step, usually `COMPLETED`.

Finished or stopped

`currentStep`	Meaning	What to do
`COMPLETED`	Onboarding complete.	Stop polling and send the user into the app. A cardholder invited onto a corporate may still need to accept legal agreements: check `application.legalAccepted`.
`DECLINED`	The application was declined, failed verification, or was closed or blocked.	Show a contact-support screen and stop polling. `requiredActions` is `["contact-support"]`.
`ERROR`	The verification couldn’t be completed.	Show an error screen. `requiredActions` is `["contact-support"]`. Support can reset it, after which the step goes back to `KYC_FORM` or `IDENTITY_VERIFICATION`, so read the application again when the user returns rather than caching the error.

GET /v1/applications is unchanged and reports detailed internal step names rather than screens. Treat values you don’t handle as “keep polling”, since new sub-states get added over time.Action required

`currentStep`	Meaning	What to do
`KYC_INTERNAL`	Our own KYC form.	Get the schema, render it, submit the answers.
`KYC_SUMSUB`	Sumsub identity check.	Get a Sumsub token and run the SDK.
`KYC_INTERNAL_PARTIAL_DATA`	The KYC form has been partially saved.	Re-render the form with existing data so the user can complete it.
`KYC_INTERNAL_VALIDATION_ERRORS`	The KYC form has validation errors.	Re-render the form with the errors so the user can correct them.
`LEGAL_AGREEMENTS`	Terms to accept.	Accept the agreements.

Waiting — keep polling

`currentStep`	Meaning	What to do
`KYC_SUMSUB_AWAITING_PROVIDER_APPROVAL`	Submitted to Sumsub, awaiting approval.	Show a loader and keep polling.
`KYC_SUMSUB_KYC_REVIEW`	Sumsub reviewing the submission.	Show a loader and keep polling.
`KYC_SUMSUB_KYC_VERIFICATION`	Sumsub KYC verification in progress.	Show a loader and keep polling.
`KYC_INTERNAL_KYC_VERIFICATION`	Internal KYC verification in progress.	Show a loader and keep polling.
`KYC_SUMSUB_AWAITING_UBOS`	Waiting for beneficial owners to verify.	Show an “awaiting UBOs” screen and keep polling.
`KYC_INTERNAL_COMPLIANCE_REVIEW`	Internal KYC under manual compliance review.	Show a read-only “in review” screen and keep polling.
`KYC_SUMSUB_COMPLIANCE_REVIEW`	Sumsub KYC under manual compliance review.	Show a read-only “in review” screen and keep polling.
`RISK_IN_PROGRESS`	Risk scoring running.	Show a loader and keep polling.
`RISK_COMPLIANCE_REVIEW`	Awaiting compliance review.	Show a read-only “in review” screen and keep polling.
`RISK_COMPLIANCE_REVIEW_RFI`	Compliance requested information from the program.	Show a read-only “in review” screen and keep polling. Program owners see the RFI reason in management CSV reports.
`HOLDER_CREATION_IN_PROGRESS`	Holder being created.	Show a loader and keep polling.
`ACCOUNT_CREATION_IN_PROGRESS`	Account being created.	Show a loader and keep polling.

Terminal — stop polling

`currentStep`	Meaning	What to do
`CUSTOMER` or `MEMBER`	Onboarding complete.	Send the user into the app.
`KYC_FAILED`	KYC failed.	Show an error screen and stop polling.
`KYC_ERROR`	KYC error.	Show an error screen and stop polling.
`KYC_DECLINED`	KYC declined.	Show a contact-support screen and stop polling.
`KYC_UBO_FAILED`	UBO verification failed.	Show an error screen and stop polling.
`RISK_COMPLIANCE_REJECTED`	Risk compliance rejected.	Show a contact-support screen and stop polling.
`ACCOUNT_CREATION_FAILED`	Account creation failed.	Show an error screen and stop polling.

For a company, the KYC steps appear as KYB steps (KYB_INTERNAL, KYB_SUMSUB, KYB_INTERNAL_AWAITING_UBOS).

Companies (KYB)

Create the application with isCompany: true and the flow uses the same steps. On KYC_FORM you fetch the form from the same schema endpoint (it returns company and beneficial-owner fields), but you submit the answers to POST /v1/applications/kyb instead of the individual KYC endpoint. A company can also reach ADD_UBOS while its beneficial owners verify.

Get started

Guides

How it works

After approval: from application to customer

Steps

Companies (KYB)

Endpoints

Create an application

Get the current application

Get the KYC form schema

Submit KYC data

Submit KYB data

Get a Sumsub SDK token

Accept legal agreements

​How it works

​After approval: from application to customer

​Steps

​Companies (KYB)

​Endpoints

Create an application

Get the current application

Get the KYC form schema

Submit KYC data

Submit KYB data

Get a Sumsub SDK token

Accept legal agreements

How it works

After approval: from application to customer

Steps

Companies (KYB)

Endpoints