openapi: 3.0.3
info:
title: One-Time Login Applications Verification API
description: Login users using one-time login methods like magic links or OTPs. This implements a backend-to-backend integration for authentication.
version: ''
servers:
- url: https://api.sbx.transmitsecurity.io/cis
description: Sandbox environment
- url: https://api.transmitsecurity.io/cis
description: Production environment (US)
- url: https://api.eu.transmitsecurity.io/cis
description: Production environment (EU)
- url: https://api.ca.transmitsecurity.io/cis
description: Production environment (CA)
- url: https://api.au.transmitsecurity.io/cis
description: Production environment (AU)
security: []
tags:
- name: Verification
paths:
/api/v1/verification:
post:
operationId: createSession
summary: Create verification session
description: 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](https://developer.transmitsecurity.com/guides/verify/quick_start_web/#step-4-initiate-id-verification) for details.
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionRequest'
responses:
'201':
description: Session created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionResponse'
'400':
description: Request is malformed or missing required fields
'401':
description: Access token is malformed, missing data, or expired
security:
- verify_access_token: []
tags:
- Verification
/api/v1/verification/{sid}/result:
get:
operationId: getResult
summary: Get verification result
description: Retrieves the results of the verification session, which contains detailed information about the submitted documents (including PII). This should be called from the backend.
parameters:
- name: detailed
required: false
in: query
description: 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.
deprecated: true
example: false
schema:
type: boolean
- name: sid
required: true
in: path
description: Session ID returned upon session creation or in the callback URL upon completing the verification
schema: {}
responses:
'200':
description: ''
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CompleteSessionResult'
- $ref: '#/components/schemas/IncompleteSessionResult'
- $ref: '#/components/schemas/DeprecatedSessionResult'
'400':
description: Request is malformed or missing required fields
'401':
description: Access token is malformed, missing data, or expired
'404':
description: Session not found
security:
- verify_access_token: []
tags:
- Verification
/api/v1/verification/{sid}:
delete:
operationId: deleteSession
summary: Delete verification session
description: Deletes a verification session. This deletes the personal user data collected during the verification process
parameters:
- name: sid
required: true
in: path
description: Session ID returned upon session creation or in the callback URL upon completing the verification
schema: {}
responses:
'200':
description: Session deleted
'400':
description: Request is malformed or missing required fields
'401':
description: Access token is malformed, missing data, or expired
'404':
description: Session not found
security:
- verify_access_token: []
tags:
- Verification
/api/v1/verification/{sid}/images:
get:
operationId: getImages
summary: Get all images for session
description: 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.
parameters:
- name: sid
required: true
in: path
description: Session ID returned upon session creation or in the callback URL upon completing the verification
schema: {}
responses:
'200':
description: List of all images (metadata)
content:
application/json:
schema:
$ref: '#/components/schemas/SessionImagesResponse'
'400':
description: Request is malformed or missing required fields
'401':
description: Access token is malformed, missing data, or expired
security:
- verify_access_token: []
tags:
- Verification
/api/v1/verification/{sid}/images/{id}:
get:
operationId: getImage
summary: Get image by ID
description: 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.
parameters:
- name: id
required: true
in: path
description: Image ID returned by the request to get all images
schema:
type: string
- name: format
required: false
in: query
description: 'Optional. Determines the image format returned. Enum: `raw` `base64`'
examples:
raw:
summary: Raw format
description: Unprocessed binary image format
value: raw
base64:
summary: Base64 format
description: Base64-encoded string format
value: base64
schema:
type: string
- name: sid
required: true
in: path
description: Session ID returned upon session creation or in the callback URL upon completing the verification
schema: {}
responses:
'200':
description: Actual image
content:
image/jpg:
schema:
type: string
format: binary
'400':
description: Request is malformed or missing required fields
'401':
description: Access token is malformed, missing data, or expired
'404':
description: Image not found
security:
- verify_access_token: []
tags:
- Verification
/api/v1/verification/{sid}/consent:
get:
operationId: getConsent
summary: Get consent
description: Checks whether user consent was provided for a specific session and if so, provides the timestamp
parameters:
- name: sid
required: true
in: path
description: Session ID returned upon session creation or in the callback URL upon completing the verification
schema: {}
responses:
'200':
description: Session created
content:
application/json:
schema:
$ref: '#/components/schemas/GetConsentApprovalResponse'
'400':
description: Request is malformed or missing required fields
'401':
description: Access token is malformed, missing data, or expired
'404':
description: Session not found
security:
- verify_access_token: []
tags:
- Verification
components:
schemas:
VerifiedInfoDto:
type: object
properties:
person:
description: Information about the person identified by this session
allOf:
- $ref: '#/components/schemas/DeprecatedPersonDto'
document:
description: Information from the documents of this session
allOf:
- $ref: '#/components/schemas/DeprecatedDocumentDto'
SessionImagesResponse:
type: object
properties:
session_images:
type: array
items:
$ref: '#/components/schemas/SessionImageDto'
required:
- session_images
ExtractedDetails:
type: object
properties:
person_details:
description: Information about the person in this session
allOf:
- $ref: '#/components/schemas/DeprecatedPersonDto'
document_details:
description: Information extracted from the document in this session
allOf:
- $ref: '#/components/schemas/DeprecatedDocumentDto'
SessionChecksDto:
type: object
properties:
document_validation:
description: Checks that the data extracted from the document is valid and matches the document template.
allOf:
- $ref: '#/components/schemas/DocumentValidationCheckDto'
document_authentication:
description: Checks that the document is authentic and that there are no signs of tampering.
allOf:
- $ref: '#/components/schemas/DocumentAuthenticationCheckDto'
document_liveness:
description: Checks that the document is a real live document (e.g., not a screen capture).
allOf:
- $ref: '#/components/schemas/DocumentLivenessCheckDto'
biometric_matching:
description: Checks that the selfie is a biometric match to the picture extracted from the document.
allOf:
- $ref: '#/components/schemas/BiometricMatchingCheckDto'
biometric_liveness:
description: Checks that the selfie is a real live person (e.g., not a screen capture).
allOf:
- $ref: '#/components/schemas/BiometricLivenessCheckDto'
flagged_identity:
description: Checks the session against previous sessions identifying suspicious fraudulent behavior (e.g., previous face fraud).
allOf:
- $ref: '#/components/schemas/FlaggedIdentityCheckDto'
risk_recommendation:
description: Assesses the risk throughout the verification process using a built-in integration with our [Fraud Prevention](/guides/risk/overview.md) services. This is used to detect risk signals, such as bots, spoofed devices, behavioral anomalies, malicious networks, and more.
allOf:
- $ref: '#/components/schemas/RiskRecommendationCheckDto'
VerificationImageDto:
type: object
properties:
id:
type: string
description: Image ID
type:
type: string
description: Image type
enum:
- document_front
- document_back
- selfie
example: document_front
required:
- id
- type
RiskDetailsDeviceDto:
type: object
properties:
os:
type: string
description: Operating system used by the device.
example: Android
browser:
type: string
description: Browser used by the device.
example: Chrome
device_id:
type: string
description: Unique device identifier.
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
device_fingerprint:
type: string
description: Device fingerprint hash.
example: 4ebf21edcb4297363ad239386fc6e45e34123045f6ac7b9da93c415d7cb60bdc
device_type:
type: string
enum:
- mobile
- desktop
description: Type of device used for the verification.
example: mobile
device_model:
type: string
description: Device model used for the verification.
example: SM-G955U
device_timestamp:
type: integer
format: int64
description: Timestamp of the device event, in epoch milliseconds.
example: 1777462766771
timezone:
type: string
description: Device timezone.
example: Asia/Jerusalem
incognito:
type: boolean
description: Indicates whether incognito mode was detected.
example: false
tampered:
type: boolean
description: Indicates whether device tampering was detected.
example: false
emulated:
type: boolean
description: Indicates whether an emulator was detected.
example: false
spoofed:
type: boolean
description: Indicates whether device spoofing was detected.
example: true
esim:
type: boolean
description: Indicates whether eSIM information was detected.
example: false
RiskDetailsNetworkDto:
type: object
properties:
network_country:
type: string
description: Country detected from the network.
example: IE
ip_address:
type: string
description: IP address (IPv4 or IPv6) detected from the network.
example: 192.168.1.1
ip_type:
type: string
description: Type of IP address detected.
example: hosting
ip_organization:
type: string
description: Organization associated with the IP address.
example: Amazon.com, Inc.
timezone:
type: string
description: Timezone detected from the IP address.
example: Europe/Dublin
vpn:
type: boolean
description: Indicates whether VPN usage was detected.
example: false
tor:
type: boolean
description: Indicates whether Tor usage was detected.
example: false
proxy:
type: boolean
description: Indicates whether proxy usage was detected.
example: false
anonymizer:
type: boolean
description: Indicates whether anonymizer usage was detected.
example: false
DocumentDto:
type: object
properties:
country:
type: string
description: The country that issued this document, as an ISO 3166 alpha-2 code
example: US
region:
type: string
description: 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
type:
type: string
description: The type of this document
enum:
- national_id
- drivers_license
- passport
- residence_permit
- visa
- firearm_license
- criminal_police_certificate
- health_card
- membership_card
- postal
- social_security_card
- voter_card
- professional_id
- other
number:
type: string
description: This value identifies the document and the person attached to it.
example: '1234567'
serial_number:
type: string
description: 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'
issue_date:
type: string
description: The date the document was issued, as an ISO-8601 string
example: '1867-11-07T00:00:00.000Z'
expiration_date:
type: string
description: The date the document is expired, as an ISO-8601 string
example: '1867-11-07T00:00:00.000Z'
required:
- type
BiometricMatchingCheckDto:
type: object
properties:
recommendation:
type: string
description: The recommendation of the check.
enum:
- ALLOW
- CHALLENGE
- DENY
- N/A
example: DENY
reasons:
type: array
description: Machine-readable rejection reasons.
items:
type: string
enum:
- biometric_mismatch
- age_mismatch
- gender_mismatch
required:
- recommendation
DeprecatedExtractedInfoDto:
type: object
properties:
document:
description: Info extracted from the verification session. Returned only if the verification was completed
allOf:
- $ref: '#/components/schemas/DeprecatedDocumentDto'
person:
description: Information about the person in this session
allOf:
- $ref: '#/components/schemas/DeprecatedPersonDto'
CreateSessionRequest:
type: object
properties:
callback_url:
type: string
description: 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
state:
type: string
description: 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
time_to_live:
type: string
description: 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.
deprecated: true
example: 90d
default: 90d
mock_behavior:
description: 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
allOf:
- $ref: '#/components/schemas/MockBehavior'
auto_start:
type: boolean
description: Deprecated. See 'start'
deprecated: true
start:
description: 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.
allOf:
- $ref: '#/components/schemas/StartSessionConfigDto'
customer_information:
description: Additional customer information for this session. This information should not contain any PII data.
allOf:
- $ref: '#/components/schemas/CustomerInformation'
BiometricLivenessCheckDto:
type: object
properties:
recommendation:
type: string
description: The recommendation of the check.
enum:
- ALLOW
- CHALLENGE
- DENY
- N/A
example: DENY
reasons:
type: array
description: Machine-readable rejection reasons.
items:
type: string
enum:
- screen_capture
- printed_copy_capture
- printed_cutout
- mask_detected
- injection_attack_detected
- selfie_liveness_attack
- multiple_faces_detected
required:
- recommendation
CreateSessionResponse:
type: object
properties:
start_token:
type: string
description: 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_id:
type: string
description: ID of the new verification session, which can be used to check the status and the result
expiration:
type: string
description: The expiration date of this session
missing_images:
type: array
description: The additional image types that need to be added
items:
type: string
enum:
- document_front
- document_back
- selfie
required:
- session_id
- expiration
- missing_images
SessionImageDto:
type: object
properties:
id:
type: string
description: The ID of the image
format:
type: string
description: The data format of the image. Currently, only jpg is supported
type:
type: string
description: The type of content in the image
enum:
- document_front
- document_back
- selfie
rejected:
type: boolean
description: true if the image was rejected for processing - i.e it's too blurry, the document is obstructed, etc
original:
type: boolean
description: True if this is the original image uploaded by the user, false if it was refined by our system
original_id:
type: string
description: The ID of the original image, if this is a refined image
required:
- id
- rejected
- original
SessionConsent:
type: object
properties:
granted:
type: boolean
description: Flag confirming consent was granted
document_id:
type: string
description: The ID of the consent document presented to the customer
required:
- granted
- document_id
MockBehavior:
type: object
properties:
mock_recommendation:
type: string
description: Deprecated. see 'recommendation'
deprecated: true
enum:
- ALLOW
- CHALLENGE
- DENY
recommendation:
type: string
description: "The desired recommendation for this session.\n See [recommendations](/guides/verify/identity_verification_result/#recommendations)"
enum:
- ALLOW
- CHALLENGE
- DENY
processing_time:
type: string
description: The desired processing time once all the images are captured. Formatted as a duration, e.g "15s", "1m30s"
force_retry:
type: boolean
description: Allows simulating a recapture status. If true, a recapture status will be returned for the first attempt to verify the session
info:
description: The desired result for extracted info fields
allOf:
- $ref: '#/components/schemas/ExtractedDetails'
DeprecatedPersonDto:
type: object
properties:
given_name:
type: string
description: Given name
example: Marie
surname:
type: string
description: Family name
example: Curie
gender:
type: string
description: Gender
example: F
full_name:
type: string
description: Full name
example: Marie Salomea Skłodowska-Curies
age:
type: number
description: The person's age, at the current UTC date
example: 36
address:
description: The person's address
allOf:
- $ref: '#/components/schemas/DeprecatedAddressDetailsDto'
date_of_birth:
type: string
description: The person's date of birth, as an ISO-8601 string
example: '1867-11-07T00:00:00.000Z'
DeprecatedAddressDetailsDto:
type: object
properties:
country:
type: string
description: ISO 3166-1 alpha-3 country code
example: USA
region:
type: string
description: Region
example: Indiana
city:
type: string
description: City
example: Indianapolis
street:
type: string
description: Street
example: Snowy Ridge Road
house_number:
type: string
description: House number
example: '1234'
apartment_number:
type: string
description: Apartment number
example: '12'
postcode:
type: string
description: Postcode
example: '56789'
full_address:
type: string
description: Full address
example: 1234 Snowy Ridge Road Indianapolis, IN 56789
DeprecatedDocumentDto:
type: object
properties:
type:
type: string
description: The type of this document
enum:
- national_id
- drivers_license
- passport
- residence_permit
- visa
- firearm_license
- criminal_police_certificate
- health_card
- membership_card
- postal
- social_security_card
- voter_card
- professional_id
- other
country:
type: string
description: The country that issued this document, as an ISO 3166-1 alpha-3 code
example: USA
region:
type: string
description: 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.
example: ny
issue_date:
type: string
description: The date the document was issued, as an ISO-8601 string
example: '1867-11-07T00:00:00.000Z'
document_serial_number:
type: string
description: A value that identifies this specific document. When an ID (for example) expires and a new one is issued, the 'id_value' will remain the same but this value will be different.
example: '1234567'
id_value:
type: string
description: The value that identifies this specific person, like an ID number
example: 123ABC
given_name:
type: string
description: The person's given name, according to this document
example: Marie
surname:
type: string
description: The person's surname, according to this document
example: Curie
full_name:
type: string
description: The person's full name, according to this document
example: Marie Salomea Skłodowska-Curie
date_of_birth:
type: string
description: The person's date of birth, as an ISO-8601 string
example: '1867-11-07T00:00:00.000Z'
valid_until:
type: string
description: The date the document is expired, as an ISO-8601 string
example: '1867-11-07T00:00:00.000Z'
required:
- type
NationalStatusDto:
type: object
properties:
citizen:
type: boolean
description: Indicates if the person is a citizen of the issuing country
resident:
type: boolean
description: Indicates if the person is a permanent resident of the issuing country
CompleteSessionResult:
type: object
properties:
session_id:
type: string
description: ID of the verification session
status:
type: string
description: "Status of the verification session.\n See [verification statuses](/guides/verify/identity_verification_result/#verification-status)"
enum:
- complete
recommendation:
type: string
description: "Aggregated result of the verification checks.\n See [recommendations]( /guides/verify/identity_verification_result/#recommendations)"
enum:
- ALLOW
- CHALLENGE
- DENY
example: DENY
risk_details:
description: Detailed risk information collected during the verification flow.
allOf:
- $ref: '#/components/schemas/RiskDetailsDto'
person:
description: Information about the person in this session.
allOf:
- $ref: '#/components/schemas/PersonDto'
document:
description: Information about the document in this session.
allOf:
- $ref: '#/components/schemas/DocumentDto'
additional_info:
description: Additional information extracted from this session.
allOf:
- $ref: '#/components/schemas/AdditionalInfoDto'
checks:
description: The verification checks performed in this session.
allOf:
- $ref: '#/components/schemas/SessionChecksDto'
verification_images:
type: array
description: Images used for verification
items:
$ref: '#/components/schemas/VerificationImageDto'
required:
- session_id
- status
- recommendation
- person
- document
- checks
- verification_images
DocumentAuthenticationCheckDto:
type: object
properties:
recommendation:
type: string
description: The recommendation of the check.
enum:
- ALLOW
- CHALLENGE
- DENY
- N/A
example: DENY
reasons:
type: array
description: Machine-readable rejection reasons.
items:
type: string
enum:
- face_tampering
- face_not_found
- missing_security_features
- document_tampering
- document_text_tampering
- wrong_font
- document_damaged
- document_template_mismatch
required:
- recommendation
RiskDetailsDto:
type: object
properties:
general:
description: General Fraud Prevention details for the verification action.
allOf:
- $ref: '#/components/schemas/RiskDetailsGeneralDto'
device:
description: Device risk details collected during the verification flow.
allOf:
- $ref: '#/components/schemas/RiskDetailsDeviceDto'
network:
description: Network risk details collected during the verification flow.
allOf:
- $ref: '#/components/schemas/RiskDetailsNetworkDto'
recommendation_reasons:
type: array
description: Risk signals that contributed to the recommendation.
items:
type: string
example:
- DEVICE_SPOOFED_BY_USERAGENT
- DEVICE_SUSPICIOUS_PLATFORM_OS
- DEVICE_VERY_OLD_VERSION
- DEVICE_PLATFORM_ANOMALY
- DEVICE_IP_TIMEZONE_MISMATCH
- IP_RISKY_REPUTATION
- DEVICE_NEW
FlaggedIdentityCheckDto:
type: object
properties:
recommendation:
type: string
description: The recommendation of the check.
enum:
- ALLOW
- CHALLENGE
- DENY
- N/A
example: DENY
reasons:
type: array
description: Machine-readable rejection reasons.
items:
type: string
enum:
- multiple_same_identity_attempts
- previous_document_fraud
- previous_face_fraud
required:
- recommendation
AdditionalInfoDto:
type: object
properties:
address:
description: The person's address
allOf:
- $ref: '#/components/schemas/AddressDto'
national_status:
description: The person's national status
allOf:
- $ref: '#/components
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/transmit-security/refs/heads/main/openapi/transmit-security-verification-api-openapi.yml