> ## 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.

# Verification: bringing an org through KYB

> Start, check, and complete an organization's verification flow using Sumsub-backed sessions.

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`](/api-reference/organizations/get-verification): read the current status.
* [`POST /v1/organizations/verification`](/api-reference/organizations/start-verification): start (or refresh) a verification session.
* [`POST /v1/organizations/verification/import`](/api-reference/organizations/import-verification): 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](/guides/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](/guides/cross-org-access)).
* For brokers, the customer org must already exist (created via [`POST /v1/organizations`](/api-reference/organizations/create)).

## Flow overview

```
Start session → Customer completes Sumsub → Status polls APPROVED
```

1. Call [`POST /v1/organizations/verification`](/api-reference/organizations/start-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`](/api-reference/organizations/get-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

```bash theme={null}
curl -X POST https://api.sandbox.nxos.io/v1/organizations/verification \
  -H "Authorization: Bearer nxos_sk_test_..." \
  -H "Nxos-On-Behalf-Of: org_cust1234567890abcdef1234567890abcd"
```

```json theme={null}
{
  "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.

```html theme={null}
<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.

```html theme={null}
<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`](/api-reference/organizations/start-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

```bash theme={null}
curl https://api.sandbox.nxos.io/v1/organizations/verification \
  -H "Authorization: Bearer nxos_sk_test_..." \
  -H "Nxos-On-Behalf-Of: org_cust1234567890abcdef1234567890abcd"
```

```json theme={null}
{
  "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`](/api-reference/organizations/import-verification). 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`](/api-reference/organizations/create)).
* An `ACTIVE` LOA on the customer org. See [Cross-org access](/guides/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
```

```bash theme={null}
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-..." }'
```

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

Same shape as [`GET /v1/organizations/verification`](/api-reference/organizations/get-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`](/api-reference/organizations/create); 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`](/api-reference/organizations/start-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](/guides/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](/guides/cross-org-access#kyb-gating) 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`](/api-reference/organizations/start-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`](/api-reference/organizations/start-verification)         | Creates a Sumsub applicant for the org, returns a session URL and access token                       |
| Check                                | [`GET /v1/organizations/verification`](/api-reference/organizations/get-verification)            | Returns current status, type, and last-updated timestamp                                             |
| Resubmit                             | [`POST /v1/organizations/verification`](/api-reference/organizations/start-verification)         | Mints a fresh token for the same applicant; flow resumes at the failing step                         |
| Import (advanced, `INDIVIDUAL` only) | [`POST /v1/organizations/verification/import`](/api-reference/organizations/import-verification) | Consumes a partner Sumsub share token, links the applicant on our tenant, moves the org to `PENDING` |

## Related

* [Authentication](/concepts/authentication): API keys
* [Cross-org access](/guides/cross-org-access): how LOAs and KYB interact