Onboarding moves a signed-in user through KYC/KYB, a risk check, legal agreements, and account creation until they become a customer. You create an application, then poll its status and show 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

  1. Create an application once with POST /v1/applications, passing isCompany to pick the individual or company flow.
  2. Poll GET /v1/applications and read status.currentStep. The reference app polls about once a second.
  3. Show the screen for that step. Some steps need input from the user (a form, the Sumsub check, accepting terms); others just wait while we process. The step advances on the next poll once the work is done.
  4. When currentStep is null, 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 /v1/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: null 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 you don’t hard-code the sequence. Render whatever currentStep comes back, and treat values you don’t handle as “keep polling”, since new sub-states get added over time.

​
Steps

currentStepMeaningWhat to do
KYC_INTERNALOur own KYC form.Get the schema, render it, submit the answers.
KYC_SUMSUBSumsub identity check.Get a Sumsub token and run the SDK.
RISK_IN_PROGRESSRisk check running.Show a loader and keep polling.
RISK_COMPLIANCE_REVIEWAwaiting backoffice compliance review.Show a read-only “in review” screen and keep polling.
RISK_COMPLIANCE_REVIEW_RFICompliance requested information from the program.Show a read-only “in review” screen and keep polling. Program owners see the RFI reason in backoffice CSV reports.
RISK_COMPLIANCE_REJECTEDRisk compliance rejected (terminal).Show a contact-support screen and stop polling.
LEGAL_AGREEMENTSTerms to accept.Accept the agreements.
HOLDER_CREATION_IN_PROGRESS / ACCOUNT_CREATION_IN_PROGRESSAccount being created.Show a loader and keep polling.
nullFinished.Send the user into the app.

​
Waiting and failure states

Other values are review or failure states. Render the matching screen:
currentStepMeaningWhat to do
KYC_INTERNAL_PARTIAL_DATA / KYC_INTERNAL_VALIDATION_ERRORSThe form needs more or corrected input.Re-render it with the errors.
KYC_SUMSUB_AWAITING_PROVIDER_APPROVAL / KYC_SUMSUB_KYC_VERIFICATIONSubmitted to Sumsub, waiting on the result.Show a loader and keep polling.
KYC_INTERNAL_COMPLIANCE_REVIEW / KYC_SUMSUB_COMPLIANCE_REVIEWManual review.Show a read-only “in review” screen.
KYC_DECLINED / KYC_FAILED / KYC_ERROR / ACCOUNT_CREATION_FAILEDFailed.Show the matching error screen and stop polling.

​
Companies (KYB)

Create the application with isCompany: true and the flow is the same, except the KYC steps become KYB steps: KYB_INTERNAL and KYB_SUMSUB in place of KYC_INTERNAL and KYC_SUMSUB. 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. One extra waiting state can show up:
currentStepMeaningWhat to do
KYB_INTERNAL_AWAITING_UBOSWaiting on the company’s beneficial owners to verify.Show an “awaiting UBOs” screen and keep polling.

​
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