Document Verification

Manage the verification sessions that are used to securely verify the identity of your customers using documents like their driver's license or passport.

Download OpenAPI description

verifications.openapi.json

verifications.openapi.yaml

Overview

Servers

Sandbox environment

https://api.sbx.transmitsecurity.io/verify/

Production environment (US)

https://api.transmitsecurity.io/verify/

Production environment (EU)

https://api.eu.transmitsecurity.io/verify/

Production environment (CA)

https://api.ca.transmitsecurity.io/verify/

Production environment (AU)

https://api.au.transmitsecurity.io/verify/

Create verification session

Request

Creates a new verification session that will provide a secure context to the verification process. It returns a start token that will be used when initiating the verification process from the client side. This should be called from the backend. See the Quick start guide for details.

Security

verify_access_token

Bodyapplication/jsonrequired

callback_urlstring

The url that the user will be redirected to once the verification process completes. It will contain the session ID used to obtain the verification result

statestring

An opaque string that is used to maintain state between the request and the callback, so it should be unique per request. It will be added as a URL parameter (named state) to the callback URL. The URL parameter should be validated by your server to protect against cross-site request forgery (CSRF) attacks

mock_behaviorobject

Sets the behavior for the session for testing purposes only. For example, you can simulate a flow that results in a specific recommendation without performing an actual verification.

Example: null

startobject

Automatically start the session upon creation. If you intend to send this session to a frontend component (app, sdk, etc), leave this parameter empty - the session will be started by the frontend. However if you want to operate this session via your backend server, this parameter should be filled in.

customer_informationobject

Additional customer information for this session. This information should not contain any PII data.

time_to_livestringDeprecated

The time after which this session will be deleted (including all images and verification data). Once deleted, it will no longer be visible in the Admin Portal and the verification result won't be available via API. It should be formatted as a duration, e.g "30d", "60d", "90d". Defaults to "90d", which is 90 days.

Default "90d"

Example: "90d"

auto_startbooleanDeprecated

Deprecated. See 'start'

curl -i -X POST \
  https://api.sbx.transmitsecurity.io/verify/api/v1/verification \
  -H 'Authorization: Bearer <YOUR_jwt_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "callback_url": "string",
    "state": "string",
    "time_to_live": "90d",
    "mock_behavior": null,
    "auto_start": true,
    "start": {
      "consent": {
        "granted": true,
        "document_id": "string"
      }
    },
    "customer_information": {
      "organization_name": "string",
      "organization_id": "string",
      "external_user_id": "string"
    }
  }'

Responses

Session created

Bodyapplication/json

start_tokenstring

A single-use token that is used in the request to initiate the verification process. It will bind the session to the device. In case of an auto-start session, this token won't be returned

session_idstringrequired

ID of the new verification session, which can be used to check the status and the result

expirationstringrequired

The expiration date of this session

missing_imagesArray of stringsrequired

The additional image types that need to be added

Items Enum"document_front""document_back""selfie"

Response

application/json

{
  "start_token": "string",
  "session_id": "string",
  "expiration": "string",
  "missing_images": [
    "document_front"
  ]
}

Get verification result

Request

Retrieves the results of the verification session, which contains detailed information about the submitted documents (including PII). This should be called from the backend.

Security

verify_access_token

Path

sidanyrequired

Session ID returned upon session creation or in the callback URL upon completing the verification

Query

detailedbooleanDeprecated

This parameter allows existing customers to select between response objects. You should explicitly send false to return the DeprecatedSessionResult response structure or send true to return the new CompleteSessionResult/IncompleteSessionResult response structure. Please note this parameter will be removed once DeprecatedSessionResult is fully deprecated.

curl -i -X GET \
  'https://api.sbx.transmitsecurity.io/verify/api/v1/verification/{sid}/result?detailed=true' \
  -H 'Authorization: Bearer <YOUR_jwt_HERE>'

Responses

Bodyapplication/json

One of:

session_idstringrequired

ID of the verification session

statusstringrequired

Status of the verification session. See verification statuses

Value"complete"

recommendationstringrequired

Aggregated result of the verification checks. See recommendations

Enum"ALLOW""CHALLENGE""DENY"

Example: "DENY"

personobjectrequired

Information about the person in this session.

person.full_namestring

Full name

Example: "Marie Salomea Skłodowska-Curies"

person.given_namestring

Given name

Example: "Marie"

person.surnamestring

Family name

Example: "Curies"

person.genderstring

Gender

Enum"male""female""other"

Example: "female"

person.national_idstring

The value that identifies this specific person, like an ID number

Example: "123ABC"

person.date_of_birthstring

The person's date of birth, as an ISO-8601 string

Example: "1867-11-07T00:00:00.000Z"

person.agenumber

The person's age, at the time the verification was created. This is a derived field and is not present in the original document. It is calculated from the date of birth and the current date.

Example: 35

documentobjectrequired

Information about the document in this session.

document.countrystring

The country that issued this document, as an ISO 3166 alpha-2 code

Example: "US"

document.regionstring

Sub-division of the document's issuer within the country. For example, this field will contain the issuing state for a US drivers license but will be empty for a US passport. Given as a as an ISO 3166 alpha-2 code

Example: "NY"

document.typestringrequired

The type of this document

Enum"national_id""drivers_license""passport""residence_permit""visa""firearm_license""criminal_police_certificate""health_card""membership_card""postal"

document.numberstring

This value identifies the document and the person attached to it.

Example: "1234567"

document.serial_numberstring

This value identifies the document itself and not the person attached to it. This property isn't present on all document types, but when it is, the value will change when a document is renewed or reissued. This value is only meaningful in the context of the specific document's country and type

Example: "1234567"

document.issue_datestring

