openapi: 3.0.0
info:
  contact:
    email: contact@yousign.com
    name: Support
    url: https://yousign.com/contact
  description: Build the best experience of digital signature through your own platform. Increase your conversion rates, leverage your data and reduce your costs with Yousign API.
  license:
    name: proprietary
    url: https://yousign.com/terms
  title: Public Api v3 Applicant Identity Document Verification API
  version: '3.0'
servers:
- description: Sandbox URL
  url: https://api-sandbox.yousign.app/v3
- description: Production URL
  url: https://api.yousign.app/v3
security:
- bearerAuth: []
tags:
- description: KYC Process of verifying the identity associated with an identity document.
  name: Identity Document Verification
paths:
  /verifications/identity_documents:
    get:
      description: Returns the list of all Identity Document Verifications within your organization. You can limit the number of items returned by using filters and pagination. Consult our [guide](https://developers.yousign.com/docs/identity-document-verification) for more details and examples.
      operationId: get-verifications-identity_documents
      parameters:
      - description: After cursor (pagination)
        in: query
        name: after
        required: false
        schema:
          minLength: 1
          type: string
      - description: The limit of items count to retrieve.
        in: query
        name: limit
        required: false
        schema:
          default: 100
          maximum: 100
          minimum: 1
          type: integer
      - description: 'Filter by `status`. Allowed operators: `eq`.

          Example: `status[eq]=verified`

          '
        example:
          eq:
          - verified
        explode: true
        in: query
        name: status
        required: false
        schema:
          description: Filter by status.
          minProperties: 1
          type: object
        style: deepObject
      - description: 'Filter by `workspace_id`. Allowed operators: `eq`.

          Example: `workspace_id[eq]=9b6ed2f3-244f-487a-baa1-bbe4f51c8748`

          '
        example:
          eq:
          - 9b6ed2f3-244f-487a-baa1-bbe4f51c8748
        explode: true
        in: query
        name: workspace_id
        required: false
        schema:
          description: Filter by workspace_id.
          minProperties: 1
          type: object
        style: deepObject
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_verifications_identity_documents_200_response'
          description: OK
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad request
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Access unauthorized
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Access forbidden
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed'
          description: This method is not allowed
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
            Retry-After:
              $ref: '#/components/headers/retry-after'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Too Many Requests, please try again later.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
            Retry-After:
              $ref: '#/components/headers/retry-after'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
      summary: List Identity Document Verifications
      tags:
      - Identity Document Verification
    post:
      description: 'Verify a person''s Identity Document by sending the file containing their Identity Document (identity card, passport, residence permit or driving license).


        An Image Identity Verification can be requested as follows:

        - **Verification with names**: This option checks both the validity of the ID document and the coherence between the names provided and those on the document.

        - **Verification without names**: This option only checks the validity of the ID document.


        Related guide: [Image Identity Verification](https://developers.yousign.com/docs/identity-document-verification)


        **ℹ️ This endpoint accepts two request body formats — pick the one that matches your use case:**

        - 📁 `multipart/form-data` — upload a binary file containing the Identity Document.

        - 📝 `application/json` — reference an existing Workflow Session Applicant by ID.


        **🔓 Endpoint access**

        - Environments: `production`, `sandbox`

        - API key scopes: `organization`, `workspace`

        - Plans: `pro`, `scale`

        - Add-ons (for production access): `Verify - Image identity verification`

        '
      operationId: post-verifications-identity_documents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateIdentityDocumentFromApplicant'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/post_verifications_identity_documents_request'
      responses:
        '201':
          content:
            application/json:
              examples:
                pending:
                  $ref: '#/components/examples/IdentityDocumentExample'
              schema:
                $ref: '#/components/schemas/IdentityDocumentFull'
          description: Created
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad request
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Access unauthorized
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Access forbidden
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed'
          description: This method is not allowed
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
            Retry-After:
              $ref: '#/components/headers/retry-after'
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMediaTypeResponse'
          description: UnsupportedMediaType
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Too Many Requests, please try again later.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
            Retry-After:
              $ref: '#/components/headers/retry-after'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
      summary: Initiate a new Identity Document Verification
      tags:
      - Identity Document Verification
  /verifications/identity_documents/{identityDocumentVerificationId}:
    get:
      description: Get the detailed results of an Identity Document Verification, including the status of the verification, the reasons in case of rejection and the data extracted from the Identity Document.
      operationId: get-verifications-identity_documents-id
      parameters:
      - description: Identity Document Verification Id
        in: path
        name: identityDocumentVerificationId
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      responses:
        '200':
          content:
            application/json:
              examples:
                verified:
                  summary: Verified result
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    workspace_id: 9a93d3b5-fb3b-4abf-9e70-26315b33506c
                    created_at: '2024-01-18T22:59:00+00:00'
                    updated_at: '2024-01-18T23:15:00+00:00'
                    status: verified
                    status_codes: []
                    data_anonymized: false
                    workflow_session_id: 0ef334d2-7f36-4643-8a2a-4283b4a3e4a4
                    previous_attempt_id: null
                    applicant_id: null
                    data:
                      extracted_from_document:
                        first_name: John
                        birth_name: Doe
                        last_name: Doe
                        born_on: '1990-05-15'
                        birth_location: Paris
                        gender: m
                        full_address: '13 RUE SAINT MARCELIN

                          MARSEILLE 10E (13)'
                        type: id_card
                        issuing_country_code: FR
                        issued_on: '2020-03-01'
                        expired_on: '2030-03-01'
                        document_number: X4RTBPFW4
                        mrz:
                          line1: IDFRASIAGRA<<<<<<<<<<<<<<<<<<<133039
                          line2: 1002133008071GREGOIRE<<REMY8110228M4
                          line3: <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                        national_identification_number: null
              schema:
                $ref: '#/components/schemas/IdentityDocumentFull'
          description: OK
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad request
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Access unauthorized
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Access forbidden
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Resource not found
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed'
          description: This method is not allowed
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
            Retry-After:
              $ref: '#/components/headers/retry-after'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Too Many Requests, please try again later.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
            Retry-After:
              $ref: '#/components/headers/retry-after'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
      summary: Retrieve an Identity Document Verification
      tags:
      - Identity Document Verification
components:
  headers:
    rateLimit-remaining:
      description: The number of requests remaining in the current rate limit window
      schema:
        type: integer
    rateLimit-reset:
      description: The remaining time until the rate limit resets in seconds
      schema:
        type: integer
    rateLimit-remaining-hour:
      description: The number of requests remaining in the current hour rate limit window
      schema:
        type: integer
    rateLimit-limit:
      description: The maximum number of requests that the consumer is permitted to make in a given period
      schema:
        type: integer
    retry-after:
      description: Retry the request after X seconds
      schema:
        type: integer
    rateLimit-remaining-minute:
      description: The number of requests remaining in the current minute rate limit window
      schema:
        type: integer
    rateLimit-limit-minute:
      description: The maximum number of requests that the consumer is permitted to make in an minute window
      schema:
        type: integer
    rateLimit-limit-hour:
      description: The maximum number of requests that the consumer is permitted to make in an hour window
      schema:
        type: integer
  schemas:
    InternalServerError:
      properties:
        type:
          example: about:blank
          type: string
        detail:
          example: Something wrong occurred.
          type: string
      required:
      - detail
      - type
      title: InternalServerError
      type: object
    IdentityDocumentFull:
      allOf:
      - $ref: '#/components/schemas/IdentityDocumentMeta'
      - properties:
          data:
            $ref: '#/components/schemas/IdentityDocumentFull_allOf_data'
        required:
        - data
        type: object
      title: IdentityDocumentFull
      type: object
    TooManyRequestsResponse:
      properties:
        message:
          type: string
      required:
      - message
      title: TooManyRequestsResponse
      type: object
    post_verifications_identity_documents_request:
      anyOf:
      - $ref: '#/components/schemas/InitiateIdentityDocument'
      - $ref: '#/components/schemas/InitiateIdentityDocumentWithoutName'
      type: object
    UnsupportedMediaTypeResponse:
      properties:
        type:
          type: string
        detail:
          type: string
      required:
      - detail
      - type
      title: UnsupportedMediaTypeResponse
      type: object
    InitiateIdentityDocumentWithoutName:
      additionalProperties: false
      properties:
        type:
          description: The document type to verify
          enum:
          - id_card
          - passport
          - residence_permit
          - ita_ts_cns
          example: id_card
          type: string
        file:
          description: 'The identity document file to verify.

            Accepted formats: PNG, JPEG, JPG, PDF.

            Max size: 10 MB. Max resolution: 20 mpx.

            '
          format: binary
          type: string
        additional_file:
          description: 'Additional document file, such as the back side of an identity card.

            Accepted formats: PNG, JPEG, JPG, PDF.

            Max size: 10 MB. Max resolution: 20 mpx.

            '
          format: binary
          type: string
        workspace_id:
          description: 'Scopes the verification to a specific workspace.

            Defaults to the default workspace if not specified.

            '
          example: 9412b83b-b4b9-4a94-97b5-2b43dfa4cde3
          format: uuid
          nullable: true
          type: string
        workflow_session_id:
          $ref: '#/components/schemas/WorkflowSessionId'
        previous_attempt_id:
          $ref: '#/components/schemas/PreviousAttemptId'
        min_age:
          description: Minimum age required for the document holder.
          example: 18
          minimum: 1
          nullable: true
          type: integer
        max_age:
          description: Maximum age allowed for the document holder.
          example: 65
          minimum: 1
          nullable: true
          type: integer
        prohibited_countries:
          description: List of prohibited issuing countries (ISO 3166-1 alpha-2).
          example:
          - RU
          - KP
          items:
            pattern: ^[A-Z]{2}$
            type: string
          minItems: 1
          nullable: true
          type: array
      required:
      - file
      title: Initiate an Identity Document Verification without names
      type: object
    MethodNotAllowed:
      properties:
        message:
          type: string
      required:
      - message
      title: MethodNotAllowed
      type: object
    NotFoundResponse:
      properties:
        type:
          type: string
        detail:
          type: string
      required:
      - detail
      - type
      title: NotFoundResponse
      type: object
    InitiateIdentityDocumentFromApplicant:
      additionalProperties: false
      properties:
        applicant_id:
          description: The Applicant ID linked to the Workflow Session.
          example: 9a93d3b5-fb3b-4abf-9e70-26315b33506c
          format: uuid
          type: string
      required:
      - applicant_id
      title: Attach a new Identity Document Verification to an Applicant
      type: object
    WorkflowSessionApplicantId:
      description: 'Unique identifier of an Applicant.

        '
      example: 0ef334d2-7f36-4643-8a2a-4283b4a3e4a4
      format: uuid
      nullable: true
      title: Applicant
      type: string
    ForbiddenResponse:
      properties:
        type:
          type: string
        detail:
          type: string
      required:
      - detail
      - type
      title: ForbiddenResponse
      type: object
    UnauthorizedResponse:
      properties:
        type:
          type: string
        detail:
          type: string
      required:
      - detail
      - type
      title: UnauthorizedResponse
      type: object
    BadRequestResponse:
      properties:
        type:
          type: string
        detail:
          type: string
      required:
      - detail
      - type
      title: BadRequestResponse
      type: object
    UUID:
      description: The unique identifier for a resource.
      example: 9a93d3b5-fb3b-4abf-9e70-26315b33506c
      format: uuid
      type: string
    IdentityDocumentMeta:
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        workspace_id:
          description: The Workspace ID in which the verification has been created.
          example: 9a93d3b5-fb3b-4abf-9e70-26315b33506c
          format: uuid
          type: string
        created_at:
          description: Creation date of the Identity Document Verification.
          example: '2024-01-18T22:59:00Z'
          format: date-time
          type: string
        updated_at:
          description: Update date of the Identity Document Verification.
          example: '2024-01-18T22:59:00Z'
          format: date-time
          type: string
        status:
          $ref: '#/components/schemas/IdentityDocumentStatus'
        status_codes:
          description: List of status codes. Indicates the cause when the status is `failed` or `inconclusive`.
          example:
          - IDDV_1706
          - IDDV_1707
          items:
            type: string
          type: array
        data_anonymized:
          description: 'Indicates if the personal data extracted from the document has been anonymized.

            If set to `true`, the personal data has been anonymized and most fields will be NULL.

            '
          example: false
          type: boolean
        workflow_session_id:
          $ref: '#/components/schemas/WorkflowSessionId'
        previous_attempt_id:
          $ref: '#/components/schemas/PreviousAttemptId'
        applicant_id:
          $ref: '#/components/schemas/WorkflowSessionApplicantId'
      required:
      - applicant_id
      - created_at
      - data_anonymized
      - id
      - previous_attempt_id
      - status
      - status_codes
      - updated_at
      - workflow_session_id
      - workspace_id
      title: IdentityDocumentMeta
      type: object
    get_verifications_identity_documents_200_response:
      properties:
        meta:
          $ref: '#/components/schemas/Pagination'
        data:
          items:
            $ref: '#/components/schemas/IdentityDocumentMeta'
          type: array
      type: object
    PreviousAttemptId:
      description: 'ID of the previous attempt within the same `workflow_session_id`.

        Allows continuity between multiple attempts of the same Action.

        Null if this is the first attempt.

        '
      example: 9412b83b-b4b9-4a94-97b5-2b43dfa4cde4
      format: uuid
      nullable: true
      title: Previous Attempt identifier
      type: string
    InitiateIdentityDocument:
      additionalProperties: false
      properties:
        first_name:
          description: 'Please provide the holder first name, exactly as it appears on the ID document.

            Please match it exactly, with the same characters, same case.

            One exception: if the document mentions an honorary title, please don''t provide it as part of the name.

            '
          example: John
          maxLength: 255
          minLength: 1
          nullable: false
          type: string
        last_name:
          description: 'Please provide the holder last name, exactly as it appears on the ID document birth name.

            Please match it exactly, with the same characters, same case.

            One exception: if the document mentions an honorary title, please don''t provide it as part of the name.

            '
          example: Doe
          maxLength: 255
          minLength: 1
          nullable: false
          type: string
        type:
          description: The document type to verify
          enum:
          - id_card
          - passport
          - residence_permit
          - ita_ts_cns
          example: id_card
          type: string
        file:
          description: 'The identity document file to verify.

            Accepted formats: PNG, JPEG, JPG, PDF.

            Max size: 10 MB. Max resolution: 20 mpx.

            '
          format: binary
          type: string
        additional_file:
          description: 'Additional document file, such as the back side of an identity card.

            Accepted formats: PNG, JPEG, JPG, PDF.

            Max size: 10 MB. Max resolution: 20 mpx.

            '
          format: binary
          type: string
        workspace_id:
          description: 'Scopes the verification to a specific workspace.

            Defaults to the default workspace if not specified.

            '
          example: 9412b83b-b4b9-4a94-97b5-2b43dfa4cde3
          format: uuid
          nullable: true
          type: string
        workflow_session_id:
          $ref: '#/components/schemas/WorkflowSessionId'
        previous_attempt_id:
          $ref: '#/components/schemas/PreviousAttemptId'
        min_age:
          description: Minimum age required for the document holder.
          example: 18
          minimum: 1
          nullable: true
          type: integer
        max_age:
          description: Maximum age allowed for the document holder.
          example: 65
          minimum: 1
          nullable: true
          type: integer
        prohibited_countries:
          description: List of prohibited issuing countries (ISO 3166-1 alpha-2).
          example:
          - RU
          - KP
          items:
            pattern: ^[A-Z]{2}$
            type: string
          minItems: 1
          nullable: true
          type: array
      required:
      - file
      - first_name
      - last_name
      title: Initiate an Identity Document Verification with names
      type: object
    IdentityDocumentFull_allOf_data:
      properties:
        extracted_from_document:
          $ref: '#/components/schemas/IdentityDocumentFull_allOf_data_extracted_from_document'
      required:
      - extracted_from_document
      type: object
    WorkflowSessionId:
      description: 'Unique identifier of a Workflow Session. When provided, an Action is created in the Workflow Session, and this resource is associated with that Action.

        '
      example: 0ef334d2-7f36-4643-8a2a-4283b4a3e4a4
      format: uuid
      nullable: true
      title: Workflow Session identifier
      type: string
    IdentityDocumentFull_allOf_data_extracted_from_document:
      description: Information extracted from the verified identity document
      properties:
        first_name:
          description: The document holder's first name as it appears on the identity document
          example: John
          minLength: 1
          nullable: true
          type: string
        birth_name:
          description: The document holder's birth name (family name at birth)
          example: Doe
          minLength: 1
          nullable: true
          type: string
        last_name:
          description: The document holder's current last name (may differ from birth name)
          example: Doe
          minLength: 1
          nullable: true
          type: string
        born_on:
          description: The document holder's date of birth as it appears on the document
          example: '2024-01-18'
          format: date
          nullable: true
          type: string
        birth_location:
          description: The holder's place of birth as it appears on the document
          example: Paris
          minLength: 1
          nullable: true
          type: string
        gender:
          description: The holder's gender as it appears on the document. "m" for Male, "f" for Female, "x" for Non-binary or unspecified.
          enum:
          - f
          - m
          - x
          - null
          example: f
          nullable: true
          type: string
        full_address:
          description: The holder's complete postal address as it appears on the document
          example: '13 RUE SAINT MARCELIN

            MARSEILLE 10E (13)'
          minLength: 1
          nullable: true
          type: string
        type:
          description: The type of identity document that was verified
          enum:
          - id_card
          - passport
          - residence_permit
          - ita_ts_cns
          - null
          example: id_card
          nullable: true
          type: string
        issuing_country_code:
          description: The country that issued the document (ISO 3166-1 alpha-2 code)
          example: US
          format: ISO 3166-1 alpha-2
          nullable: true
          pattern: ^[A-Za-z]{2}$
          type: string
        issued_on:
          description: The date when the document was issued
          example: '2024-01-18'
          format: date
          nullable: true
          pattern: ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$
          type: string
        expired_on:
          description: The date when the document legally expires
          example: '2024-01-18'
          format: date
          nullable: true
          pattern: ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$
          type: string
        document_number:
          description: Document identifier number (may contain letters)
          example: X4RTBPFW4
          nullable: true
          type: string
        mrz:
          $ref: '#/components/schemas/IdentityDocumentFull_allOf_data_extracted_from_document_mrz'
        national_identification_number:
          description: 'Some documents may contain a national identification number.

            For example, Italian ID cards contain the Codice Fiscale on the back of the document.

            When this data is available on the document, it will be returned here, otherwise it will be NULL.

            Consult our [guide](https://developers.yousign.com/docs/identity-document-verification) for more details and examples.

            '
          example: MLLSNT82P65Z404U
          nullable: true
          type: string
      required:
      - birth_location
      - birth_name
      - born_on
      - document_number
      - expired_on
      - first_name
      - full_address
      - gender
      - issued_on
      - issuing_country_code
      - last_name
      - mrz
      - national_identification_number
      - type
      type: object
    IdentityDocumentFull_allOf_data_extracted_from_document_mrz:
      description: Machine Readable Zone content
      properties:
        line1:
          description: MRZ line 1
          example: IDFRASIAGRA<<<<<<<<<<<<<<<<<<<133039
          nullable: true
          type: string
        line2:
          description: MRZ line 2
          example: 1002133008071GREGOIRE<<REMY8110228M4
          nullable: true
          type: string
        line3:
          description: MRZ line 3
          example: <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
          nullable: true
          type: string
      required:
      - line1
      - line2
      - line3
      type: object
    Pagination:
      description: Metadata about the response.
      properties:
        next_cursor:
          description: 'Token to get the next page of results. If `null`, there are no more pages.

            '
          minLength: 1
          nullable: true
          type: string
      required:
      - next_cursor
      type: object
    IdentityDocumentStatus:
      description: Status of the Identity Document Verification
      enum:
      - pending
      - awaiting_data
      - verified
      - failed
      - inconclusive
      example: verified
      type: string
  examples:
    IdentityDocumentExample:
      summary: 'Pending - Verification Is In Progress: On Creation The Status Is Always Pending'
      value:
        id: aa8c4e74-ad8f-4a10-bd9d-5681bbf23572
        workspace_id: 9a93d3b5-fb3b-4abf-9e70-26315b33506c
        workflow_session_id: 0ef334d2-7f36-4643-8a2a-4283b4a3e4a4
        previous_attempt_id: 9412b83b-b4b9-4a94-97b5-2b43dfa4cde4
        applicant_id: null
        created_at: '2023-01-01T12:00:00+00:00'
        updated_at: '2023-01-01T12:00:00+00:00'
        status: pending
        status_codes: []
        data_anonymized: false
        data:
          extracted_from_document:
            first_name: null
            birth_name: null
            last_name: null
            born_on: null
            birth_location: null
            gender: null
            full_address: null
            type: null
            issuing_country_code: null
            issued_on: null
            expired_on: null
            document_number: null
            mrz:
              line1: null
              line2: null
              line3: null
            national_identification_number: null
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http