openapi: 3.1.0
info:
  title: Overview
  version: '1.0'
  termsOfService: https://kycaid.com/terms-and-conditions/
servers:
  - url: https://api.kycaid.com
components:
  securitySchemes:
    your_api_key:
      type: apiKey
      in: header
      name: Authorization
  schemas:
    '400':
      type: object
      properties:
        type:
          type: string
          example: bad_request
        errors:
          type: array
    '429':
      type: object
      properties:
        type:
          type: string
          example: flow
        errors:
          type: array
          items:
            type: object
            properties:
              parameter:
                type: string
                example: limit_exceeded
              message:
                type: string
                example: Rate limit exceeded
    '500':
      type: object
      properties:
        type:
          type: string
          example: internal_server
        errors:
          type: array
    '502':
      type: string
      example: >-
        <!doctype html><meta charset='utf-8'><meta name=viewport
        content='width=device-width, initial-scale=1'><title>502</title>502 Bad
        Gateway
    cpf_number:
      title: CPF number
      type: string
      minLength: 11
      maxLength: 11
      example: '00388415129'
      description: >-
        Brazilian individual taxpayer identification number (Cadastro de Pessoas
        Físicas), consisting of 11 numeric digits without formatting (no dots or
        hyphens)
    full_name:
      type:
        - string
        - 'null'
      format: name
      pattern: ^[a-zA-Z ,.''-]{1,100}$
      minLength: 2
      maxLength: 100
      example: Josh Coffey
      description: The full name of a person, which includes a first and last name
    dob:
      type:
        - string
        - 'null'
      format: date
      example: '1976-02-21'
      description: >-
        The date of birth of a person, formatted as “YYYY-MM-DD” according to
        ISO 8601
    gender:
      type:
        - string
        - 'null'
      enum:
        - M
        - F
      example: M
      description: The gender of a person. `M` indicates male; `F` indicates female
    cpf_status:
      type: string
      example: Regular
      description: >
        Descriptive status of the CPF number, based on official data. Indicates
        the current registration condition of the CPF holder - `Regular` — Valid
        (CPF is active and in good standing) - `Suspensa` — Suspended (CPF is
        temporarily inactive) - `Cancelada` — Canceled (CPF has been officially
        canceled) - `Pendente` — Pending regularisation (CPF requires corrective
        action) - `Nula` — Null (CPF was never issued or is invalid)
    cpf_status_code:
      type: string
      enum:
        - '00'
        - '02'
        - '03'
        - '04'
        - '05'
        - '08'
        - '09'
      example: '00'
      description: >
        Status code of the CPF number, based on official data - `00` — Valid
        (CPF is active and in good standing)   - `02` — Suspended (CPF is
        temporarily inactive)   - `03` — Canceled (CPF has been officially
        canceled)   - `05` — Pending regularisation (CPF requires corrective
        action)   - `08` — Null (CPF was never issued or is invalid)  
    cpf_status_reason:
      type: string
      example: REGULAR
      description: >
        Human-readable reason for the current CPF registration status, as
        provided by officials. Explains why the CPF holds its specific status
        (e.g., suspension due to missing tax declarations, cancellation by
        request, invalid registration, death)
    year_of_death:
      type:
        - integer
        - 'null'
      format: int32
      example: null
      description: >
        Calendar year in which the individual was reported deceased, based on
        available records. The field may be `null` if the information is not
        applicable
    nin:
      title: NIN
      type: string
      minLength: 11
      maxLength: 11
      example: '38109457262'
      description: >-
        The Nigerian National Identification Number (NIN), a unique 11-digit
        identifier issued by the National Identity Management Commission (NIMC)
    first_name:
      title: First name
      type:
        - string
        - 'null'
      format: name
      minLength: 2
      maxLength: 64
      pattern: ^[a-zA-Z ,.''-]{1,64}$
      example: Josh
      description: The first name of a person
    middle_name:
      title: Middle name
      type:
        - string
        - 'null'
      format: name
      minLength: 2
      maxLength: 64
      pattern: ^[a-zA-Z ,.''-]{1,64}$
      example: David
      description: The middle name of a person
    last_name:
      title: Last name
      type:
        - string
        - 'null'
      format: name
      minLength: 2
      maxLength: 64
      pattern: ^[a-zA-Z ,.''-]{1,64}$
      example: Coffey
      description: The last name of a person
    phone:
      title: Phone number
      type:
        - string
        - 'null'
      minLength: 1
      maxLength: 15
      example: '441172345678'
      description: The phone number of a person or a company
    email:
      title: Email address
      type:
        - string
        - 'null'
      format: email
      minLength: 1
      maxLength: 254
      example: josh.coffey@example.com
      description: The email address of a person or a company
    residence_country:
      type:
        - string
        - 'null'
      minLength: 2
      maxLength: 2
      example: GB
      description: >-
        A residence country of an object. A two-letter country code according to
        ISO 3166-2
    profile_image:
      title: Profile image
      type: string
      format: binary
      example: /9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST0ZJTEUAAQEAAAHIAAAAAAQwA[...]
      description: A profile image of a person in base64 binary format
    country:
      type:
        - string
        - 'null'
      minLength: 2
      maxLength: 2
      example: GB
      description: >-
        A country of an object. A two-letter country code according to ISO
        3166-2
    state:
      title: State
      type:
        - string
        - 'null'
      minLength: 1
      maxLength: 50
      example: null
      description: A state of a person or a company
    district:
      type:
        - string
        - 'null'
      minLength: 1
      maxLength: 50
      example: Westminster
      description: The district (an area of a city) of an object
    address:
      title: Address
      type:
        - string
        - 'null'
      minLength: 1
      maxLength: 50
      example: 45 High Street, Flat 2A
      description: >-
        An address (a street name, a building number, and a unit number) of a
        person or a company
    document_number--non-doc--pe--foreigner-id:
      type:
        - string
        - 'null'
      minLength: 7
      maxLength: 9
      example: '006016372'
      description: A number of a document
    issue_date:
      title: Issue date
      type:
        - string
        - 'null'
      maxLength: 10
      format: date
      example: '2020-11-04'
      description: An issue date of a document in `YYYY-MM-DD` format
    expiry_date:
      title: Expiration date
      type:
        - string
        - 'null'
      maxLength: 10
      format: date
      example: '2028-11-04'
      description: The date of document expiration, formatted according to ISO 8601
    residence_expiry_date:
      type:
        - string
        - 'null'
      format: date
      example: '2028-04-16'
      description: The date of residence expiration, formatted according to ISO 8601
    nationality:
      type:
        - string
        - 'null'
      minLength: 2
      maxLength: 2
      example: GB
      description: >-
        A nationality country of a person. A two-letter country code according
        to ISO 3166-2
    nationality_demonym_es:
      type:
        - string
        - 'null'
      example: VENEZOLANA
      description: Nationality demonym in Spanish
    form_id:
      title: Form ID
      type:
        - string
        - 'null'
      minLength: 36
      maxLength: 36
      example: d87132ba092d8148ba1891736832d0451ac2
      description: >-
        A unique identifier of a form, assigned by our system after it is
        created in the Dashboard
    applicant_id:
      title: Applicant ID
      type: string
      minLength: 36
      maxLength: 36
      example: 723f46ab04feb64f442946f2953a67eaecf7
      description: >-
        A unique identifier of an applicant, that is assigned by our system
        after an applicant object was created with a “Create an applicant”
        request
    external_applicant_id:
      type:
        - string
        - 'null'
      minLength: 0
      maxLength: 50
      example: cb1eebbe-9945-4e64-8f60-c920f1e3e237
      description: A unique identifier of your user in your system
    language_code:
      type: string
      minLength: 2
      maxLength: 2
      example: EN
      description: >-
        A language of an object. A two-letter language code according to ISO
        639-1
    external_verification_id:
      type:
        - string
        - 'null'
      minLength: 0
      maxLength: 50
      example: ed469618898d75b149e5c7c4b6a1c415
      description: A unique identifier of an object in your system
    verification_id:
      title: Verification ID
      type:
        - string
        - 'null'
      minLength: 36
      maxLength: 36
      example: d2177cdf067d424a221b5d045dc616bf81f9
      description: >-
        A unique identifier for a verification, assigned by our system after a
        verification is created using the “Create a verification" request
    type--nondoc--ukraine--request:
      type: string
      enum:
        - PRIVATBANK
        - MONOBANK
      example: PRIVATBANK
      description: >
        Name of an entity, that provides verfication with BankID for an
        applicant
    url--nondoc--ukraine--request:
      type: string
      example: >-
        https://bankid.org.ua/DataAccessService/das/authorize?response_type=code&client_id=fb58c7a4-cbb8-4331-a974-228e7ff30ff1&redirect_uri=https://api2.needhelp.com.ua/callbacks/ua-bank-id/d947a2180d6461447119b6d4c4a8f3c201a1
      description: |
        An URL address for BankID services
    method--nondoc--ukraine--request:
      type: string
      enum:
        - GET
        - POST
      example: GET
      description: >
        Name of HTTP request method, which should be applied to an URL in order
        to initiate creation of a verification
    nondoc--ukraine--post--200:
      summary: Test
      description: ''
      type: object
      properties:
        external_verification_id:
          $ref: '#/components/schemas/external_verification_id'
        verification_id:
          $ref: '#/components/schemas/verification_id'
        applicant_id:
          $ref: '#/components/schemas/applicant_id'
        request:
          type: object
          properties:
            method:
              $ref: '#/components/schemas/type--nondoc--ukraine--request'
            url:
              $ref: '#/components/schemas/url--nondoc--ukraine--request'
        additional_requests:
          type: array
          items:
            type: object
            properties:
              type:
                $ref: '#/components/schemas/type--nondoc--ukraine--request'
              method:
                $ref: '#/components/schemas/method--nondoc--ukraine--request'
              url:
                $ref: '#/components/schemas/url--nondoc--ukraine--request'
    city:
      title: City
      type:
        - string
        - 'null'
      minLength: 1
      maxLength: 50
      example: London
      description: A city or a town of a person or a company
    postal_code:
      title: Postal code
      type:
        - string
        - 'null'
      minLength: 1
      maxLength: 20
      example: SW1A 1AA
      description: A postal code (zip code, postcode) of a person or a company
    ssn:
      title: Social Security Number (SSN)
      type:
        - string
        - 'null'
      minLength: 4
      maxLength: 9
      example: '545180772'
      description: >-
        The US Social Security Number of a person (SSN). The value must be an
        unformatted string of digits, either 4 digits (partial) or exactly 9
        digits (full). No dashes, spaces, or other characters are allowed
    drivers_license:
      title: Driver’s license number
      type:
        - string
        - 'null'
      minLength: 7
      maxLength: 14
      example: P620-7949
      description: >-
        The unique driver identification number issued by a US state or
        territory. It is a mix of numbers and letters, and its format is
        state-dependent
    match_score:
      title: US eIDV match score
      type:
        - number
        - 'null'
      format: float
      minimum: 0
      maximum: 100
      example: 80
      description: Overall identity match score
    name_match:
      title: Full name match
      type:
        - string
        - 'null'
      enum:
        - MATCH
        - PARTIAL_MATCH
        - NO_MATCH
        - null
      example: NO_MATCH
      description: >
        The type of match found for the person’s full name during US eIDV
        verification


        - **MATCH**: The person’s full name has a total match against the record
        in the database

        - **PARTIAL_MATCH**: The person’s full name address partially matches
        the record in the database

        - **NO_MATCH**: The person’s full name address did not match a record in
        the database

        - **null**: No data was provided in the request
    dob_match:
      title: Date of birth match
      type:
        - string
        - 'null'
      enum:
        - MATCH
        - PARTIAL_MATCH
        - NO_MATCH
        - null
      example: NO_MATCH
      description: >
        The type of match found for the person’s date of birth during US eIDV
        verification


        - **MATCH**: The person’s date of birth has a total match against the
        record in the database

        - **PARTIAL_MATCH**: The person’s date of birth partially matches the
        record in the database

        - **NO_MATCH**: The person’s date of birth did not match a record in the
        database

        - **null**: No data was provided in the request
    address_match:
      title: Address match
      type:
        - string
        - 'null'
      enum:
        - MATCH
        - PARTIAL_MATCH
        - NO_MATCH
        - null
      example: NO_MATCH
      description: >
        The type of match found for the person’s address during US eIDV
        verification


        - **MATCH**: The person’s address has a total match against the record
        in the database

        - **PARTIAL_MATCH**: The person’s address partially matches the record
        in the database

        - **NO_MATCH**: The person’s address did not match a record in the
        database

        - **null**: No data was provided in the request
    city_match:
      title: City match
      type:
        - string
        - 'null'
      enum:
        - MATCH
        - PARTIAL_MATCH
        - NO_MATCH
        - null
      example: NO_MATCH
      description: >
        The type of match found for the person’s city during US eIDV
        verification


        - **MATCH**: The person’s city has a total match against the record in
        the database

        - **PARTIAL_MATCH**: The person’s city partially matches the record in
        the database

        - **NO_MATCH**: The person’s city did not match a record in the database

        - **null**: No data was provided in the request
    state_match:
      title: State match
      type:
        - string
        - 'null'
      enum:
        - MATCH
        - PARTIAL_MATCH
        - NO_MATCH
        - null
      example: NO_MATCH
      description: >
        The type of match found for the person’s state during US eIDV
        verification


        - **MATCH**: The person’s state has a total match against the record in
        the database

        - **PARTIAL_MATCH**: The person’s state partially matches the record in
        the database

        - **NO_MATCH**: The person’s state did not match a record in the
        database

        - **null**: No data was provided in the request
    postal_code_match:
      title: Postal code (ZIP) match
      type:
        - string
        - 'null'
      enum:
        - MATCH
        - PARTIAL_MATCH
        - NO_MATCH
        - null
      example: NO_MATCH
      description: >
        The type of match found for the person’s postal code (ZIP) during US
        eIDV verification


        - **MATCH**: The person’s postal code (ZIP) has a total match against
        the record in the database

        - **PARTIAL_MATCH**: The person’s postal code (ZIP) partially matches
        the record in the database

        - **NO_MATCH**: The person’s postal code (ZIP) did not match a record in
        the database

        - **null**: No data was provided in the request
    phone_match:
      title: Phone number match
      type:
        - string
        - 'null'
      enum:
        - MATCH
        - PARTIAL_MATCH
        - NO_MATCH
        - null
      example: NO_MATCH
      description: >
        The type of match found for the person’s phone number


        - **MATCH**: The person’s phone number has a total match against the
        record in the database

        - **PARTIAL_MATCH**: The person’s phone number partially matches the
        record in the database

        - **NO_MATCH**: The person’s phone number did not match a record in the
        database

        - **null**: No data was provided in the request
    email_match:
      title: Email address match
      type:
        - string
        - 'null'
      enum:
        - MATCH
        - PARTIAL_MATCH
        - NO_MATCH
        - null
      example: NO_MATCH
      description: >
        The type of match found for the person’s email address during US eIDV
        verification


        - **MATCH**: The person’s email address has a total match against the
        record in the database

        - **PARTIAL_MATCH**: The person’s email address partially matches the
        record in the database

        - **NO_MATCH**: The person’s email address did not match a record in the
        database

        - **null**: No data was provided in the request
    ssn_match:
      title: Social Security Number (SSN) match
      type:
        - string
        - 'null'
      enum:
        - MATCH
        - PARTIAL_MATCH
        - NO_MATCH
        - null
      example: NO_MATCH
      description: >
        The type of match found for the person’s Social Security Number (SSN)
        during US eIDV verification


        - **MATCH**: The person’s SSN has a total match against the record in
        the database

        - **PARTIAL_MATCH**: The person’s SSN partially matches the record in
        the database

        - **NO_MATCH**: The person’s SSN did not match a record in the database

        - **null**: No data was provided in the request
    drivers_license_match:
      title: Driver’s license number match
      type:
        - string
        - 'null'
      enum:
        - MATCH
        - PARTIAL_MATCH
        - NO_MATCH
        - null
      example: NO_MATCH
      description: >-
        |  The type of match found for the person’s driver’s license number
        during US eIDV verification

        - **MATCH**: The person’s driver’s license number has a total match
        against the record in the database - **PARTIAL_MATCH**: The person’s
        driver’s license number partially matches the record in the database -
        **NO_MATCH**: The person’s driver’s license number did not match a
        record in the database - **null**: No data was provided in the request
