Verification: bringing an org through KYB

Every organization on nxos must complete identity verification (KYB for businesses, KYC for individuals) before it can hold balances, send payouts, or back an active Letter of Authorization. This guide covers the endpoints that drive that flow:

GET /v1/organizations/verification: read the current status.
POST /v1/organizations/verification: start (or refresh) a verification session.
POST /v1/organizations/verification/import: import an existing verification from a partner Sumsub tenant (Reusable KYC, INDIVIDUAL orgs only).

All three endpoints accept the Nxos-On-Behalf-Of header, so a broker can run verification on behalf of a customer org. The flow is identical whether you’re verifying your own org or a customer org. The only difference is which org id the request targets. In broker flows, the customer’s Letter of Authorization is signed in the same session as their verification submission. The LOA becomes effective once both the signature is captured and the verification reaches APPROVED. See Cross-org access for what the LOA enables.

Prerequisites

An API key for the organization you’re verifying, or a broker API key plus a PENDING Letter of Authorization (see Cross-org access).
For brokers, the customer org must already exist (created via POST /v1/organizations).

Flow overview

Start session → Customer completes Sumsub → Status polls APPROVED

Call POST /v1/organizations/verification to start a session. The response carries a url (Sumsub-hosted page) and an accessToken (for the Sumsub WebSDK).
Hand off the customer to one of the two delivery options below.
Poll GET /v1/organizations/verification until status is APPROVED, REJECTED, or RESUBMISSION_REQUIRED.

The platform stores verification state by externalUserId = organizationId. Calling POST multiple times returns a new short-lived token for the same applicant. It does not start over.

Step 1: Start a session

curl -X POST https://api.sandbox.nxos.io/v1/organizations/verification \
  -H "Authorization: Bearer nxos_sk_test_..." \
  -H "Nxos-On-Behalf-Of: org_cust1234567890abcdef1234567890abcd"

{
  "object": "verification_session",
  "url": "https://in.sumsub.com/idensic/l/#/sbx_...",
  "accessToken": "_act-sbx-jwt-..."
}

Tokens are short-lived (around 30 minutes). Generate a fresh one whenever you’re about to hand off to the customer rather than caching across sessions.

Step 2: Hand off to the customer

You have two delivery options. Pick one based on how much UI control you need.

Option A: Hosted URL

Share the url with the customer (email link, dashboard redirect, SMS, in-app prompt). The customer completes the entire flow on a Sumsub-hosted page. No SDK integration on your side. This is the simplest path and works well for brokers who don’t want to host the verification UI.

<a href="https://in.sumsub.com/idensic/l/#/sbx_..." target="_blank">
  Verify your business
</a>

The customer uploads documents, takes selfies if required, and submits. Sumsub closes the session and reports the result back to nxos via webhook. There is no callback to your application directly. You poll GET /v1/organizations/verification to learn the outcome.

Option B: Embedded WebSDK

If you’d rather render the flow inside your own UI, pass the accessToken to the Sumsub WebSDK. The token authorizes the SDK to communicate with Sumsub on the applicant’s behalf.

<script src="https://static.sumsub.com/idensic/static/sns-websdk-builder.js"></script>
<div id="sumsub-websdk-container"></div>
<script>
  const snsWebSdkInstance = snsWebSdk
    .init(
      "_act-sbx-jwt-...",                          // accessToken from POST response
      () => fetchFreshTokenFromYourBackend()        // refresh handler
    )
    .withConf({ lang: "en" })
    .build()
    .launch("#sumsub-websdk-container");
</script>

The refresh handler is important. Tokens expire mid-session if the customer takes longer than 30 minutes. Your handler should call POST /v1/organizations/verification again for the same org and return the new accessToken. The SDK swaps it in without restarting the flow. See Sumsub’s WebSDK docs for full integration details. The token format and refresh callback shape are theirs.

Step 3: Poll for the result

curl https://api.sandbox.nxos.io/v1/organizations/verification \
  -H "Authorization: Bearer nxos_sk_test_..." \
  -H "Nxos-On-Behalf-Of: org_cust1234567890abcdef1234567890abcd"

{
  "object": "organization_verification",
  "status": "APPROVED",
  "type": "BUSINESS",
  "updatedAt": "2026-05-15T14:30:00.000Z"
}

Reasonable poll cadence is once every 10 to 30 seconds while the customer is mid-flow, then back off to once a minute. Customers usually finish in a few minutes; expect occasional pauses when manual review is required, which can stretch to hours or a business day.

Importing from a partner tenant (advanced)

If you already verified a natural person on your own Sumsub tenant and would rather not send them through the flow again, you can import that existing verification directly with POST /v1/organizations/verification/import. This is Sumsub’s Reusable KYC path: a share token generated on your tenant is exchanged for a linked applicant on ours. This is limited to INDIVIDUAL orgs. Sumsub’s Reusable KYC product covers natural persons only; calling the import endpoint for a BUSINESS org returns 400 verification_import_unsupported. For BUSINESS, keep using the standard flow above.

Prerequisites

Reusable KYC enabled on both Sumsub tenants — yours (donor) and ours (recipient).
nxos added as a sharing partner in your Sumsub dashboard (Reusable Identity → Partners).
The customer org already exists on nxos (POST /v1/organizations).
An ACTIVE LOA on the customer org. See Cross-org access.

Flow

Your Sumsub tenant: generate share token (forClientId = nxos client id, single-use)
        │
        ▼
POST /v1/organizations/verification/import
  Nxos-On-Behalf-Of: <customer-org-id>
  { "shareToken": "..." }
        │
        ▼
