TrustWixDocs
API reference

Verifications

List verification sessions

GET
/v1/verifications

Cursor-paginated, newest first. limit accepts 1 to 100 and defaults to 20. To walk further, set starting_after to the id of the last record on the page you just read. has_more tells you another page exists and next_cursor is the value to pass back; on the last page has_more is false and next_cursor is null. An unknown cursor is ignored and you get the first page. Requires the verification:read permission on the calling key.

Authorization

secretKey
AuthorizationBearer <token>

Secret API key, e.g. kyc_live_... (server-side) or kyc_test_... (sandbox).

In: header

Query Parameters

limit?integer

How many records to return. 1 to 100, defaults to 20.

Range1 <= value <= 100
Default20
starting_after?string

A verification id; returns the page after it.

Match^vs_
status?string

Session lifecycle. pending → processing → terminal (approved/rejected/manual_review) or expired. Roll-up: any required check reject ⇒ rejected; else any review ⇒ manual_review; else approved.

Value in

  • "pending"
  • "processing"
  • "approved"
  • "rejected"
  • "manual_review"
  • "expired"

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/verifications"
{  "object": "list",  "data": [    {      "id": "string",      "object": "verification",      "status": "pending",      "mode": "sandbox",      "flow": "string",      "verdict": "approve",      "reason_codes": [        "string"      ],      "checks": [        {          "id": "string",          "object": "check",          "type": "liveness",          "status": "pending",          "verdict": "approve",          "provider_tier": "standard",          "reason_codes": [            "string"          ],          "created_at": "2019-08-24T14:15:22Z",          "updated_at": "2019-08-24T14:15:22Z"        }      ],      "client_token": "string",      "hosted_verify_url": "http://example.com",      "locale": "string",      "metadata": {},      "expires_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "has_more": true,  "next_cursor": "string"}

Create a verification session

POST
/v1/verifications

Start a verification. Provide exactly one of flow (a saved flow id) or an inline checks array. Returns a session with a short-lived client_token and a hosted_verify_url. In sandbox mode, magic applicant inputs (approved/rejected/review/pending) force the verdict.

Requires the verification:create permission on the calling key. A key without it gets a 403. This is the one endpoint that honours Idempotency-Key.

Authorization

secretKey
AuthorizationBearer <token>

Secret API key, e.g. kyc_live_... (server-side) or kyc_test_... (sandbox).

In: header

Header Parameters

Idempotency-Key?string

Retries with the same key + body replay the original response.

Lengthlength <= 255
X-Request-Id?string

Optional client-supplied correlation id; echoed back.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Provide exactly one of flow or checks.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/verifications" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "object": "verification",  "status": "pending",  "mode": "sandbox",  "flow": "string",  "verdict": "approve",  "reason_codes": [    "string"  ],  "checks": [    {      "id": "string",      "object": "check",      "type": "liveness",      "status": "pending",      "verdict": "approve",      "provider_tier": "standard",      "reason_codes": [        "string"      ],      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "client_token": "string",  "hosted_verify_url": "http://example.com",  "locale": "string",  "metadata": {},  "expires_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Retrieve a verification session

GET
/v1/verifications/{id}

Fetch the current status, verdict and per-check results for one session. client_token is only populated on create, so it is null here. Requires the verification:read permission on the calling key.

Authorization

secretKey
AuthorizationBearer <token>

Secret API key, e.g. kyc_live_... (server-side) or kyc_test_... (sandbox).

In: header

Path Parameters

id*string

The verification session id.

Match^vs_

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/verifications/string"
{  "id": "string",  "object": "verification",  "status": "pending",  "mode": "sandbox",  "flow": "string",  "verdict": "approve",  "reason_codes": [    "string"  ],  "checks": [    {      "id": "string",      "object": "check",      "type": "liveness",      "status": "pending",      "verdict": "approve",      "provider_tier": "standard",      "reason_codes": [        "string"      ],      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "client_token": "string",  "hosted_verify_url": "http://example.com",  "locale": "string",  "metadata": {},  "expires_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Create an upload URL

POST
/v1/verifications/{id}/uploads

Step one of the two-step upload. Reserves an upload against the session and returns a short-lived presigned upload_url. PUT the raw bytes straight to that URL with the same Content-Type you declared, then call the complete endpoint. The bytes never pass through this API.

Supported content_type values are image/jpeg, image/jpg, image/png, image/webp, image/heic, image/heif, application/pdf, video/mp4, video/webm and video/quicktime. Anything else is rejected with 400 UNSUPPORTED_CONTENT_TYPE.

Requires the verification:create permission on the calling key.

Authorization

secretKey
AuthorizationBearer <token>

Secret API key, e.g. kyc_live_... (server-side) or kyc_test_... (sandbox).

In: header

Path Parameters

id*string

The verification session id.

Match^vs_

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Reserve one captured artefact against the session. side is only accepted when kind is document.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/verifications/string/uploads" \  -H "Content-Type: application/json" \  -d '{    "kind": "document",    "content_type": "string"  }'
{  "upload_id": "string",  "key": "string",  "upload_url": "http://example.com",  "expires_in": 0}

Complete an upload

POST
/v1/verifications/{id}/uploads/{uploadId}/complete

Step two of the two-step upload. Confirms the presigned PUT finished and moves the upload from pending to uploaded. The object must already be in storage, otherwise you get 400 UPLOAD_NOT_RECEIVED. Calling it again on an already completed upload is safe and returns the same record.

Takes no request body. Requires the verification:create permission on the calling key.

Authorization

secretKey
AuthorizationBearer <token>

Secret API key, e.g. kyc_live_... (server-side) or kyc_test_... (sandbox).

In: header

Path Parameters

id*string

The verification session id.

Match^vs_
uploadId*string

The upload_id returned when the upload URL was created.

Match^(doc|bio)_

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/verifications/string/uploads/string/complete"
{  "upload_id": "string",  "object": "upload",  "kind": "document",  "side": "front",  "status": "pending",  "created_at": "2019-08-24T14:15:22Z"}

About the API

Base URL, conventions and the stability promise behind every endpoint

Flows

Next Page