Sign in
latestOpenAPI 3.1.02026-08-153864115.7 MB

c301132dbfd7

Verifications

Create Verification

Starts a hosted verification session for an account or user, or returns the active session when one already exists. Any fields you include in the request body are used to prefill the session. Send documents (with document_type) to instead verify the person from identity documents included in this request — no hosted session involved. Send share_token to reuse a verification another Sumsub account has already completed for this person, instead of verifying them again. If the account already has an approved verification the request is rejected; unlink it first to start a new one.

post/verifications

Query parameters

account_idstring required

Account or user ID whose identity you want to verify. Use a biz_ account ID for account verifications, or the caller's user_ ID for personal verification.

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

A unique key that makes this request safe to retry. See Idempotent requests.

Request body

OR

Example request

{
  "address": {
    "city": "Austin",
    "country": "US",
    "line1": "4180 Burnet Rd",
    "line2": "Suite 2",
    "postal_code": "78756",
    "state": "TX"
  },
  "business_name": "Shine Time Auto Detailing LLC",
  "business_structure": "private_corporation",
  "business_tax_identification_number": "12-3456789",
  "business_website": "https://shinetime.example",
  "country": "US",
  "date_of_birth": "2026-01-01",
  "document_type": "RESIDENCE_PERMIT",
  "documents": {
    "drivers_back": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    "drivers_front": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    "id_card_back": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    "id_card_front": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    "passport_front": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    "residence_permit_back": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    "residence_permit_front": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    "selfie": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx="
  },
  "first_name": "Marcus",
  "kind": "individual",
  "last_name": "Webb",
  "phone": "+xxxxxxxxxxx",
  "share_token": "_act-sbx-jwt-eyJhbGciOiJub25l",
  "tax_identification_number": "123456789"
}

Response

OK

business_namestring nullable

Legal business name.

business_structurestring nullable

Legal entity structure of the business, such as private_corporation or sole_proprietorship. Supported values vary by country of incorporation — see Business structures.

countrystring nullable

Two-letter ISO 3166-1 country code, for example US, DE, or GB.

created_atstring

When the verification profile was created, as an ISO 8601 timestamp.

date_of_birthstring nullable

Formatted as YYYY-MM-DD.

emailstring nullable

Email address on the verification profile.

first_namestring nullable
idstring

Verification profile ID, prefixed idpf_.

kind'individual' | 'business'
last_namestring nullable
phonestring nullable

Phone number on the verification profile.

session_urlstring nullable

Hosted verification session URL for the user to complete identity checks. Expires 7 days after creation.

status'not_started' | 'pending' | 'processing' | 'manual_review' | 'approved' | 'rejected' | 'action_required'

Current verification state. not_started before any session exists; pending while a session needs the user's input; processing while the provider's automated checks run on a fresh submission; action_required when requested_information needs answers; manual_review while information already sent is under review — an audit answer, or a document the payout provider holds — nothing to submit, usually done within 3 business days; approved on success; rejected on failure. Call Create Verification again to start a new session.

updated_atstring

When the verification profile was last updated, as an ISO 8601 timestamp.

Example response

{
  "address": {
    "city": "Austin",
    "country": "US",
    "line1": "4180 Burnet Rd",
    "line2": "Suite 2",
    "postal_code": "78756",
    "state": "TX"
  },
  "business_name": "Shine Time Auto Detailing, LLC",
  "business_structure": "sole_proprietorship",
  "country": "US",
  "created_at": "2026-06-01T12:00:00.000Z",
  "date_of_birth": "1990-01-01",
  "email": "marcus@shinetime.example",
  "first_name": "Marcus",
  "id": "idpf_xxxxxxxxxxxx",
  "kind": "individual",
  "last_name": "Webb",
  "phone": "+15551234567",
  "requested_information": [
    {
      "errors": [
        {
          "code": "document_not_readable",
          "reason": "The uploaded image was too blurry to read."
        }
      ],
      "id": "inrqi_xxxxxxxxxxx",
      "label": "Bank Statement or a check for account ending in 4242",
      "optional": true,
      "options": [
        "sole_proprietorship"
      ],
      "requirement": "bank_statement",
      "type": "files"
    }
  ],
  "required_documents": [
    {
      "document": "id_card_front",
      "rejection_reason": "Document image was too blurry to read.",
      "status": "submitted"
    }
  ],
  "session_url": "https://sumsub.com/session/abc",
  "status": "action_required",
  "updated_at": "2026-06-02T12:00:00.000Z"
}