Skip to main content
API docs by Redocly

KYC Document API (3.0)

Download OpenAPI specification:Download

Terms of Service

The KYC Document API is organized around REST with predictable resource-oriented URLs, standard HTTP response codes, authentication, and verbs. It provides endpoints for authorization, transaction creation, document upload, verification, and retrieval of results.

Biometric notice (e.g., BIPA): Some US states regulate the collection and use of biometric identifiers and information, including facial scan data extracted from photos used in document verification. Customers must implement a notice and consent mechanism and confirm via API that the individual has consented as prescribed. Consult legal counsel for compliance.

For service-specific terms, see: https://www.trulioo.com/legal/SST

Authorization

Obtain access tokens for subsequent endpoints.

Obtain OAuth2 access token (client credentials)

Obtain a Bearer access token using OAuth2 client credentials.

Request Body schema: application/x-www-form-urlencoded
grant_type
required
string
Value: "client_credentials"
client_id
required
string
client_secret
required
string
scope
required
string

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "scope": "docv.api.us"
}

Transaction

Create transactions, upload documents, verify, and fetch results.

Create a short code for SDK handoff

Generates a single-use short code (valid for 5 minutes) to continue the verification flow in an SDK. The short code locks the workflow to the same transaction identifier that was generated during authorization.

Authorizations:
AccessToken
header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Responses

Response samples

Content type
application/json
{
  • "shortCode": "qWinHpfejeezSqek"
}

Create and configure a transaction

Creates a transaction with configuration options for document verification, selfie liveness verification, biometric verification, and optional SDK configuration for client-side capture.

Authorizations:
AccessToken
header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Request Body schema: application/json
object (DocumentVerificationConfig)

Document verification configuration.

object (SelfieVerificationConfig)

Selfie liveness verification configuration.

Array of objects (MatcherConfig)
object (SubjectInfo)

Customer Input Personal Identification Information.

Array of objects (SubjectInfo)
object (BiometricVerificationConfig)

Biometric verification configuration.

object (SDK)

SDK configuration for client-side capture and UI settings.

webhookUrl
string <uri>

Callback URL for webhook notifications

clientId
string <= 150 characters

Optional client identifier, max length 150 characters

object (DocumentLivenessConfig)

Configuration for document liveness checks.

Responses

Request samples

Content type
application/json
{
  • "documentVerification": {
    },
  • "selfieVerification": {
    },
  • "matcherConfigs": [
    ],
  • "subjectInfo": {
    },
  • "subjectInfoList": [
    ],
  • "biometricVerification": {
    },
  • "sdk": {
    },
  • "webhookUrl": "http://example.com",
  • "clientId": "string",
  • "documentLivenessConfig": {
    }
}

Response samples

Content type
application/json
{
  • "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc"
}

Upload a document or selfie image

Upload file(s) for a verification process. Accepts:

  • Images: JPEG (image/jpeg), PNG (image/png)
  • PDF: (application/pdf) Maximum file size: 10 MB. Minimum: 20 KB.
Authorizations:
AccessToken
header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Request Body schema: multipart/form-data
context
required
string
Default: "front"
Enum: "front" "back" "live" "pdf"

front or back for document images, live for selfie, or pdf for PDF uploads.

body
required
string <binary>

The file to upload. Accepts image/jpeg, image/png, or application/pdf.

Responses

Response samples

Content type
application/json
{
  • "imageId": "bbefe473-c66a-4040-85cf-1c7e6f0b3830"
}

Start verification for the current transaction

Starts the verification process and returns the status.

Authorizations:
AccessToken
header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Responses

Response samples

Content type
application/json
{
  • "status": "ACCEPTED"
}

Get transaction data

Retrieves detailed information for a verification process by transaction identifier.

Authorizations:
AccessToken
path Parameters
transactionId
required
string <uuid>
header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Responses

Response samples

Content type
application/json
{
  • "transactionId": "28087e85-9c6c-4ce9-83e2-1fb3d66b8cde",
  • "clientId": "8005efed-e683-40ab-a803-56eba164b767",
  • "timeOfTransaction": "2023-01-01T16:00:00Z",
  • "status": "REVIEW",
  • "errors": [
    ],
  • "indicators": [
    ],
  • "person": {
    },
  • "document": {
    },
  • "images": {},
  • "matcherResults": [
    ],
  • "biometricVerification": {
    },
  • "uniquePersonIdentifier": "ede60aad-b484-484c-8f31-9c51e55efe67",
  • "networkInsight": [
    ]
}

