openapi: 3.0.3
info:
  title: Acuant AssureID Connect API
  description: >-
    REST API for document identity verification. Supports creating document
    transactions, uploading multi-spectral images, extracting data fields,
    and retrieving authentication results for over 3,400 global document
    types including driver's licenses, passports, and national IDs. Uses
    HTTP Basic authentication over HTTPS.
  version: '1.0'
  contact:
    name: Acuant Support
    url: https://support.acuant.com
  x-api-id: acuant:assureid-connect
servers:
  - url: https://services.assureid.net
    description: USA Production
  - url: https://us.assureid.acuant.net
    description: USA Production (alternate)
  - url: https://eu.assureid.acuant.net
    description: EU Production
  - url: https://aus.assureid.acuant.net
    description: AUS Production
  - url: https://preview.assureid.acuant.net
    description: Preview / Sandbox
security:
  - BasicAuth: []
tags:
  - name: Document Instances
    description: Create and manage document processing sessions
  - name: Images
    description: Submit and retrieve document images
  - name: Document Data
    description: Upload and retrieve extracted document data
  - name: Chip Data
    description: Submit and retrieve contactless chip data
  - name: Metadata
    description: Supported document types, subscriptions, logs
paths:
  /Document/Instance:
    post:
      operationId: createDocumentInstance
      summary: Create document processing instance
      description: >-
        Creates a new document processing session. Returns an instance ID (GUID)
        used for all subsequent operations in the transaction.
      tags:
        - Document Instances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentCreateRequest'
            example:
              SubscriptionId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              ImageCroppingExpectedSize: 0
              ImageCroppingMode: 0
              ManualCropCoordinates: null
              Device:
                Manufacturer: "Acuant"
                Model: "WebSDK"
                SerialNumber: "1234567890"
                Type:
                  Manufacturer: "Web"
                  Model: "Browser"
                  SensorType: 2
      responses:
        '200':
          description: Document instance created successfully
          content:
            application/json:
              schema:
                type: string
                format: uuid
                description: Instance ID (GUID) for the document processing session
              example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /Document/{instanceId}:
    get:
      operationId: getDocumentResult
      summary: Retrieve document processing results
      description: >-
        Returns the full document processing result including classification,
        extracted field data, and authentication test results.
      tags:
        - Document Instances
      parameters:
        - $ref: '#/components/parameters/instanceId'
      responses:
        '200':
          description: Document processing result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deleteDocumentInstance
      summary: Delete document instance
      description: Removes a document instance and all associated data.
      tags:
        - Document Instances
      parameters:
        - $ref: '#/components/parameters/instanceId'
      responses:
        '200':
          description: Instance deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /Document/{instanceId}/Image:
    post:
      operationId: uploadDocumentImage
      summary: Upload document image
      description: >-
        Submits a document image for the specified instance. Multiple images
        can be submitted with different light sources and document sides.
        Minimum 300 DPI required; 600 DPI recommended for authentication.
      tags:
        - Images
      parameters:
        - $ref: '#/components/parameters/instanceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageUploadRequest'
            example:
              Image:
                MimeType: "image/jpeg"
                Data: "<base64-encoded-image-data>"
              Light: 0
              Side: 0
              CalculateMetrics: true
      responses:
        '200':
          description: Image submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageMetrics'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '430':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      operationId: getDocumentImage
      summary: Retrieve document images
      description: Returns document images with corrected orientation.
      tags:
        - Images
      parameters:
        - $ref: '#/components/parameters/instanceId'
      responses:
        '200':
          description: Document images
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentImage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /DocumentImageMetrics:
    get:
      operationId: getDocumentImageMetrics
      summary: Get image quality metrics
      description: Returns image quality metrics including sharpness and glare scores.
      tags:
        - Images
      responses:
        '200':
          description: Image quality metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageMetrics'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /Document/{instanceId}/Data:
    post:
      operationId: uploadDocumentData
      summary: Upload non-imaging data
      description: >-
        Uploads non-imaging data for a document instance such as magnetic
        stripe data, MRZ (machine-readable zone), or chip data.
      tags:
        - Document Data
      parameters:
        - $ref: '#/components/parameters/instanceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentDataRequest'
      responses:
        '200':
          description: Data submitted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /DocumentData:
    get:
      operationId: getDocumentData
      summary: Retrieve extracted document data
      description: Returns all extracted data fields from the document.
      tags:
        - Document Data
      responses:
        '200':
          description: Extracted document data fields
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentField'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /DocumentChipData:
    post:
      operationId: uploadDocumentChipData
      summary: Submit contactless chip data
      description: Submits contactless chip (NFC/RFID) information for a document.
      tags:
        - Chip Data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChipDataRequest'
      responses:
        '200':
          description: Chip data submitted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      operationId: getDocumentChipData
      summary: Retrieve chip authentication results
      description: Returns contactless chip authentication results.
      tags:
        - Chip Data
      responses:
        '200':
          description: Chip authentication results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChipDataResult'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /DocumentTypes:
    get:
      operationId: listDocumentTypes
      summary: List supported document types
      description: Returns the list of over 3,400 supported global document types.
      tags:
        - Metadata
      responses:
        '200':
          description: Supported document types
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentType'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /Subscriptions:
    get:
      operationId: listSubscriptions
      summary: List available subscriptions
      description: Returns available subscriptions for the authenticated account.
      tags:
        - Metadata
      responses:
        '200':
          description: Available subscriptions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /DocumentLog:
    get:
      operationId: getDocumentLog
      summary: Get transaction log
      description: Returns transaction log entries for document processing sessions.
      tags:
        - Metadata
      responses:
        '200':
          description: Transaction log entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentLogEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication. Credentials formatted as "name:password"
        and base64-encoded, transmitted via Authorization header over HTTPS.

  parameters:
    instanceId:
      name: instanceId
      in: path
      required: true
      description: Document instance GUID
      schema:
        type: string
        format: uuid

  responses:
    Unauthorized:
      description: Authentication failure
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Inactive subscription
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Duplicate submission attempt
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Validation or argument error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      type: object
      properties:
        Code:
          type: integer
          description: HTTP status code
        Message:
          type: string
          description: Error description

    DocumentCreateRequest:
      type: object
      required:
        - SubscriptionId
      properties:
        SubscriptionId:
          type: string
          format: uuid
          description: Subscription identifier for the processing request
        ImageCroppingExpectedSize:
          type: integer
          description: Expected size for image cropping (0 = auto)
          default: 0
        ImageCroppingMode:
          type: integer
          description: Cropping mode (0 = default)
          default: 0
        ManualCropCoordinates:
          type: object
          nullable: true
          description: Manual crop coordinates if applicable
        Device:
          $ref: '#/components/schemas/DeviceInfo'

    DeviceInfo:
      type: object
      properties:
        Manufacturer:
          type: string
          description: Device manufacturer name
        Model:
          type: string
          description: Device model
        SerialNumber:
          type: string
          description: Device serial number
        Type:
          $ref: '#/components/schemas/DeviceType'

    DeviceType:
      type: object
      properties:
        Manufacturer:
          type: string
        Model:
          type: string
        SensorType:
          type: integer
          description: Sensor type (0=Scanner, 1=Camera, 2=Mobile)
          enum: [0, 1, 2]

    ImageUploadRequest:
      type: object
      required:
        - Image
        - Light
        - Side
      properties:
        Image:
          $ref: '#/components/schemas/ImageData'
        Light:
          type: integer
          description: Light source type (0=Visible, 1=NearInfrared, 2=Ultraviolet, 3=Coaxial)
          enum: [0, 1, 2, 3]
        Side:
          type: integer
          description: Document side (0=Front, 1=Back)
          enum: [0, 1]
        CalculateMetrics:
          type: boolean
          description: Whether to calculate image quality metrics
          default: true

    ImageData:
      type: object
      required:
        - MimeType
        - Data
      properties:
        MimeType:
          type: string
          description: MIME type of the image
          example: image/jpeg
        Data:
          type: string
          format: byte
          description: Base64-encoded image data

    ImageMetrics:
      type: object
      properties:
        GlareMetric:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: Glare quality score (0-100)
        SharpnessMetric:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: Sharpness quality score (0-100)

    DocumentImage:
      type: object
      properties:
        GlareMetric:
          type: number
          format: float
        SharpnessMetric:
          type: number
          format: float
        Light:
          type: integer
          description: Light source used
        Side:
          type: integer
          description: Document side
        Uri:
          type: string
          format: uri
          description: URI of corrected orientation image

    DocumentDataRequest:
      type: object
      properties:
        DataType:
          type: integer
          description: Type of non-imaging data (MRZ, magnetic stripe, etc.)
        Data:
          type: string
          description: Raw data string

    DocumentField:
      type: object
      properties:
        Name:
          type: string
          description: Field name (e.g., "First Name", "Date of Birth")
        Value:
          type: string
          description: Extracted field value
        DataSource:
          type: string
          description: Source of the data extraction

    ChipDataRequest:
      type: object
      properties:
        ChipData:
          type: string
          description: NFC/RFID chip data payload

    ChipDataResult:
      type: object
      properties:
        Authenticated:
          type: boolean
          description: Whether chip authentication succeeded
        ChipFields:
          type: array
          items:
            $ref: '#/components/schemas/DocumentField'

    Document:
      type: object
      properties:
        InstanceId:
          type: string
          format: uuid
          description: Instance identifier
        Classification:
          $ref: '#/components/schemas/DocumentClassification'
        Fields:
          type: array
          items:
            $ref: '#/components/schemas/DocumentField'
        AuthenticationSensitivity:
          type: integer
          description: Authentication sensitivity level
        Images:
          type: array
          items:
            $ref: '#/components/schemas/DocumentImage'

    DocumentClassification:
      type: object
      properties:
        Type:
          $ref: '#/components/schemas/DocumentType'
        ClassificationDetails:
          type: object
          properties:
            Front:
              type: object
            Back:
              type: object

    DocumentType:
      type: object
      properties:
        Id:
          type: string
          format: uuid
        Name:
          type: string
          description: Document type name
        Class:
          type: string
          description: Document class (Identification, Passport, etc.)
        IssuerCode:
          type: string
          description: Issuing country/entity code
        IssuerName:
          type: string
          description: Issuing country/entity name
        Series:
          type: string
          description: Document series identifier

    Subscription:
      type: object
      properties:
        Id:
          type: string
          format: uuid
        Name:
          type: string
        IsActive:
          type: boolean

    DocumentLogEntry:
      type: object
      properties:
        InstanceId:
          type: string
          format: uuid
        Timestamp:
          type: string
          format: date-time
        DocumentType:
          type: string
        Status:
          type: string