Skip to main content
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: 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
  1. Call POST /v1/organizations/verification to start a session. The response carries a url (Sumsub-hosted page) and an accessToken (for the Sumsub WebSDK).
  2. Hand off the customer to one of the two delivery options below.
  3. 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

CodeMeaningFix
share_token_invalidSumsub 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_unsupportedThe target org is BUSINESS. Reusable KYC covers natural persons only.Use the standard flow (POST /v1/organizations/verification).
authorization_requiredNo currently effective LOA between you and the target org (unsigned, revoked, or the customer’s KYB has lapsed).See Cross-org access.
organization_not_foundThe org id in Nxos-On-Behalf-Of doesn’t exist.Check the id.

​
Status lifecycle

StatusMeaningWhat you do
NOT_STARTEDThe org has a verification record but no session has been opened.Call POST to start one.
PENDINGSession started; awaiting customer action or Sumsub review.Poll.
APPROVEDVerified. The org can transact, hold balances, and back active LOAs.Done.
REJECTEDSumsub 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_HOLDPending manual compliance review on our side.Poll. Resolution can take a business day.
RESUBMISSION_REQUIREDSumsub 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:
  1. Send the customer an LOA to sign (dashboard / e-signing).
  2. 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

StepEndpointWhat happens
StartPOST /v1/organizations/verificationCreates a Sumsub applicant for the org, returns a session URL and access token
CheckGET /v1/organizations/verificationReturns current status, type, and last-updated timestamp
ResubmitPOST /v1/organizations/verificationMints a fresh token for the same applicant; flow resumes at the failing step
Import (advanced, INDIVIDUAL only)POST /v1/organizations/verification/importConsumes a partner Sumsub share token, links the applicant on our tenant, moves the org to PENDING