KnownFaces

Manage known faces list and transactions.

Create a new KnownFaces list

Creates a new KnownFaces list

Authorizations:
AccessToken
header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Request Body schema: application/json
listName
required
string <= 32 characters

The list name (max 32 characters, alphanumeric, -, _, and space only. No duplicate entries)

Responses

Request samples

Content type
application/json
{
  • "listName": "string"
}

Response samples

Content type
application/json
{
  • "listId": "9fc6ad7d-902a-4834-b161-a4911b883d44",
  • "listName": "string"
}

List all KnownFaces list

Lists all KnownFaces list

Authorizations:
AccessToken
header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all transactions tagged to the specified list

Lists all transactions under a list

Authorizations:
AccessToken
path Parameters
listId
required
string
header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Responses

Response samples

Content type
application/json
{
  • "listId": "9fc6ad7d-902a-4834-b161-a4911b883d44",
  • "listName": "string",
  • "transactionIds": [
    ]
}

Delete a KnownFaces list

Authorizations:
AccessToken
path Parameters
listId
required
string
header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Responses

Response samples

Content type
application/json
{
  • "code": "FACE_IMAGE_MISSING",
  • "message": "Face image missing. Make sure the selfie image is available.",
  • "details": { }
}

Add transactions to a list

Authorizations:
AccessToken
path Parameters
listId
required
string <uuid>

UUID of the list

header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Request Body schema: application/json
transactionIds
Array of strings <uuid> <= 5000 items

Transaction Ids to be added to the list (max 5000 transactions per list)

Responses

Request samples

Content type
application/json
{
  • "transactionIds": [
    ]
}

Response samples

Content type
application/json
{
  • "failedTransactions": [
    ]
}

Delete a transaction from a list

Authorizations:
AccessToken
path Parameters
listId
required
string <uuid>

UUID of the list

transactionId
required
string <uuid>

UUID of the transaction

header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Responses

Response samples

Content type
application/json
{
  • "code": "FACE_IMAGE_MISSING",
  • "message": "Face image missing. Make sure the selfie image is available.",
  • "details": { }
}

Update list metadata

Authorizations:
AccessToken
path Parameters
listId
required
string <uuid>

UUID of the list

header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Enrolment

Upload a selfie

Submit one or more selfies in Base64 encoding for enrolment. It accepts images in PNG, WEBP, and JPG formats.

Authorizations:
AccessToken
header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Request Body schema: application/json
selfies
Array of strings <= 3 items

List of strings, which are images in Base64 encoding. Only one is read for now, but multiple image input will be allowed in the future.

Responses

Request samples

Content type
application/json
{
  • "selfies": [
    ]
}

Response samples

Content type
application/json
{
  • "uniquePersonIdentifier": "e5ac7bc7-4155-4500-b6db-7ed110c75a12",
  • "externalUniquePersonIdentifier": "string",
  • "enrolmentResults": {
    }
}

Upload a selfie with external unique person identifier

Submit one or more selfies in Base64 encoding for enrolment, attaching a unique identifier with context in a system external to Trulioo. It accepts images in PNG and JPG format and PDF files.

Authorizations:
AccessToken
path Parameters
externalUniquePersonIdentifier
required
string
header Parameters
Accept-Version
required
string
Example: 3.0

API version header.

Request Body schema: application/json
selfies
Array of strings <= 3 items

List of strings, which are images in Base64 encoding. Only one is read for now, but multiple image input will be allowed in the future.

Responses

Request samples

Content type
application/json
{
  • "selfies": [
    ]
}

Response samples

Content type
application/json
{
  • "uniquePersonIdentifier": "e5ac7bc7-4155-4500-b6db-7ed110c75a12",
  • "externalUniquePersonIdentifier": "string",
  • "enrolmentResults": {
    }
}

Enrol selfie from an old transaction

Enrol selfie image that is available from old transaction

Authorizations:
AccessToken
path Parameters
transactionId
required
string <uuid>

UUID of the transaction

Responses

Response samples

Content type
application/json
{
  • "uniquePersonIdentifier": "e5ac7bc7-4155-4500-b6db-7ed110c75a12",
  • "externalUniquePersonIdentifier": "string",
  • "enrolmentResults": {
    }
}