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 Applicants 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: Applicants
paths:
  /applicants:
    get:
      description: 'Lists all applicants you''ve created, sorted by creation date in descending order.

        '
      operationId: list_applicants
      parameters:
      - description: The page to return. The first page is `page=1`
        in: query
        name: page
        schema:
          default: 1
          type: integer
      - description: The number of objects per page.
        in: query
        name: per_page
        schema:
          default: 20
          type: integer
      - description: Whether to also include applicants scheduled for deletion.
        in: query
        name: include_deleted
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Applicants_list'
          description: A list of applicants
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: List Applicants
      tags:
      - Applicants
    post:
      description: 'Creates a single applicant. Returns an applicant object.

        '
      operationId: create_applicant
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/applicant_builder'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/applicant'
          description: Created
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Create Applicant
      tags:
      - Applicants
  /applicants/{applicant_id}:
    delete:
      description: 'Deletes a single applicant.

        '
      operationId: delete_applicant
      parameters:
      - in: path
        name: applicant_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Delete Applicant
      tags:
      - Applicants
    get:
      description: 'Retrieves a single applicant. Returns an applicant object.

        '
      operationId: find_applicant
      parameters:
      - in: path
        name: applicant_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/applicant'
          description: Applicant object
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Retrieve Applicant
      tags:
      - Applicants
    put:
      description: 'Allows updating applicant''s information before any checks is created.

        - Partial updates - Addresses and ID numbers present will replace existing ones - Same applicant validations to create applicant

        '
      operationId: update_applicant
      parameters:
      - in: path
        name: applicant_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/applicant_updater'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/applicant'
          description: Applicant Object
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Update Applicant
      tags:
      - Applicants
  /applicants/{applicant_id}/restore:
    post:
      description: 'Restores a single applicant scheduled for deletion.

        '
      operationId: restore_applicant
      parameters:
      - in: path
        name: applicant_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Restore Applicant
      tags:
      - Applicants
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
    address_builder:
      allOf:
      - $ref: '#/components/schemas/address_shared'
    applicant_updater:
      allOf:
      - $ref: '#/components/schemas/applicant_shared'
      - $ref: '#/components/schemas/applicant_request'
      - $ref: '#/components/schemas/applicant_update'
    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
    applicant:
      allOf:
      - $ref: '#/components/schemas/applicant_shared'
      - $ref: '#/components/schemas/applicant_response'
      example:
        address:
          building_name: building_name
          country: country
          town: town
          flat_number: flat_number
          street: street
          postcode: postcode
          state: state
          line3: line3
          line2: line2
          building_number: building_number
          line1: line1
          sub_street: sub_street
        sandbox: true
        last_name: last_name
        created_at: '2000-01-23T04:56:07.000Z'
        id_numbers:
        - type: ssn
          state_code: state_code
          value: value
        - type: ssn
          state_code: state_code
          value: value
        dob: '2000-01-23T00:00:00.000Z'
        delete_at: '2000-01-23T04:56:07.000Z'
        phone_number: phone_number
        location:
          country_of_residence: GBR
          ip_address: ip_address
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        href: href
        first_name: first_name
        email: email
    applicant_create:
      properties:
        first_name:
          description: The applicant's first name
          pattern: ^[^!#$%*=<>;{}"]*$
          type: string
        last_name:
          description: The applicant's surname
          pattern: ^[^!#$%*=<>;{}"]*$
          type: string
      required:
      - first_name
      - last_name
    applicant_update:
      properties:
        first_name:
          description: The applicant's first name
          pattern: ^[^!#$%*=<>;{}"]*$
          type: string
        last_name:
          description: The applicant's surname
          pattern: ^[^!#$%*=<>;{}"]*$
          type: string
    applicant_request:
      properties:
        consents:
          description: The applicant's consents
          items:
            $ref: '#/components/schemas/applicant_consent_builder'
          type: array
        address:
          $ref: '#/components/schemas/address_builder'
        location:
          $ref: '#/components/schemas/location_builder'
      type: object
    Applicants_list:
      example:
        applicants:
        - address:
            building_name: building_name
            country: country
            town: town
            flat_number: flat_number
            street: street
            postcode: postcode
            state: state
            line3: line3
            line2: line2
            building_number: building_number
            line1: line1
            sub_street: sub_street
          sandbox: true
          last_name: last_name
          created_at: '2000-01-23T04:56:07.000Z'
          id_numbers:
          - type: ssn
            state_code: state_code
            value: value
          - type: ssn
            state_code: state_code
            value: value
          dob: '2000-01-23T00:00:00.000Z'
          delete_at: '2000-01-23T04:56:07.000Z'
          phone_number: phone_number
          location:
            country_of_residence: GBR
            ip_address: ip_address
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          href: href
          first_name: first_name
          email: email
        - address:
            building_name: building_name
            country: country
            town: town
            flat_number: flat_number
            street: street
            postcode: postcode
            state: state
            line3: line3
            line2: line2
            building_number: building_number
            line1: line1
            sub_street: sub_street
          sandbox: true
          last_name: last_name
          created_at: '2000-01-23T04:56:07.000Z'
          id_numbers:
          - type: ssn
            state_code: state_code
            value: value
          - type: ssn
            state_code: state_code
            value: value
          dob: '2000-01-23T00:00:00.000Z'
          delete_at: '2000-01-23T04:56:07.000Z'
          phone_number: phone_number
          location:
            country_of_residence: GBR
            ip_address: ip_address
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          href: href
          first_name: first_name
          email: email
      properties:
        applicants:
          items:
            $ref: '#/components/schemas/applicant'
          type: array
      required:
      - applicants
      title: Applicants list
      type: object
    id_number:
      example:
        type: ssn
        state_code: state_code
        value: value
      properties:
        type:
          description: Type of ID number.
          enum:
          - ssn
          - social_insurance
          - tax_id
          - identity_card
          - driving_licence
          - share_code
          - voter_id
          - passport
          - other
          type: string
        value:
          description: Value of ID number
          type: string
        state_code:
          description: Two letter code of issuing state (state-issued driving licenses only)
          type: string
      type: object
    location:
      allOf:
      - $ref: '#/components/schemas/location_shared'
      example:
        country_of_residence: GBR
        ip_address: ip_address
    applicant_consent_name:
      enum:
      - privacy_notices_read
      - ssn_verification
      - phone_number_verification
      type: string
    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
    address:
      allOf:
      - $ref: '#/components/schemas/address_shared'
      example:
        building_name: building_name
        country: country
        town: town
        flat_number: flat_number
        street: street
        postcode: postcode
        state: state
        line3: line3
        line2: line2
        building_number: building_number
        line1: line1
        sub_street: sub_street
    applicant_builder:
      allOf:
      - $ref: '#/components/schemas/applicant_shared'
      - $ref: '#/components/schemas/applicant_request'
      - $ref: '#/components/schemas/applicant_create'
    location_builder:
      allOf:
      - $ref: '#/components/schemas/location_shared'
    address_shared:
      properties:
        flat_number:
          description: The flat number of this address
          type: string
        building_number:
          description: The building number of this address
          type: string
        building_name:
          description: The building name of this address
          type: string
        street:
          description: The street of the applicant's address
          type: string
        sub_street:
          description: The sub-street of the applicant's address
          type: string
        town:
          description: The town of the applicant's address
          type: string
        postcode:
          description: The postcode or ZIP of the applicant's address
          type: string
        country:
          allOf:
          - $ref: '#/components/schemas/country_codes'
          description: The 3 character ISO country code of this address. For example, GBR is the country code for the United Kingdom
          type: string
        state:
          description: The address state. US states must use the USPS abbreviation (see also ISO 3166-2:US), for example AK, CA, or TX.
          type: string
        line1:
          description: Line 1 of the applicant's address
          nullable: true
          pattern: ^[^!$%^*=<>]*$
          type: string
        line2:
          description: Line 2 of the applicant's address
          nullable: true
          pattern: ^[^!$%^*=<>]*$
          type: string
        line3:
          description: Line 3 of the applicant's address
          nullable: true
          pattern: ^[^!$%^*=<>]*$
          type: string
      required:
      - country
      - postcode
      type: object
    applicant_shared:
      properties:
        email:
          description: The applicant's email address. Required if doing a US check, or a UK check for which `applicant_provides_data` is `true`.
          type: string
        dob:
          description: The applicant's date of birth
          format: date
          type: string
        id_numbers:
          items:
            $ref: '#/components/schemas/id_number'
          type: array
        phone_number:
          description: The applicant's phone number
          type: string
      type: object
    applicant_response:
      properties:
        first_name:
          description: The applicant's first name
          pattern: ^[^!#$%*=<>;{}"]*$
          type: string
        last_name:
          description: The applicant's surname
          pattern: ^[^!#$%*=<>;{}"]*$
          type: string
        id:
          description: The unique identifier for the applicant.
          format: uuid
          type: string
        created_at:
          description: The date and time when this applicant was created.
          format: date-time
          type: string
        delete_at:
          description: The date and time when this applicant is scheduled to be deleted.
          format: date-time
          type: string
        href:
          description: The uri of this resource.
          type: string
        sandbox:
          type: boolean
        address:
          $ref: '#/components/schemas/address'
        location:
          $ref: '#/components/schemas/location'
      required:
      - id
      type: object
    Error:
      example:
        error:
          type: type
          message: message
          fields:
            key: ''
      properties:
        error:
          $ref: '#/components/schemas/ErrorProperties'
      title: Error
      type: object
    applicant_consent_builder:
      properties:
        name:
          $ref: '#/components/schemas/applicant_consent_name'
        granted:
          type: boolean
      required:
      - granted
      - name
      type: object
  securitySchemes:
    Token:
      in: header
      name: Authorization
      type: apiKey
externalDocs:
  url: https://documentation.onfido.com