Skip to content

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
Languages
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
Example: null
startobject
customer_informationobject
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
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
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
checksobjectrequired
checks.​document_validationobject
checks.​document_authenticationobject
checks.​document_livenessobject
checks.​biometric_matchingobject
checks.​biometric_livenessobject
checks.​flagged_identityobject
checks.​risk_recommendationobject
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:

Unprocessed binary image format

format=raw

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"
}