openapi: 3.2.0
info:
  title: Encrypted Verifications API
  description: API to manage verifications, messages, checkers, devices, and risk scores.
  contact:
    name: API Support
    url: https://trusona.com
    email: support@trusona.com
  version: 2.2.0
  summary: 'Base URL: https://authcloud.trusona.net'
servers:
- url: https://authcloud.trusona.net
security:
- bearerAuth: []
tags:
- name: Encrypted Verifications
paths:
  /api/v1/encrypted/verifications:
    post:
      tags:
      - Encrypted Verifications
      summary: Create a new verification with encrypted response
      description: Create a new verification and return the verification data encrypted with the provided encryption key.
      operationId: createEncryptedVerification
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEncryptedVerificationDto'
        required: true
      responses:
        '201':
          description: Verification created successfully with encryption token
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/EncryptedVerificationResponse'
        '400':
          description: Bad request - Must be one of RSA, EC or OKP (crv=X25519) type in JWK format
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity - validation failed
  /api/v1/encrypted/verifications/{verificationId}:
    get:
      tags:
      - Encrypted Verifications
      summary: Get an encrypted verification by ID
      operationId: getEncryptedVerification
      parameters:
      - name: verificationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Verification retrieved successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/EncryptedVerificationResponse'
        '401':
          description: Unauthorized
        '404':
          description: Verification not found
  /api/v1/encrypted/verifications/{verificationId}/document:
    get:
      tags:
      - Encrypted Verifications
      summary: Get an encrypted document by verification ID
      description: Get the verification's document and return it encrypted with the same public key provided when the verification was created.
      operationId: getEncryptedDocument
      parameters:
      - name: verificationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Encrypted document retrieved successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/EncryptedDocumentResponse'
        '401':
          description: Unauthorized
        '404':
          description: Verification not found or document is not yet available
        '410':
          description: Document has been removed (occurs when parent verification expires)
