postStart client verification session
kyc.verifyAuthentication: Send Authorization: Bearer <access_token>.
Initiates KYC/KYB onboarding for an End Client owned by the caller enterprise. Returns an embeddable WebSDK access token, a provider-hosted verification link, and the resolved stage flow. legal_form is required for company onboarding in legal-form jurisdictions (AR).
Parameters
| Name | Location | Type | Required | Description and constraints |
|---|---|---|---|---|
client_id |
path | string | Yes | format: uuid |
Request
Required request body.
Request body schema
| Field | Type | Required | Description and constraints |
|---|---|---|---|
applicant_type |
"individual" / "company" | Yes | |
country |
string | Yes | minLength: 2; maxLength: 2 |
legal_form |
"SA" / "SRL" / "SAS" / "SH" / "CH1_SEC_IV" / "ASSOC_FOUND" / "COOP" / "SCS" / "SCA" / "TRUST" | No |
Additional fields are not accepted.
Request URL
POST /kyc/clients/{client_id}/sessionsRequest Body
{
"applicant_type": "company",
"country": "AR",
"legal_form": "SA"
}Responses
Response
{
"access_token": "_act-sbx-jwt-eyJhbGciOiJub25lIn0...",
"external_user_id": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"flow": {
"jurisdiction": "AR",
"legal_form_required": false,
"legal_form_supported": true,
"stages": [
{
"id": "company"
}
]
},
"verification_link": "https://in.sumsub.com/websdk/p/sbx_AbCdEf123456"
}Operation succeeded.
Response 200 schema
Content type: application/json.
application/json body
| Field | Type | Required | Description and constraints |
|---|---|---|---|
access_token |
string | Yes | minLength: 1 |
external_user_id |
string | Yes | minLength: 1; maxLength: 255 |
flow |
object | Yes | No additional fields |
verification_link |
string | Yes | minLength: 1; maxLength: 2048 |
Additional fields are not accepted.
application/json body.flow
| Field | Type | Required | Description and constraints |
|---|---|---|---|
jurisdiction |
string or null | Yes | |
legal_form_required |
boolean | Yes | |
legal_form_supported |
boolean | Yes | |
stages |
object[] | Yes |
Additional fields are not accepted.
application/json body.flow.jurisdiction
At least one alternative must match.
application/json body.flow.jurisdiction: alternative 1
Type: string.
application/json body.flow.jurisdiction: alternative 2
Type: null.
application/json body.flow.stages
Type: object[].
application/json body.flow.stages item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
id |
"identity" / "company" / "signatories" / "form_k" | Yes |
Additional fields are not accepted.
| Response header | Type | Description |
|---|---|---|
Cache-Control |
"no-store" |
Response 400 schema
Content type: application/json.
application/json body
| Field | Type | Required | Description and constraints |
|---|---|---|---|
code |
string | Yes | |
data |
object | No | No additional fields |
details |
object | No | Additional fields allowed |
message |
string | Yes |
Additional fields are not accepted.
application/json body.data
| Field | Type | Required | Description and constraints |
|---|---|---|---|
acr_values |
string | No | RFC 9470 step-up challenge (insufficient_user_authentication). |
blockers |
object[] | No | For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition. |
code |
string | No | For legal refusals: the document code the refusal is about. |
max_age |
string | No | RFC 9470 step-up challenge (insufficient_user_authentication). |
max_source_amount |
object | No | For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields |
min_source_amount |
object | No | For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields |
published_version |
string | No | For document_version_superseded: the version currently published. |
reason |
string | No | Typed refinement of code, from the failing service's contract. |
resource |
string | No | Resource kind a resource_not_found refers to. |
retry_after_ms |
integer | No | Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0 |
source |
string | No | For not_admissible: the gate that denied (verification, lifecycle, policy, compliance). |
Additional fields are not accepted.
application/json body.data.blockers
For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
Type: object[].
application/json body.data.blockers item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
description |
string | Yes | |
type |
"non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" | Yes | |
assets |
object[] | No | minItems: 1 |
count |
integer | No | minimum: 0; maximum: 9007199254740991 |
Additional fields are not accepted.
application/json body.data.blockers item.assets
Type: object[]. minItems: 1
application/json body.data.blockers item.assets item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
asset |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
kind |
"balance" / "held" / "owed" / "unsettled" | Yes |
Additional fields are not accepted.
application/json body.data.max_source_amount
For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | |
value |
string | Yes |
Additional fields are not accepted.
application/json body.data.min_source_amount
For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | |
value |
string | Yes |
Additional fields are not accepted.
Response 401 schema
Content type: application/json.
application/json body
| Field | Type | Required | Description and constraints |
|---|---|---|---|
code |
string | Yes | |
data |
object | No | No additional fields |
details |
object | No | Additional fields allowed |
message |
string | Yes |
Additional fields are not accepted.
application/json body.data
| Field | Type | Required | Description and constraints |
|---|---|---|---|
acr_values |
string | No | RFC 9470 step-up challenge (insufficient_user_authentication). |
blockers |
object[] | No | For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition. |
code |
string | No | For legal refusals: the document code the refusal is about. |
max_age |
string | No | RFC 9470 step-up challenge (insufficient_user_authentication). |
max_source_amount |
object or null | No | For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields |
min_source_amount |
object | No | For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields |
published_version |
string | No | For document_version_superseded: the version currently published. |
reason |
string | No | Typed refinement of code, from the failing service's contract. |
resource |
string | No | Resource kind a resource_not_found refers to. |
retry_after_ms |
integer or null | No | Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0 |
source |
string | No | For not_admissible: the gate that denied (verification, lifecycle, policy, compliance). |
Additional fields are not accepted.
application/json body.data.blockers
For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
Type: object[].
application/json body.data.blockers item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
description |
string | Yes | |
type |
"non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" | Yes | |
assets |
object[] | No | minItems: 1 |
count |
integer | No | minimum: 0; maximum: 9007199254740991 |
Additional fields are not accepted.
application/json body.data.blockers item.assets
Type: object[]. minItems: 1
application/json body.data.blockers item.assets item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
asset |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
kind |
"balance" / "held" / "owed" / "unsettled" | Yes |
Additional fields are not accepted.
application/json body.data.max_source_amount
For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | |
value |
string | Yes |
Additional fields are not accepted.
application/json body.data.min_source_amount
For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | |
value |
string | Yes |
Additional fields are not accepted.
Response 403 schema
Content type: application/json.
See response 401 schema.
Response 404 schema
Content type: application/json.
See response 401 schema.
Response 409 schema
Content type: application/json.
See response 401 schema.
Response 500 schema
Content type: application/json.
See response 401 schema.
Response 502 schema
Content type: application/json.
See response 400 schema.
Response 503 schema
Content type: application/json.
See response 400 schema.