openapi: 3.0.0
info:
  contact:
    name: Onfido
    url: https://public.support.onfido.com
  description: "\nCreate trust at onboarding and beyond with a complete, AI-powered digital\nidentity solution built to help you know your customers online. \nAutomation allows you to acquire new customers and reduce costs while\nmeeting global KYC and AML compliance."
  license:
    name: MIT
  title: Onfido Live API
  version: v3.6
servers:
- url: https://api.{region}.onfido.com/v3.6
  variables:
    region:
      default: eu
      enum:
      - eu
      - us
      - ca
security:
- Token: []
tags:
- name: Live
paths:
  /live_photos:
    get:
      description: 'Lists the live photos that belong to an applicant.

        '
      operationId: list_live_photos
      parameters:
      - description: The id of the applicant the live photos belong to.
        in: query
        name: applicant_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Live_Photos_list'
          description: An array of live photos
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: List live photos
      tags:
      - Live
    post:
      description: 'You can upload live photos to this endpoint. Like document upload, files must be uploaded as a multipart form. Valid file types are jpg, png and pdf. The file size must be between 32KB and 10MB. Live photos are validated at the point of upload to check that they contain exactly one face. This validation can be disabled by setting the advanced_validation argument to false.

        '
      operationId: upload_live_photo
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/live_photo_uploader'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/live_photo'
          description: The Live Photo
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Upload live photo
      tags:
      - Live
  /live_photos/{live_photo_id}:
    get:
      description: 'Retrieves a single live photo. Returns a live photo object.

        '
      operationId: find_live_photo
      parameters:
      - description: The live photo's unique identifier.
        in: path
        name: live_photo_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/live_photo'
          description: A live photo
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Retrieve live photo
      tags:
      - Live
  /live_photos/{live_photo_id}/download:
    get:
      description: Live photos are downloaded using this endpoint.
      operationId: download_live_photo
      parameters:
      - description: The live photo's unique identifier.
        in: path
        name: live_photo_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            '*/*':
              schema:
                format: binary
                type: string
          description: The live photo's binary data.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Download live photo
      tags:
      - Live
  /live_videos:
    get:
      description: 'Lists all the live videos that belong to an applicant.

        '
      operationId: list_live_videos
      parameters:
      - description: The id of the applicant the live videos belong to.
        in: query
        name: applicant_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Live_Videos_list'
          description: An array of live videos
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: List live videos
      tags:
      - Live
  /live_videos/{live_video_id}:
    get:
      description: 'Retrieves a single live video. Returns the corresponding live video object.

        '
      operationId: find_live_video
      parameters:
      - description: The live video's unique identifier.
        in: path
        name: live_video_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/live_video'
          description: A live video
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Retrieve live video
      tags:
      - Live
  /live_videos/{live_video_id}/download:
    get:
      description: Live videos are downloaded using this endpoint.
      operationId: download_live_video
      parameters:
      - description: The live video's unique identifier.
        in: path
        name: live_video_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            '*/*':
              schema:
                format: binary
                type: string
          description: The live video's binary data.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Download live video
      tags:
      - Live
  /live_videos/{live_video_id}/frame:
    get:
      description: Returns the binary data representing a single frame from a live video.
      operationId: download_live_video_frame
      parameters:
      - description: The live video's unique identifier.
        in: path
        name: live_video_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            '*/*':
              schema:
                format: binary
                type: string
          description: The live video frame's binary data.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Download live video frame
      tags:
      - Live
components:
  schemas:
    ErrorProperties:
      example:
        type: type
        message: message
        fields:
          key: ''
      properties:
        type:
          type: string
        message:
          type: string
        fields:
          additionalProperties: true
          type: object
      title: ErrorProperties
      type: object
    live_photo_request:
      properties:
        applicant_id:
          description: The ID of the applicant whose live photo is being uploaded.
          format: uuid
          type: string
        file:
          description: The file to be uploaded.
          format: binary
          type: string
        advanced_validation:
          default: true
          description: Validates that the live photo contains exactly one face.
          type: boolean
      type: object
    Live_Photos_list:
      example:
        live_photos:
        - download_href: download_href
          file_name: file_name
          file_type: file_type
          created_at: '2000-01-23T04:56:07.000Z'
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          href: href
          file_size: 0
        - download_href: download_href
          file_name: file_name
          file_type: file_type
          created_at: '2000-01-23T04:56:07.000Z'
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          href: href
          file_size: 0
      properties:
        live_photos:
          items:
            $ref: '#/components/schemas/live_photo'
          type: array
      required:
      - live_photos
      title: Live Photos list
      type: object
    live_photo_uploader:
      allOf:
      - $ref: '#/components/schemas/live_photo_request'
      required:
      - applicant_id
      - file
    Error:
      example:
        error:
          type: type
          message: message
          fields:
            key: ''
      properties:
        error:
          $ref: '#/components/schemas/ErrorProperties'
      title: Error
      type: object
    live_photo_response:
      properties:
        id:
          description: The unique identifier for the photo.
          format: uuid
          type: string
        created_at:
          description: The date and time at which the photo was uploaded.
          format: date-time
          type: string
        href:
          description: The uri of this resource.
          type: string
        download_href:
          description: The uri that can be used to download the photo.
          type: string
        file_name:
          description: The name of the uploaded file.
          type: string
        file_type:
          description: The file type of the uploaded file.
          type: string
        file_size:
          description: The size of the file in bytes.
          type: integer
      required:
      - id
      type: object
    live_photo:
      allOf:
      - $ref: '#/components/schemas/live_photo_response'
      example:
        download_href: download_href
        file_name: file_name
        file_type: file_type
        created_at: '2000-01-23T04:56:07.000Z'
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        href: href
        file_size: 0
    live_video:
      example:
        download_href: download_href
        file_name: file_name
        file_type: file_type
        created_at: '2000-01-23T04:56:07.000Z'
        challenge:
        - key: ''
        - key: ''
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        href: href
        file_size: 0
      properties:
        id:
          description: The unique identifier for the video.
          format: uuid
          type: string
        created_at:
          description: The date and time at which the video was uploaded.
          format: date-time
          type: string
        href:
          description: The uri of this resource.
          type: string
        download_href:
          description: The uri that can be used to download the video.
          type: string
        file_name:
          description: The name of the uploaded file.
          type: string
        file_size:
          description: The size of the file in bytes.
          type: integer
        file_type:
          description: The file type of the uploaded file.
          type: string
        challenge:
          description: Challenge the end user was asked to perform during the video recording.
          items:
            additionalProperties: true
            type: object
          type: array
      type: object
    Live_Videos_list:
      example:
        live_videos:
        - download_href: download_href
          file_name: file_name
          file_type: file_type
          created_at: '2000-01-23T04:56:07.000Z'
          challenge:
          - key: ''
          - key: ''
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          href: href
          file_size: 0
        - download_href: download_href
          file_name: file_name
          file_type: file_type
          created_at: '2000-01-23T04:56:07.000Z'
          challenge:
          - key: ''
          - key: ''
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          href: href
          file_size: 0
      properties:
        live_videos:
          items:
            $ref: '#/components/schemas/live_video'
          type: array
      required:
      - live_videos
      title: Live Videos list
      type: object
  securitySchemes:
    Token:
      in: header
      name: Authorization
      type: apiKey
externalDocs:
  url: https://documentation.onfido.com