security:
  - your_api_key: []
tags:
  - name: 🇧🇷 Brazil
    description: Brazil
  - name: 🇮🇳 India
    description: 🇮🇳 India
  - name: 🇰🇿 Kazakhstan
    description: 🇰🇿 Kazakhstan
  - name: 🇲🇽 Mexico
    description: 🇲🇽 Mexico
  - name: 🇳🇬 Nigeria
    description: 🇳🇬 Nigeria
  - name: 🇵🇪 Peru
    description: 🇵🇪 Peru
  - name: 🇹🇷 Turkey
    description: 🇹🇷 Turkey
  - name: 🇺🇦 Ukraine
    description: 🇺🇦 Ukraine
  - name: 🇺🇸 USA
    description: 🇺🇸 USA
paths:
  /services/br/cpf/cpf_number:
    get:
      tags:
        - 🇧🇷 Brazil
      summary: CPF number
      description: |
        Access the article from the previous version of the documentation:

        # [Brazilian CPF](https://docs-v1.kycaid.com/#br-cpf)
      operationId: br-cpf
  /services/br/cpf/2/{cpf_number}:
    get:
      tags:
        - 🇧🇷 Brazil
      summary: CPF number (alternative)
      description: >
        The Brazil CPF verification service allows you to verify the identity of
        an individual in Brazil using their individual taxpayer identification
        number (Cadastro de Pessoas Físicas). The service returns the person’s
        full name, date of birth, and CPF registration status, including whether
        the CPF is active, suspended, or cancelled. No document upload is
        required for verification. This enables quick and automated identity
        checks against official records.
      operationId: br-cpf-2
      parameters:
        - name: cpf_number
          in: path
          schema:
            $ref: '#/components/schemas/cpf_number'
          required: true
      responses:
        '200':
          description: >
            **OK**


            The request was successful, and our system returned an expected
            response.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    title: Infomation found (a person is alive)
                    properties:
                      validation:
                        type: object
                        properties:
                          valid:
                            type: boolean
                            example: true
                      data:
                        type: object
                        properties:
                          cpf_number:
                            $ref: '#/components/schemas/cpf_number'
                          full_name:
                            $ref: '#/components/schemas/full_name'
                          dob:
                            $ref: '#/components/schemas/dob'
                          gender:
                            $ref: '#/components/schemas/gender'
                          cpf_status:
                            $ref: '#/components/schemas/cpf_status'
                          cpf_status_code:
                            $ref: '#/components/schemas/cpf_status_code'
                          cpf_status_reason:
                            $ref: '#/components/schemas/cpf_status_reason'
                          year_of_death:
                            $ref: '#/components/schemas/year_of_death'
                  - type: object
                    title: Information found (a person is dead)
                    properties:
                      validation:
                        type: object
                        properties:
                          valid:
                            type: boolean
                            example: true
                      data:
                        type: object
                        properties:
                          cpf_number:
                            allOf:
                              - $ref: '#/components/schemas/cpf_number'
                              - example: '13550106521'
                          full_name:
                            allOf:
                              - $ref: '#/components/schemas/full_name'
                              - example: Michael Thompson
                          dob:
                            allOf:
                              - $ref: '#/components/schemas/dob'
                              - example: '1971-07-01'
                          gender:
                            $ref: '#/components/schemas/gender'
                          cpf_status:
                            allOf:
                              - $ref: '#/components/schemas/cpf_status'
                              - example: Cancelada
                          cpf_status_code:
                            allOf:
                              - $ref: '#/components/schemas/cpf_status_code'
                              - example: '03'
                          cpf_status_reason:
                            allOf:
                              - $ref: '#/components/schemas/cpf_status_reason'
                              - example: TITULAR FALECIDO
                          year_of_death:
                            allOf:
                              - $ref: '#/components/schemas/year_of_death'
                              - example: 2009
        '400':
          description: >
            **Bad Request**


            Our system could not process the request due to invalid syntax,
            missing parameters, or incorrect data format. Check the request
            structure and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '404':
          description: >
            **Not Found**


            The requested resource does not exist or can’t be found in our
            system.
          content:
            application/json:
              schema: {}
        '422':
          description: >
            **Unprocessable Content**


            The request was well-formed but contains invalid or unprocessable
            data, such as failed validation or incorrect field values.
          content:
            application/json:
              schema:
                type: object
                properties:
                  validation:
                    type: object
                    properties:
                      valid:
                        type: boolean
                        example: false
                  data:
                    type: object
                    properties:
                      cpf_number:
                        type: string
                        example: '00388415129'
        '500':
          description: >
            **Internal Server Error**


            This response indicates that our system encountered an unexpected
            condition that prevented it from fulfilling the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
        '502':
          description: >
            **Bad Gateway**


            This response indicates that our system is unable to reach or
            communicate properly with an upstream server it relies on, the URL
            provided is incorrect, or a required token is missing from the
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/502'
  /services/in/aadhaar/generate-otp:
    post:
      tags:
        - 🇮🇳 India
      summary: Aadhaar number
      description: |
        Access the article from the previous version of the documentation:

        # [India aadhaar card](https://docs-v1.kycaid.com/#in-aadhaar-card)
      operationId: in-aadhaar
  /services/kz/iin/request:
    post:
      tags:
        - 🇰🇿 Kazakhstan
      summary: IIN (basic)
      description: |
        Access the article from the previous version of the documentation:

        # [Kazakhstan Iin](https://docs-v1.kycaid.com/#kz-iin)
      operationId: kz-iin-basic
  /services/kz/personal-data/request:
    post:
      tags:
        - 🇰🇿 Kazakhstan
      summary: IIN (extended)
      description: >
        Access the article from the previous version of the documentation:


        # [Kazakhstan Personal
        Data](https://docs-v1.kycaid.com/#kz-personal-data)
      operationId: kz-iin-extended
  /services/mx/curp/curp_number:
    get:
      tags:
        - 🇲🇽 Mexico
      summary: CURP
      description: |
        Access the article from the previous version of the documentation:

        # [Mexican CURP](https://docs-v1.kycaid.com/#mx-curp)
      operationId: mx-curp
  /services/ng/nin:
    post:
      tags:
        - 🇳🇬 Nigeria
      summary: NIN
      description: >
        The Nigeria NIN (National Identification Number) service provides a
        method for checking and confirming person idenitity using their NIN. It
        utilizes the provided 11-digit NIN to query the official national
        database. The service returns a detailed response including the NIN
        holder's registered identity data (full name, date of birth, address,
        and gender) upon a successful match.
      operationId: ng-nin
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                nin_number:
                  $ref: '#/components/schemas/nin'
      responses:
        '200':
          description: >
            **OK**


            The request was successful, and our system returned an expected
            response.
          content:
            applicantion/json:
              schema:
                type: object
                title: Data on NIN was found
                properties:
                  validation:
                    type: object
                    properties:
                      valid:
                        type: boolean
                        example: true
                  data:
                    type: object
                    properties:
                      nin:
                        $ref: '#/components/schemas/nin'
                      first_name:
                        $ref: '#/components/schemas/first_name'
                      middle_name:
                        $ref: '#/components/schemas/middle_name'
                      last_name:
                        $ref: '#/components/schemas/last_name'
                      dob:
                        $ref: '#/components/schemas/dob'
                      phone:
                        $ref: '#/components/schemas/phone'
                      email:
                        $ref: '#/components/schemas/email'
                      gender:
                        $ref: '#/components/schemas/gender'
                      residence_country:
                        $ref: '#/components/schemas/residence_country'
                      profile_image:
                        $ref: '#/components/schemas/profile_image'
                      address:
                        type: object
                        properties:
                          country:
                            $ref: '#/components/schemas/country'
                          state:
                            $ref: '#/components/schemas/state'
                          district:
                            $ref: '#/components/schemas/district'
                          address:
                            $ref: '#/components/schemas/address'
        '400':
          description: >
            **Bad Request**


            Our system could not process the request due to invalid syntax,
            missing parameters, or incorrect data format. Check the request
            structure and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '404':
          description: >
            **Not Found**


            The requested resource does not exist or can’t be found in our
            system.
          content:
            application/json:
              schema:
                type: object
                title: Data on NIN was not found
                properties:
                  validation:
                    type: object
                    properties:
                      valid:
                        type: boolean
                        example: false
                  data:
                    type: object
                    properties:
                      nin:
                        $ref: '#/components/schemas/nin'
        '422':
          description: >
            **Unprocessable Content**


            Our system understands the request but can’t process it due to
            invalid fields in the request body.
          content:
            application/json:
              schema:
                oneOf:
                  - title: NIN number is required
                    description: >-
                      The error is sent by our system when there is no
                      `nin_number` parameter in a request
                    type: object
                    properties:
                      type:
                        type: string
                        example: validation
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            parameter:
                              type: string
                              example: nin_number
                            message:
                              type: string
                              example: NIN number is required
                  - title: NIN number is not valid
                    description: The error is sent by our system when NIN has wrong format
                    type: object
                    properties:
                      type:
                        type: string
                        example: validation
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            parameter:
                              type: string
                              example: nin_number
                            message:
                              type: string
                              example: NIN number is not valid
  /services/pe/dni/{dni_number}:
    get:
      tags:
        - 🇵🇪 Peru
      summary: DNI number (basic)
      description: |
        Access the article from the previous version of the documentation:

        # [Peru DNI](https://docs-v1.kycaid.com/#pe-dni)
      operationId: pe-dni-basic
      parameters:
        - name: dni_number
          in: path
          schema: {}
          required: true
  /services/pe/dni-extra/{dni_number}:
    get:
      tags:
        - 🇵🇪 Peru
      summary: DNI number (extended)
      description: |
        Access the article from the previous version of the documentation:

        # [Peru DNI Extra](https://docs-v1.kycaid.com/#pe-dni-extra)
      operationId: pe-dni-extended
      parameters:
        - name: dni_number
          in: path
          schema: {}
          required: true
  /services/pe/foreigner-id:
    post:
      tags:
        - 🇵🇪 Peru
      summary: Foreigner resident ID
      description: >
        The foreigner resident ID (Peru) verification service allows you to
        verify the identity of a foreign resident in Peru by their CE (Carné de
        Extranjería) number. The service returns the individual’s full name,
        given and family names, date of birth, nationality, immigration status,
        and residence details, including ID issuance and expiration dates
      operationId: pe-foreigner-id
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                document_number:
                  $ref: >-
                    #/components/schemas/document_number--non-doc--pe--foreigner-id
                dob:
                  $ref: '#/components/schemas/dob'
              required:
                - document_number
                - dob
      responses:
        '200':
          description: >
            **OK**


            The request was successful, and our system returned an expected
            response.
          content:
            application/json:
              schema:
                oneOf:
                  - title: Information found
                    description: >-
                      Returned when a person matches the given parameters was
                      found
                    type: object
                    properties:
                      validation:
                        type: object
                        properties:
                          valid:
                            type: boolean
                            example: true
                      data:
                        type: object
                        properties:
                          number:
                            $ref: >-
                              #/components/schemas/document_number--non-doc--pe--foreigner-id
                          full_name:
                            $ref: '#/components/schemas/full_name'
                          first_name:
                            $ref: '#/components/schemas/first_name'
                          last_name:
                            $ref: '#/components/schemas/last_name'
                          names:
                            type: array
                            items: {}
                          dob:
                            $ref: '#/components/schemas/dob'
                          issue_date:
                            $ref: '#/components/schemas/issue_date'
                          expiry_date:
                            $ref: '#/components/schemas/expiry_date'
                          residence_expiry_date:
                            $ref: '#/components/schemas/residence_expiry_date'
                          immigration_status:
                            type: string
                            example: ESPECIAL
                          nationality:
                            $ref: '#/components/schemas/nationality'
                          nationality_demonym_es:
                            $ref: '#/components/schemas/nationality_demonym_es'
                  - title: Information not found
                    description: Returned when no person matches the given parameters
                    type: object
                    properties:
                      validation:
                        type: object
                        properties:
                          valid:
                            type: boolean
                            example: false
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              example: not_found
                            message:
                              type: string
                              example: Information not found
                      data:
                        type: string
                        example: 'null'
        '400':
          description: >
            **Bad Request**


            Our system could not process the request due to invalid syntax,
            missing parameters, or incorrect data format. Check the request
            structure and try again.
          content:
            application/json:
              schema: {}
        '404':
          description: >
            **Not Found**


            The requested resource does not exist or can’t be found in our
            system.
          content:
            application/json:
              schema: {}
        '422':
          description: >
            **Unprocessable Content**


            Our system understands the request but can’t process it due to
            invalid fields in the request body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: ''
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          example: ''
                        message:
                          type: string
                          example: ''
              example:
                type: validation
                errors:
                  - parameter: document_number
                    message: Document number is required
                  - parameter: dob
                    message: Date of birth is required
        '429':
          description: >
            **Too Many Requests**


            This response indicates that a user has sent too many requests in a
            given amount of time.
          content:
            application/json:
              schema: {}
        '500':
          description: >
            **Internal Server Error**


            This response indicates that our system encountered an unexpected
            condition that prevented it from fulfilling the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
        '502':
          description: >
            **Bad Gateway**


            This response indicates that our system is unable to reach or
            communicate properly with an upstream server it relies on, the URL
            provided is incorrect, or a required token is missing from the
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/502'
  /services/tr/identity-number:
    post:
      tags:
        - 🇹🇷 Turkey
      summary: Türkiye Cumhuriyeti Kimlik Numarası
      description: >
        Access the article from the previous version of the documentation:


        # [Turkey Identity
        Number](https://docs-v1.kycaid.com/#tr-identity-number)
      operationId: tr-tckn
  /external-verifications:
    post:
      tags:
        - 🇺🇦 Ukraine
      summary: 'BankID/Diia: Create a verification'
      description: |
        Create a verification using BankID or Diia services in Ukraine
      operationId: non-doc-ua-bankid-diia-create
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  title: Ukraine • BankID
                  properties:
                    type:
                      type: string
                      example: UA_BANK_ID
                    form_id:
                      $ref: '#/components/schemas/form_id'
                    applicant_id:
                      $ref: '#/components/schemas/applicant_id'
                    external_applicant_id:
                      $ref: '#/components/schemas/external_applicant_id'
                    language_code:
                      $ref: '#/components/schemas/language_code'
                  required:
                    - type
                    - form_id
                - type: object
                  title: Ukraine • Diia
                  properties:
                    type:
                      type: string
                      example: UA_DIIA
                    form_id:
                      $ref: '#/components/schemas/form_id'
                    applicant_id:
                      $ref: '#/components/schemas/applicant_id'
                    external_applicant_id:
                      $ref: '#/components/schemas/external_applicant_id'
                    language_code:
                      $ref: '#/components/schemas/language_code'
                  required:
                    - type
                    - form_id
      responses:
        '200':
          description: >
            **OK**


            The request was successful, and our system returned an expected
            response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/nondoc--ukraine--post--200'
        '400':
          description: >
            **Bad Request**


            Our system could not process the request due to invalid syntax,
            missing parameters, or incorrect data format. Check the request
            structure and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '404':
          description: >
            **Not Found**


            The requested resource does not exist or can’t be found in our
            system.
          content:
            application/json:
              schema: {}
        '422':
          description: >
            **Unprocessable Content**


            Our system understands the request but can’t process it due to
            invalid fields in the request body.
          content:
            application/json:
              schema: {}
        '429':
          description: >
            **Too Many Requests**


            This response indicates that a user has sent too many requests in a
            given amount of time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429'
        '500':
          description: >
            **Internal Server Error**


            This response indicates that our system encountered an unexpected
            condition that prevented it from fulfilling the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
        '502':
          description: 502 Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/502'
  /external-verifications/{external_verification_id}:
    get:
      tags:
        - 🇺🇦 Ukraine
      summary: 'BankID/Diia: Get a verification'
      description: >
        Access the article from the previous version of the documentation:


        # [Get external
        verification](https://docs-v1.kycaid.com/#get-external-verification)
      operationId: non-doc-ua-bankid-diia-get
      parameters:
        - name: external_verification_id
          in: path
          schema: {}
          required: true
  /services/us/eidv:
    post:
      tags:
        - 🇺🇸 USA
      summary: eIDV
      description: >
        The USA eIDV (electronic Identity Verification) service provides
        automated, remote identity verification for individuals within the
        United States. It utilizes a person's first name, last name, and date of
        birth to check against official records. The service returns a match
        score along with a detailed description of the verification outcome,
        enabling quick and reliable identity checks.
      operationId: us-eidv
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  allOf:
                    - allOf:
                        - $ref: '#/components/schemas/first_name'
                        - type: string
                    - type: string
                      example: Josh
                middle_name:
                  $ref: '#/components/schemas/middle_name'
                last_name:
                  allOf:
                    - allOf:
                        - $ref: '#/components/schemas/last_name'
                        - type: string
                    - type: string
                      example: Coffey
                dob:
                  allOf:
                    - allOf:
                        - $ref: '#/components/schemas/dob'
                        - type: string
                    - type: string
                      example: '1976-02-21'
                address:
                  $ref: '#/components/schemas/address'
                city:
                  $ref: '#/components/schemas/city'
                state:
                  $ref: '#/components/schemas/state'
                postal_code:
                  $ref: '#/components/schemas/postal_code'
                phone:
                  $ref: '#/components/schemas/phone'
                email:
                  $ref: '#/components/schemas/email'
                ssn:
                  $ref: '#/components/schemas/ssn'
                drivers_license:
                  $ref: '#/components/schemas/drivers_license'
              required:
                - first_name
                - last_name
                - dob
      responses:
        '200':
          description: >
            **OK**


            The request was successful, and our system returned an expected
            response.
          content:
            application/json:
              schema:
                type: object
                title: Information received
                properties:
                  data:
                    type: object
                    properties:
                      match_score:
                        $ref: '#/components/schemas/match_score'
                      name_match:
                        $ref: '#/components/schemas/name_match'
                      dob_match:
                        $ref: '#/components/schemas/dob_match'
                      address_match:
                        $ref: '#/components/schemas/address_match'
                      city_match:
                        $ref: '#/components/schemas/city_match'
                      state_match:
                        $ref: '#/components/schemas/state_match'
                      postal_code_match:
                        $ref: '#/components/schemas/postal_code_match'
                      phone_match:
                        $ref: '#/components/schemas/phone_match'
                      email_match:
                        $ref: '#/components/schemas/email_match'
                      ssn_match:
                        $ref: '#/components/schemas/ssn_match'
                      drivers_license_match:
                        $ref: '#/components/schemas/drivers_license_match'
        '400':
          description: >
            **Bad Request**


            Our system could not process the request due to invalid syntax,
            missing parameters, or incorrect data format. Check the request
            structure and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '404':
          description: >
            **Not Found**


            The requested resource does not exist or can’t be found in our
            system.
          content:
            application/json:
              schema: {}
        '500':
          description: >
            **Internal Server Error**


            This response indicates that our system encountered an unexpected
            condition that prevented it from fulfilling the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
        '502':
          description: >
            **Bad Gateway**


            This response indicates that our system is unable to reach or
            communicate properly with an upstream server it relies on, the URL
            provided is incorrect, or a required token is missing from the
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/502'
