Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nxos.io/llms.txt

Use this file to discover all available pages before exploring further.

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 two endpoints that drive that flow: Both 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.

​
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