Transmit Security Verification API

openapi: 3.2.0
info:
  version: '1.0'
  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.
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:
    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'
    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
    RiskDetailsGeneralDto:
      type: object
      properties:
        correlation_id:
          type: string
          description: Unique correlation ID for the verification action.
          example: SUMCposIdWZfgNp
        action_type:
          type: string
          description: Type of action assessed by Fraud Prevention.
          example: identity_verification
        recommendation:
          type: string
          description: Fraud Prevention recommendation for the verification action.
          example: rejected
        risk_score:
          type: number
          format: float
          description: Risk score calculated by Fraud Prevention.
          example: 94.6
    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/schemas/NationalStatusDto'
        employment:
          description: The person's employment information
          allOf:
          - $ref: '#/components/schemas/EmploymentDto'
    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
    CustomerInformation:
      type: object
      properties:
        organization_name:
          type: string
          description: Name of the organization or branch
        organization_id:
          type: string
          description: Unique ID of the organization
        external_user_id:
          type: string
          description: Unique identifier of a user. It should be one word and shouldn't not include any PII
    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'
    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
    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'
    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
    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
    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
    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'
    StartSessionConfigDto:
      type: object
      properties:
        consent:
          description: Consent for the session
          allOf:
          - $ref: '#/components/schemas/SessionConsent'
    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
    GetConsentApprovalResponse:
      type: object
      properties:
        consent_granted:
          type: boolean
          description: An indication of whether a user has approved the consent or not
        consent_date:
          type: string
          description: The timestamp of the consent approval. Returned empty if consent was not granted
      required:
      - consent_granted
    DocumentValidationCheckDto:
      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:
            - data_extraction_failed
            - data_validation_failed
            - data_comparison_failed
            - mrz_check_digits_invalid
      required:
      - recommendation
    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
    RiskRecommendationCheckDto:
      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 [reasons](/guides/risk/recommendations.md) forwarded from Fraud Prevention services.
          items:
            type: string
            enum:
            - action_is_legit
            - action_is_suspected_fraud
            - behavior_bot_typing
            - behavior_bot
            - behavior_inhuman_input
            - behavior_suspicious_input
            - behavior_suspicious_movement
            - device_bot
            - device_cookie_reused
            - device_emulated_gpu
            - device_emulator
            - device_history_suspicious_fingerprint
            - device_impossible_travel
            - device_incognito_browser
            - device_old_version
            - device_origin_anomaly
            - device_platform_anomaly
            - device_platform_automation
            - device_private_browser
            - device_profile_velocity
            - device_risky_reputation
            - device_rooted
            - device_spoofed
            - device_suspected_bot
            - device_suspicious_cpu_core
            - device_suspicious_display
            - device_suspicious_language
            - device_suspicious_network
            - device_suspicious_platform
            - device_suspicious_timezone
            - device_suspicious_useragent
            - device_suspicious_velocity
            - device_takeover
            - device_tampered
            - device_vm
            - ip_action_velocity
            - ip_country_blocked
            - ip_is_biz
            - ip_is_gov
            - ip_is_mil
            - ip_is_vpn
            - ip_risky_anonymize
            - ip_risky_reputation
            - ip_trusted
            - profile_action_velocity
            - profile_activity_anomaly
            - profile_device_anomaly
            - profile_device_familiar_model
            - profile_device_familiar
            - profile_device_new
            - profile_device_velocity
            - profile_familiar
            - profile_impossible_travel
            - profile_ip_familiar
            - profile_location_anomaly
            - profile_location_new
            - profile_network_anomaly
            - profile_trusted
            - user_profile_anomaly
            - user_trusted
            - other
      required:
      - recommendation
    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
    PersonDto:
      type: object
      properties:
        full_name:
          type: string
          description: Full name
          example: Marie Salomea Skłodowska-Curies
        given_name:
          type: string
          description: Given name
          example: Marie
        surname:
          type: string
          description: Family name
          example: Curies
        gender:
          type: string
          description: Gender
          enum:
          - male
          - female
          - other
          example: female
        national_id:
          type: string
          description: The value that identifies this specific person, like an ID number
          example: 123ABC
        date_of_birth:
          type: string
          description: The person's date of birth, as an ISO-8601 string
          example: '1867-11-07T00:00:00.000Z'
        age:
          type: number
          description: 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
    DeprecatedSessionResult:
      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:
          - pending
          - capturing
          - processing
          - recapture
          - complete
          - error
        recommendation:
          type: string
          description: "Aggregated result of the verification checks. Returned only if the verification was completed.\n    See [recommendations]( /guides/verify/identity_verification_result/#recommendations)"
          enum:
          - ALLOW
          - CHALLENGE
          - DENY
        rejection_description:
          description: Human-readable description of any issues with this session. Not returned if the recommendation is ALLOW
          type: array
          items:
            type: string
        extracted_info:
          description: Information extracted from this session, but not guaranteed to be verified. Not returned if the recommendation is ALLOW
          allOf:
          - $ref: '#/components/schemas/DeprecatedExtractedInfoDto'
        verified_info:
          description: Info verified in the verification session. Returned only if the recommendation is ALLOW
          allOf:
          - $ref: '#/components/schemas/VerifiedInfoDto'
      required:
      - session_id
      - status
    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
    IncompleteSessionResult:
      type: object
      propert

# --- 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