Onfido Documents API

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 Documents 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: Documents
paths:
  /documents:
    get:
      description: All documents belonging to an applicant can be listed from this endpoint
      operationId: list_documents
      parameters:
      - in: query
        name: applicant_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Documents_list'
          description: List of Documents
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: List documents
      tags:
      - Documents
    post:
      description: 'Documents are uploaded using this endpoint. Along with the file upload the relevant document type must be specified. Documents must be uploaded as a multipart form. The valid file types are: jpg, png and pdf. The file size must be between 2KB and 3MB.

        '
      operationId: upload_document
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/document_uploader'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/document'
          description: A document
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Upload a document
      tags:
      - Documents
  /documents/{document_id}:
    get:
      description: 'A single document can be retrieved by calling this endpoint with the document''s unique identifier.

        '
      operationId: find_document
      parameters:
      - in: path
        name: document_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/document'
          description: A document
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Retrieve document
      tags:
      - Documents
  /documents/{document_id}/download:
    get:
      description: 'Downloads specific documents belonging to an applicant. If successful, the response will be the binary data representing the image.

        '
      operationId: download_document
      parameters:
      - in: path
        name: document_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            '*/*':
              schema:
                format: binary
                type: string
          description: The document binary data
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Download document
      tags:
      - Documents
  /documents/{document_id}/video/download:
    get:
      description: 'Downloads a document video. If successful, the response will be the binary data representing the video.

        '
      operationId: download_document_video
      parameters:
      - in: path
        name: document_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            '*/*':
              schema:
                format: binary
                type: string
          description: The document's video binary data
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Download document video
      tags:
      - Documents
  /qualified_electronic_signature/documents:
    get:
      description: 'Retrieves the signed document or application form depending on the file_id provided.

        '
      operationId: download_qes_document
      parameters:
      - description: The unique identifier of the Workflow Run for which you want to retrieve the signed document.
        in: query
        name: workflow_run_id
        required: true
        schema:
          format: uuid
          type: string
      - description: The unique identifier of the file which you want to retrieve.
        in: query
        name: file_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/pdf:
              schema:
                format: binary
                type: string
          description: The signed document PDF binary data.
        '302':
          description: Found
          headers:
            Location:
              description: Pre-signed URL to download the file.
              schema:
                format: uri
                type: string
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Retrieves the signed document or application form
      tags:
      - Documents
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
    location_shared:
      properties:
        ip_address:
          description: The applicant's ip address.
          type: string
        country_of_residence:
          allOf:
          - $ref: '#/components/schemas/country_codes'
          description: The applicant's country of residence in 3-letter ISO code.
          example: GBR
      type: object
    document_uploader:
      allOf:
      - $ref: '#/components/schemas/document_shared'
      - $ref: '#/components/schemas/document_request'
      required:
      - applicant_id
      - file
      - type
    document_response:
      properties:
        id:
          description: The unique identifier for the document
          format: uuid
          type: string
        created_at:
          description: The date and time at which the document 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 document
          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
      required:
      - id
      type: object
    country_codes:
      enum:
      - ABW
      - AFG
      - AGO
      - AIA
      - ALA
      - ALB
      - AND
      - ARE
      - ARG
      - ARM
      - ASM
      - ATA
      - ATF
      - ATG
      - AUS
      - AUT
      - AZE
      - BDI
      - BEL
      - BEN
      - BES
      - BFA
      - BGD
      - BGR
      - BHR
      - BHS
      - BIH
      - BLM
      - BLR
      - BLZ
      - BMU
      - BOL
      - BRA
      - BRB
      - BRN
      - BTN
      - BVT
      - BWA
      - CAF
      - CAN
      - CCK
      - CHE
      - CHL
      - CHN
      - CIV
      - CMR
      - COD
      - COG
      - COK
      - COL
      - COM
      - CPV
      - CRI
      - CUB
      - CUW
      - CXR
      - CYM
      - CYP
      - CZE
      - DEU
      - DJI
      - DMA
      - DNK
      - DOM
      - DZA
      - ECU
      - EGY
      - ERI
      - ESH
      - ESP
      - EST
      - ETH
      - FIN
      - FJI
      - FLK
      - FRA
      - FRO
      - FSM
      - GAB
      - GBR
      - GEO
      - GGY
      - GHA
      - GIB
      - GIN
      - GLP
      - GMB
      - GNB
      - GNQ
      - GRC
      - GRD
      - GRL
      - GTM
      - GUF
      - GUM
      - GUY
      - HKG
      - HMD
      - HND
      - HRV
      - HTI
      - HUN
      - IDN
      - IMN
      - IND
      - IOT
      - IRL
      - IRN
      - IRQ
      - ISL
      - ISR
      - ITA
      - JAM
      - JEY
      - JOR
      - JPN
      - KAZ
      - KEN
      - KGZ
      - KHM
      - KIR
      - KNA
      - KOR
      - KWT
      - LAO
      - LBN
      - LBR
      - LBY
      - LCA
      - LIE
      - LKA
      - LSO
      - LTU
      - LUX
      - LVA
      - MAC
      - MAF
      - MAR
      - MCO
      - MDA
      - MDG
      - MDV
      - MEX
      - MHL
      - MKD
      - MLI
      - MLT
      - MMR
      - MNE
      - MNG
      - MNP
      - MOZ
      - MRT
      - MSR
      - MTQ
      - MUS
      - MWI
      - MYS
      - MYT
      - NAM
      - NCL
      - NER
      - NFK
      - NGA
      - NIC
      - NIU
      - NLD
      - NOR
      - NPL
      - NRU
      - NZL
      - OMN
      - PAK
      - PAN
      - PCN
      - PER
      - PHL
      - PLW
      - PNG
      - POL
      - PRI
      - PRK
      - PRT
      - PRY
      - PSE
      - PYF
      - QAT
      - REU
      - RKS
      - ROU
      - RUS
      - RWA
      - SAU
      - SDN
      - SEN
      - SGP
      - SGS
      - SHN
      - SJM
      - SLB
      - SLE
      - SLV
      - SMR
      - SOM
      - SPM
      - SRB
      - SSD
      - STP
      - SUR
      - SVK
      - SVN
      - SWE
      - SWZ
      - SXM
      - SYC
      - SYR
      - TCA
      - TCD
      - TGO
      - THA
      - TJK
      - TKL
      - TKM
      - TLS
      - TON
      - TTO
      - TUN
      - TUR
      - TUV
      - TWN
      - TZA
      - UGA
      - UKR
      - UMI
      - URY
      - USA
      - UZB
      - VAT
      - VCT
      - VEN
      - VGB
      - VIR
      - VNM
      - VUT
      - WLF
      - WSM
      - YEM
      - ZAF
      - ZMB
      - ZWE
      type: string
    document_request:
      properties:
        file:
          description: The file to be uploaded.
          format: binary
          type: string
        validate_image_quality:
          description: Defaults to false. When true the submitted image will undergo an image quality validation which may take up to 5 seconds.
          type: boolean
        location:
          $ref: '#/components/schemas/location_builder'
      type: object
    Error:
      example:
        error:
          type: type
          message: message
          fields:
            key: ''
      properties:
        error:
          $ref: '#/components/schemas/ErrorProperties'
      title: Error
      type: object
    document_types:
      enum:
      - passport
      - driving_licence
      - national_identity_card
      - residence_permit
      - passport_card
      - tax_id
      - visa
      - voter_id
      - residence_status_document
      - postal_identity_card
      - social_security_card
      - work_permit
      - asylum_registration_card
      - national_health_insurance_card
      - municipality_identity_card
      - private_operators_card
      - proof_of_citizenship
      - service_id_card
      - immigration_status_document
      - indigenous_card
      - vehicle_registration_card
      - certificate_of_naturalisation
      - professional_qualification_card
      - consular_id
      - international_driving_licence
      - home_office_letter
      - birth_certificate
      - vehicle_registration_certificate
      - form_for_affixing_the_visa
      - identification_number_document
      - adoption_certificate
      - bank_building_society_statement
      - bank_statement
      - benefit_letters
      - cbt
      - certificate_of_sponsorship
      - character_reference
      - civil_partnership_certificate
      - council_tax
      - credit_card_statement
      - deed_poll
      - divorce_absolute_decree
      - educational_statement
      - electricity_bill
      - gas_bill
      - government_letter
      - internet_bill
      - marriage_certificate
      - motorcycle_insurance
      - national_insurance_card
      - naturalisation_certificate
      - non_uk_driving_licence
      - p45_p60
      - payslip
      - phone_bill
      - professional_identification_card
      - right_to_work_share_code_result
      - statement_fact
      - t4_student_university_term_dates_evidence
      - uk_biometric_residence_permit
      - uk_driving_licence
      - unknown
      - utility_bill
      - utility_bill_electric
      - utility_bill_gas
      - utility_bill_other
      - water_bill
      - address_certificate
      - general_letter
      - insurance_statement
      - pension_property_statement_letter
      - mortgage_statement
      - mobile_phone_bill
      - identity_document_with_address
      - exchange_house_statement
      - accommodation_tenancy_certificate
      type: string
    document:
      allOf:
      - $ref: '#/components/schemas/document_shared'
      - $ref: '#/components/schemas/document_response'
      example:
        side: front
        download_href: download_href
        applicant_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        issuing_country: issuing_country
        file_type: jpg
        file_name: file_name
        created_at: '2000-01-23T04:56:07.000Z'
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        href: href
        type: type
        file_size: 0
    location_builder:
      allOf:
      - $ref: '#/components/schemas/location_shared'
    Documents_list:
      example:
        documents:
        - side: front
          download_href: download_href
          applicant_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          issuing_country: issuing_country
          file_type: jpg
          file_name: file_name
          created_at: '2000-01-23T04:56:07.000Z'
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          href: href
          type: type
          file_size: 0
        - side: front
          download_href: download_href
          applicant_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          issuing_country: issuing_country
          file_type: jpg
          file_name: file_name
          created_at: '2000-01-23T04:56:07.000Z'
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          href: href
          type: type
          file_size: 0
      properties:
        documents:
          items:
            $ref: '#/components/schemas/document'
          type: array
      required:
      - documents
      title: Documents list
      type: object
    document_shared:
      properties:
        file_type:
          description: The file type of the uploaded file
          enum:
          - jpg
          - jpeg
          - png
          - pdf
          type: string
        type:
          allOf:
          - $ref: '#/components/schemas/document_types'
          description: The type of document
          type: string
        side:
          description: The side of the document, if applicable. The possible values are front and back
          enum:
          - front
          - back
          type: string
        issuing_country:
          allOf:
          - $ref: '#/components/schemas/country_codes'
          description: The issuing country of the document, a 3-letter ISO code.
          type: string
        applicant_id:
          description: The ID of the applicant whose document is being uploaded.
          format: uuid
          type: string
      type: object
  securitySchemes:
    Token:
      in: header
      name: Authorization
      type: apiKey
externalDocs:
  url: https://documentation.onfido.com