Smile Identity Smart Selfie Compare API

openapi: 3.0.3
info:
  title: Smile ID V3 Authentication Smart Selfie Compare API
  version: 1.0.0
  description: 'Smile ID V3 identity verification API for Africa: Biometric KYC, Document Verification, Enhanced KYC/Doc Verification, SmartSelfie enrollment/authentication/compare, plus core service and user resources. Assembled verbatim from the per-endpoint OpenAPI fragments published in the Smile ID GitBook API reference (docs.usesmileid.com/api-reference).'
  contact:
    name: Smile ID Support
    url: https://docs.usesmileid.com/
  x-logo:
    url: https://smileidentity.com
servers:
- url: https://api.smileidentity.com
  description: Production
- url: https://api.sandbox.smileidentity.com
  description: Sandbox
security:
- SmileIDToken: []
tags:
- name: Smart Selfie Compare
paths:
  /v3/compare:
    post:
      summary: Submit smart selfie compare
      operationId: v3SmartSelfieCompare
      tags:
      - Smart Selfie Compare
      description: 'Compares a selfie image against a provided comparison image (document, ID photo, or portrait). The images are uploaded, validated at entry, then queued for async ML processing (passive liveness, face matching, optional active liveness with liveness images). Results are delivered via callback URL.

        If `user_id` is provided and the comparison passes, the user will be enrolled.'
      parameters:
      - name: SmileID-Source-SDK
        in: header
        required: false
        description: Source SDK identifier.
        schema:
          type: string
      - name: SmileID-Source-SDK-Version
        in: header
        required: false
        description: Source SDK version.
        schema:
          type: string
      - name: SmileID-Timestamp
        in: header
        required: false
        description: ISO 8601 timestamp used as the salt when computing SmileID-Request-Signature.
        schema:
          type: string
          format: date-time
      - name: SmileID-Request-Signature
        in: header
        required: false
        description: HMAC signature of the raw HTTP request body.
        schema:
          type: string
      - name: User-ID
        in: header
        required: false
        description: Partner-provided user identifier. If omitted, a TypeID is generated automatically.
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SmartSelfieCompareRequest'
            encoding:
              selfie_image:
                contentType: image/jpeg
              comparison_image:
                contentType: image/jpeg
              liveness_images:
                contentType: image/jpeg
      responses:
        '202':
          description: Accepted — job queued for async processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
        '400':
          description: Bad Request — validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required — insufficient wallet balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — partner not authorized for this product or IP.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Unsupported Media Type — request must be multipart/form-data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests — rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Consent:
      type: object
      required:
      - granted
      - granted_at
      - notice_language
      - notice_privacy_policy_url
      properties:
        granted:
          type: boolean
          enum:
          - true
        granted_at:
          type: string
          format: date-time
        notice_language:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z]{2}$
        notice_privacy_policy_url:
          type: string
          format: uri
    AcceptedResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - Accepted
        message:
          type: string
        job_id:
          type: string
        user_id:
          type: string
        created_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
      - status
      - message
      properties:
        status:
          type: string
          description: HTTP status text.
        message:
          type: string
          description: Human-readable error message.
    SmartSelfieCompareRequest:
      type: object
      required:
      - selfie_image
      - comparison_image
      - comparison_image_type
      - consent
      - user_details
      properties:
        selfie_image:
          type: string
          format: binary
          description: JPEG selfie image.
        comparison_image:
          type: string
          format: binary
          description: JPEG comparison image (ID card photo, ID photo, or portrait).
        comparison_image_type:
          type: string
          enum:
          - DOCUMENT
          - ID_PHOTO
          - PORTRAIT
          description: Type of comparison image being submitted.
        consent:
          $ref: '#/components/schemas/Consent'
        user_details:
          type: object
          required:
          - given_names
          - last_name
          description: Consumer-stated PII fields for the user. Either email or phone_number must be provided.
          properties:
            given_names:
              type: string
              minLength: 1
            last_name:
              type: string
              minLength: 1
            email:
              type: string
              format: email
              nullable: true
              description: At least one of email or phone_number is required.
            phone_number:
              type: string
              pattern: ^\+[1-9]\d{6,14}$
              nullable: true
              description: Phone number in E.164 format. At least one of email or phone_number is required.
        liveness_images:
          type: array
          minItems: 6
          maxItems: 8
          items:
            type: string
            format: binary
          description: Optional array of JPEG liveness images. If omitted, active liveness check is skipped.
        allow_new_enroll:
          type: boolean
          default: false
          description: If true, allows re-enrollment for a user who is already enrolled.
        user_id:
          type: string
          description: Optional user identifier. If provided and the job passes, the user will be enrolled.
        callback_url:
          type: string
          format: uri
          description: URL to receive the async result callback.
        sandbox_result:
          type: number
          description: Force a specific result code in sandbox mode.
        partner_params:
          type: object
          additionalProperties:
            type: string
        metadata:
          type: array
          items:
            type: object
            required:
            - name
            - value
            properties:
              name:
                type: string
                maxLength: 100
              value:
                type: string
                maxLength: 1000
  securitySchemes:
    SmileIDToken:
      type: apiKey
      in: header
      name: SmileID-Token
      description: JWT token obtained from `POST /v3/token`.