openapi: 3.0.3
info:
  title: ID Analyzer Account Scanner API
  description: REST API for scanning and performing OCR on government-issued identity documents including passports, driver licenses, and national ID cards from 190+ countries. Extracts structured data fields, performs anti-forgery analysis with 20+ fraud detection models, and validates MRZ codes, holograms, and watermarks. Supports full KYC scan with biometric face verification, quick OCR scan, and very-quick OCR scan variants.
  version: '2.0'
  contact:
    name: ID Analyzer Support
    url: https://www.idanalyzer.com/contact-us
    email: support@idanalyzer.com
  termsOfService: https://www.idanalyzer.com/en/terms-of-service
  license:
    name: Proprietary
    url: https://www.idanalyzer.com
servers:
- url: https://api2.idanalyzer.com
  description: US Region
- url: https://api2-eu.idanalyzer.com
  description: EU Region
security:
- ApiKeyHeader: []
tags:
- name: Scanner
  description: Document scanning and OCR operations
paths:
  /scan:
    post:
      tags:
      - Scanner
      operationId: scan
      summary: Full KYC document scan
      description: Initiate a new identity document scan and ID face verification transaction by providing input images. Performs OCR extraction, anti-forgery analysis, biometric face match, and produces a KYC decision (accept/review/reject). Requires a KYC profile to be specified.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanRequest'
      responses:
        '200':
          description: Scan result with extracted data and KYC decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /quickscan:
    post:
      tags:
      - Scanner
      operationId: quickScan
      summary: Quick OCR document scan
      description: Initiate a quick identity document OCR scan by providing input images. Returns extracted document data without full fraud analysis. Optionally caches images for 24 hours for subsequent full scans.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuickScanRequest'
      responses:
        '200':
          description: Quick scan result with extracted OCR data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuickScanResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /veryquickscan:
    post:
      tags:
      - Scanner
      operationId: veryQuickScan
      summary: Very quick OCR document scan
      description: Initiate a very quick (fast) identity document OCR scan. Faster but less thorough than quickScan, useful for high-throughput OCR-only use cases. Optionally caches images for 24 hours.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuickScanRequest'
      responses:
        '200':
          description: Very quick scan result with extracted OCR data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuickScanResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    QuickScanRequest:
      type: object
      required:
      - document
      properties:
        document:
          type: string
          description: Front of document image (file path, base64, or URL)
        documentBack:
          type: string
          description: Back of document image (file path, base64, or URL)
        saveFile:
          type: boolean
          description: Cache uploaded images for 24 hours and return a cache reference
          default: false
    ScanResponse:
      type: object
      properties:
        decision:
          type: string
          enum:
          - accept
          - review
          - reject
          description: Final KYC decision
        transactionId:
          type: string
          description: Unique transaction identifier
        data:
          type: object
          description: Extracted document data fields
          additionalProperties: true
        warning:
          type: array
          description: List of validation warnings
          items:
            type: object
            properties:
              code:
                type: string
              description:
                type: string
              confidence:
                type: number
        outputImage:
          type: string
          description: Cropped/processed document image (URL or base64)
        outputImageBack:
          type: string
          description: Cropped/processed document back image (URL or base64)
        faceMatch:
          type: object
          description: Face match result (if face image was provided)
          properties:
            confidence:
              type: number
            decision:
              type: string
        error:
          $ref: '#/components/schemas/ErrorObject'
    QuickScanResponse:
      type: object
      properties:
        data:
          type: object
          description: Extracted document OCR data fields
          additionalProperties: true
        reference:
          type: object
          description: Cache references for uploaded images (if saveFile=true)
          properties:
            document:
              type: string
            documentBack:
              type: string
        error:
          $ref: '#/components/schemas/ErrorObject'
    ErrorObject:
      type: object
      properties:
        code:
          type: integer
          description: Error code
        message:
          type: string
          description: Human-readable error message
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    ScanRequest:
      type: object
      required:
      - document
      - profile
      properties:
        document:
          type: string
          description: Front of document image. Accepts a file path, base64-encoded image content, URL, or cache reference (ref:...).
        documentBack:
          type: string
          description: Back of document image (file path, base64, URL, or cache reference)
        face:
          type: string
          description: Selfie face photo (file path, base64, URL, or cache reference)
        faceVideo:
          type: string
          description: Selfie face video (file path, base64, or URL). Used if face is empty.
        profile:
          type: string
          description: KYC Profile ID or preset profile name (security_none, security_low, security_medium, security_high)
          example: security_medium
        profileOverride:
          type: object
          description: Per-request overrides applied on top of the specified profile
          additionalProperties: true
        verifyName:
          type: string
          description: Full name to verify against the document
        verifyDob:
          type: string
          description: Date of birth to verify (YYYY/MM/DD)
          pattern: ^\d{4}/\d{2}/\d{2}$
        verifyAge:
          type: string
          description: Age range to verify (e.g. "18-40")
          pattern: ^\d+-\d+$
        verifyAddress:
          type: string
          description: Address to verify against the document
        verifyPostcode:
          type: string
          description: Postcode to verify against the document
        verifyDocumentNumber:
          type: string
          description: Document or ID number to verify
        restrictCountry:
          type: string
          description: Comma-separated ISO ALPHA-2 country codes. Only accept documents from these countries (e.g. "US,CA,UK")
        restrictState:
          type: string
          description: Comma-separated state names or abbreviations. Only accept documents from these states (e.g. "CA,TX")
        restrictType:
          type: string
          description: 'Accepted document types: P=Passport, D=Driver''s License, I=Identity Card (e.g. "DIP" for all three)'
        contractGenerate:
          type: string
          description: Up to 5 contract template IDs (comma-separated) for auto-generation
        contractFormat:
          type: string
          description: Contract output format
          enum:
          - PDF
          - DOCX
          - HTML
          default: PDF
        contractPrefill:
          type: object
          description: Key-value pairs to prefill contract template dynamic fields
          additionalProperties: true
        ip:
          type: string
          description: User IP address for country cross-check
        customData:
          type: string
          description: Arbitrary string to store alongside the transaction
        client:
          type: string
          description: Client library identifier (set automatically by SDKs)
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key obtained from portal2.idanalyzer.com