The date the document was issued, as an ISO-8601 string

Example: "1867-11-07T00:00:00.000Z"

document.expiration_datestring

The date the document is expired, as an ISO-8601 string

Example: "1867-11-07T00:00:00.000Z"

additional_infoobject

Additional information extracted from this session.

checksobjectrequired

The verification checks performed in this session.

checks.document_validationobject

Checks that the data extracted from the document is valid and matches the document template.

checks.document_authenticationobject

Checks that the document is authentic and that there are no signs of tampering.

checks.document_livenessobject

Checks that the document is a real live document (e.g., not a screen capture).

checks.biometric_matchingobject

Checks that the selfie is a biometric match to the picture extracted from the document.

checks.biometric_livenessobject

Checks that the selfie is a real live person (e.g., not a screen capture).

checks.flagged_identityobject

Checks the session against previous sessions identifying suspicious fraudulent behavior (e.g., previous face fraud).

checks.risk_recommendationobject

Assesses the risk throughout the verification process using a built-in integration with our Fraud Prevention services. This is used to detect risk signals, such as bots, spoofed devices, behavioral anomalies, malicious networks, and more.

verification_imagesArray of objectsrequired

Images used for verification

verification_images[].idstringrequired

Image ID

verification_images[].typestringrequired

Image type

Enum"document_front""document_back""selfie"

Example: "document_front"

Response

application/json

{
  "session_id": "string",
  "status": "complete",
  "recommendation": "DENY",
  "person": {
    "full_name": "Marie Salomea Skłodowska-Curies",
    "given_name": "Marie",
    "surname": "Curies",
    "gender": "female",
    "national_id": "123ABC",
    "date_of_birth": "1867-11-07T00:00:00.000Z",
    "age": 35
  },
  "document": {
    "country": "US",
    "region": "NY",
    "type": "national_id",
    "number": "1234567",
    "serial_number": "1234567",
    "issue_date": "1867-11-07T00:00:00.000Z",
    "expiration_date": "1867-11-07T00:00:00.000Z"
  },
  "additional_info": {
    "address": { … },
    "national_status": { … },
    "employment": { … }
  },
  "checks": {
    "document_validation": { … },
    "document_authentication": { … },
    "document_liveness": { … },
    "biometric_matching": { … },
    "biometric_liveness": { … },
    "flagged_identity": { … },
    "risk_recommendation": { … }
  },
  "verification_images": [
    { … }
  ]
}

Delete verification session

Request

Deletes a verification session. This deletes the personal user data collected during the verification process

Security

verify_access_token

Path

sidanyrequired

Session ID returned upon session creation or in the callback URL upon completing the verification

curl -i -X DELETE \
  'https://api.sbx.transmitsecurity.io/verify/api/v1/verification/{sid}' \
  -H 'Authorization: Bearer <YOUR_jwt_HERE>'

Responses

Session deleted

Get all images for session

Request

Retrieves all the images that were submitted for the session. The response contains only the image metadata, which includes the image ID that can be used to fetch the actual image.

Security

verify_access_token

Path

sidanyrequired

Session ID returned upon session creation or in the callback URL upon completing the verification

curl -i -X GET \
  'https://api.sbx.transmitsecurity.io/verify/api/v1/verification/{sid}/images' \
  -H 'Authorization: Bearer <YOUR_jwt_HERE>'

Responses

List of all images (metadata)

Bodyapplication/json

session_imagesArray of objectsrequired

session_images[].idstringrequired

The ID of the image

session_images[].formatstring

The data format of the image. Currently, only jpg is supported

session_images[].typestring

The type of content in the image

Enum"document_front""document_back""selfie"

session_images[].rejectedbooleanrequired

true if the image was rejected for processing - i.e it's too blurry, the document is obstructed, etc

session_images[].originalbooleanrequired

True if this is the original image uploaded by the user, false if it was refined by our system

session_images[].original_idstring

The ID of the original image, if this is a refined image

Response

application/json

{
  "session_images": [
    { … }
  ]
}

Get image by ID

Request

Retrieve the actual image from the session (and not only the image metadata). The image is specified by the image ID returned upon fetching all the session images.

Security

verify_access_token

Path

idstringrequired

Image ID returned by the request to get all images

sidanyrequired

Session ID returned upon session creation or in the callback URL upon completing the verification

Query

formatstring

Optional. Determines the image format returned. Enum: raw base64

Examples:

Raw format

Unprocessed binary image format

format=raw

Base64 format

Base64-encoded string format

format=base64

curl -i -X GET \
  'https://api.sbx.transmitsecurity.io/verify/api/v1/verification/{sid}/images/{id}?format=string' \
  -H 'Authorization: Bearer <YOUR_jwt_HERE>'

Responses

Actual image

Bodyimage/jpg

string(binary)

Get consent

Request

Checks whether user consent was provided for a specific session and if so, provides the timestamp

Security

verify_access_token

Path

sidanyrequired

Session ID returned upon session creation or in the callback URL upon completing the verification

curl -i -X GET \
  'https://api.sbx.transmitsecurity.io/verify/api/v1/verification/{sid}/consent' \
  -H 'Authorization: Bearer <YOUR_jwt_HERE>'

Responses

Session created

Bodyapplication/json

consent_grantedbooleanrequired

An indication of whether a user has approved the consent or not

consent_datestring

The timestamp of the consent approval. Returned empty if consent was not granted

Response

application/json

{
  "consent_granted": true,
  "consent_date": "string"
}

Document Verification

Create verification session

RequestExpand all

Responses

Get verification result

Request

Responses

Delete verification session

Request

Responses

Get all images for session

Request

Responses

Get image by ID

Request

Responses

Get consent

Request

Responses

Request