nxos returns 200 with status = PENDING
        │
        ▼
Sumsub fires applicantReviewed on our tenant within seconds → APPROVED

curl -X POST https://api.sandbox.nxos.io/v1/organizations/verification/import \
  -H "Authorization: Bearer nxos_sk_test_brkr..." \
  -H "Nxos-On-Behalf-Of: org_cust1234567890abcdef1234567890abcd" \
  -H "Content-Type: application/json" \
  -d '{ "shareToken": "_act-sbx-jwt-..." }'

{
  "object": "organization_verification",
  "status": "PENDING",
  "type": "INDIVIDUAL",
  "updatedAt": "2026-05-15T14:30:00.000Z"
}

Same shape as GET /v1/organizations/verification. Poll that endpoint for the transition to APPROVED — usually a few seconds later, once Sumsub fires applicantReviewed on our side.

What to know

Single-use tokens. Sumsub invalidates the share token the moment we consume it. A retry returns 400 share_token_invalid. Generate a fresh token per call.
No synchronous APPROVED. We return PENDING even when the donor applicant was already green. The applicantReviewed webhook drives the final transition. This keeps a single code path for approvals and preserves traceability.
Idempotent in practice. If the customer’s verification is already APPROVED or ON_HOLD, the import is a no-op for your record — the linked Sumsub applicant is still created on our side for audit, but no status change happens.
Org type is fixed at creation. The org’s type is set when you call POST /v1/organizations; the import endpoint reads it back. There’s no way to import a KYC into a BUSINESS org or vice versa.

Possible 4xx responses

Code	Meaning	Fix
`share_token_invalid`	Sumsub rejected the token: unknown, expired, already used, or the donor tenant is not paired with us.	Generate a fresh token. Confirm Reusable KYC is enabled on both tenants and that nxos is in your partner list.
`verification_import_unsupported`	The target org is `BUSINESS`. Reusable KYC covers natural persons only.	Use the standard flow (`POST /v1/organizations/verification`).
`authorization_required`	No currently effective LOA between you and the target org (unsigned, revoked, or the customer’s KYB has lapsed).	See Cross-org access.
`organization_not_found`	The org id in `Nxos-On-Behalf-Of` doesn’t exist.	Check the id.

Status lifecycle

Status	Meaning	What you do
`NOT_STARTED`	The org has a verification record but no session has been opened.	Call `POST` to start one.
`PENDING`	Session started; awaiting customer action or Sumsub review.	Poll.
`APPROVED`	Verified. The org can transact, hold balances, and back active LOAs.	Done.
`REJECTED`	Sumsub or compliance ops declined the application.	Terminal in this flow. Customer cannot re-submit through the same path; contact support if you believe this is in error.
`ON_HOLD`	Pending manual compliance review on our side.	Poll. Resolution can take a business day.
`RESUBMISSION_REQUIRED`	Sumsub flagged a fixable problem (blurry document, wrong document type, etc.).	Call `POST` again to get a fresh token, hand the customer back into the flow. The session resumes at the failing step.

What a broker can act on, and when

A Letter of Authorization can be signed at any time, including before the customer’s verification completes. But the LOA is only effective for Nxos-On-Behalf-Of calls while the granter’s verification status is APPROVED. See Cross-org access for the full gating rule. In practice this means brokers can run two flows in parallel:

Send the customer an LOA to sign (dashboard / e-signing).
Call POST /v1/organizations/verification to start their KYB.

Once both complete, calls with Nxos-On-Behalf-Of begin working. If verification later lapses (e.g. expiresAt passes, or the customer needs to re-verify), the LOA is suspended automatically until the verification returns to APPROVED. No action on the LOA itself.

Summary

Step	Endpoint	What happens
Start	`POST /v1/organizations/verification`	Creates a Sumsub applicant for the org, returns a session URL and access token
Check	`GET /v1/organizations/verification`	Returns current status, type, and last-updated timestamp
Resubmit	`POST /v1/organizations/verification`	Mints a fresh token for the same applicant; flow resumes at the failing step
Import (advanced, `INDIVIDUAL` only)	`POST /v1/organizations/verification/import`	Consumes a partner Sumsub share token, links the applicant on our tenant, moves the org to `PENDING`

Authentication: API keys
Cross-org access: how LOAs and KYB interact

Getting started

Core concepts

Guides

Verification: bringing an org through KYB

Prerequisites

Flow overview

Step 1: Start a session

Step 2: Hand off to the customer

Option A: Hosted URL

Option B: Embedded WebSDK

Step 3: Poll for the result

Importing from a partner tenant (advanced)

Prerequisites

Flow

What to know

Possible 4xx responses

Status lifecycle

What a broker can act on, and when

Summary

​Prerequisites

​Flow overview

​Step 1: Start a session

​Step 2: Hand off to the customer

​Option A: Hosted URL

​Option B: Embedded WebSDK

​Step 3: Poll for the result

​Importing from a partner tenant (advanced)

​Prerequisites

​Flow

​What to know

​Possible 4xx responses

​Status lifecycle

​What a broker can act on, and when

​Summary

​Related

Prerequisites

Flow overview

Step 1: Start a session

Step 2: Hand off to the customer

Option A: Hosted URL

Option B: Embedded WebSDK

Step 3: Poll for the result

Importing from a partner tenant (advanced)

Prerequisites

Flow

What to know

Possible 4xx responses

Status lifecycle

What a broker can act on, and when

Summary

Related