components:
  schemas:
    EncryptedVerificationResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: bd30618f-06d3-45c5-ae52-c36751fc20b2
          readOnly: true
        overallRisk:
          type: string
          enum:
          - 'NO'
          - LOW
          - HIGH
          readOnly: true
        encryptedVerification:
          type: string
          description: JWE Verification object
          example: eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0...
          readOnly: true
    RequestedMessage:
      type: object
      discriminator:
        propertyName: channel
      properties:
        channel:
          type: string
          enum:
          - COPY
          - SMS
          - EMAIL
          - TRUSTED_SMS
      required:
      - channel
    RequestedMnoVerifier:
      allOf:
      - $ref: '#/components/schemas/RequestedVerifier'
      - type: object
        properties:
          phoneNumber:
            type: string
            description: Phone number for MNO verification. Must be in one of the countries the tenant has enabled for MNO, which default to the USA (+1), Canada (+1) and the UK (+44). Dashes, spaces, dots and parentheses are accepted; a missing country code is resolved against the default countries, so numbers from any other enabled country must be given in E.164 form.
            example: '+12025551234'
      description: Request an MNO (mobile network operator) verification.
      required:
      - verifier
    RequestedVerifier:
      type: object
      discriminator:
        propertyName: verifier
      properties:
        verifier:
          type: string
          enum:
          - DMV
          - MNO_V
          - SCAN
      required:
      - verifier
    RequestedSmsMessage:
      allOf:
      - $ref: '#/components/schemas/RequestedMessage'
      - type: object
        properties:
          phoneNumber:
            type: string
            description: Phone number to send the SMS to. Dashes, spaces, dots and parentheses are accepted, as is a missing leading +; the number is stored and returned in E.164 form. A number sent without a country code cannot be resolved and is rejected.
            example: '+12025551234'
      description: Send an SMS message to the provided phone number.
      required:
      - channel
    RequestedEmailMessage:
      allOf:
      - $ref: '#/components/schemas/RequestedMessage'
      - type: object
        properties:
          emailAddress:
            type: string
            format: email
            description: Email address to send the message to.
            example: user@example.com
            minLength: 1
      description: Send an email message to the provided email address.
      required:
      - channel
      - emailAddress
    RequestedDmvVerifier:
      allOf:
      - $ref: '#/components/schemas/RequestedVerifier'
      description: Request a DMV (AAMVA) verification.
      required:
      - verifier
    VerificationSubject:
      type: object
      description: Subject identity information supplied by the API consumer for matching against the scanned document.
      properties:
        firstName:
          type: string
          description: Expected first name.
          example: Susan
          maxLength: 128
          minLength: 0
        lastName:
          type: string
          description: Expected last name.
          example: O'Brien
          maxLength: 128
          minLength: 0
        dateOfBirth:
          type: string
          description: Expected date of birth in MM/DD/YYYY format.
          example: 03/14/1990
        city:
          type: string
          description: Expected city.
          example: San Francisco
          maxLength: 32
          minLength: 0
        state:
          type: string
          description: Expected state, province or region.
          example: CA
          maxLength: 32
          minLength: 0
        country:
          type: string
          description: Expected country as ISO 3166-1 alpha-2.
          example: US
          pattern: ^[A-Za-z]{2}$
    RequestedTrustedSmsMessage:
      allOf:
      - $ref: '#/components/schemas/RequestedMessage'
      - type: object
        properties:
          phoneNumber:
            type: string
            description: Phone number to send the trusted SMS to. Dashes, spaces, dots and parentheses are accepted, as is a missing leading +; the number is stored and returned in E.164 form. A number sent without a country code cannot be resolved and is rejected.
            example: '+12025551234'
      description: Send a trusted SMS with SIM swap detection to the provided phone number.
      required:
      - channel
    EncryptedDocumentResponse:
      type: object
      properties:
        verificationId:
          type: string
          format: uuid
          description: The verification ID associated with this document
          example: 10c9207a-1c3d-45fd-874f-a2af9c2d33d4
          readOnly: true
        encryptedDocument:
          type: string
          description: JWE document object
          example: eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0...
          readOnly: true
    RequestedLexisNexisVerifier:
      allOf:
      - $ref: '#/components/schemas/RequestedVerifier'
      description: Request a LexisNexis verification.
      required:
      - verifier
    RequestedCopyMessage:
      allOf:
      - $ref: '#/components/schemas/RequestedMessage'
      required:
      - channel
    CreateEncryptedVerificationDto:
      type: object
      properties:
        documentType:
          type: string
          enum:
          - US_CA_DL
          - UK_DL
          - PASSPORT
          - INDIA_DL
          - INDIA_ID
          - INDIA_PAN
          - PHILIPPINES_DL
          - PHILIPPINES_ID
          - PHILIPPINES_MULTI_ID
          - US_MILITARY_ID
          - US_VETERAN_ID
          - SINGAPORE_DL
          - SINGAPORE_ID
          - SINGAPORE_WORK_PERMIT
          - SINGAPORE_EMPLOYMENT_PASS
          - PAKISTAN_ID
          - AUSTRALIA_DL
          - MEXICO_DL
          - NETHERLANDS_DL
          - US_PERMANENT_RESIDENT_CARD
          - GERMANY_ID
          - GERMANY_DL
          - GERMANY_RESIDENCE_PERMIT
          - AUSTRIA_ID
          - AUSTRIA_DL
          - AUSTRIA_RESIDENCE_PERMIT
          example: US_CA_DL
        callbackUrl:
          type:
          - string
          - 'null'
          format: uri
          example: https://example.com/callback/unique/to/this/request/8b62142a99ba759d8c9153b68765513c62180891
        requestedVerifiers:
          type: array
          description: Set of verifiers to run against this verification. Each entry uses the 'verifier' discriminator field.
          example:
          - verifier: DMV
          - verifier: MNO_V
            phoneNumber: '+12025551234'
          items:
            oneOf:
            - $ref: '#/components/schemas/RequestedVerifier'
            - $ref: '#/components/schemas/RequestedDmvVerifier'
            - $ref: '#/components/schemas/RequestedLexisNexisVerifier'
            - $ref: '#/components/schemas/RequestedMnoVerifier'
          uniqueItems: true
        subject:
          type: 'null'
          $ref: '#/components/schemas/VerificationSubject'
          description: Optional identity information about the subject of this verification, used by the ExpectedSubjectVerifier to compare against the scanned document.
        requestedMessages:
          type: array
          description: Set of messages to send for this verification. Each entry uses the 'channel' discriminator field. Maximum 2.
          example:
          - channel: SMS
            phoneNumber: '+12025551234'
          - channel: EMAIL
            emailAddress: user@example.com
          items:
            oneOf:
            - $ref: '#/components/schemas/RequestedMessage'
            - $ref: '#/components/schemas/RequestedCopyMessage'
            - $ref: '#/components/schemas/RequestedEmailMessage'
            - $ref: '#/components/schemas/RequestedSmsMessage'
            - $ref: '#/components/schemas/RequestedTrustedSmsMessage'
          maxItems: 2
          minItems: 0
          uniqueItems: true
        status:
          type:
          - string
          - 'null'
          enum:
          - CREATED
        publicWebKey:
          type: object
          additionalProperties: {}
          description: Public key used for encrypting the verification response. Must be one of RSA, EC or OKP (crv=X25519) type in JWK format.
      required:
      - documentType
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT