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 Proof of Address 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 a proof of address document.
  name: Proof of Address Verification
paths:
  /verifications/proofs_of_address:
    get:
      description: 'Returns the list of all Proof of Address 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/proof-of-address-verification) for more details and examples.

        '
      operationId: get-verifications-proofs_of_address
      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_proofs_of_address_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 Proof of Address Verifications
      tags:
      - Proof of Address Verification
    post:
      description: 'Ask for a Proof of Address Verification by sending a supported document type (see our [guide](https://developers.yousign.com/docs/proof-of-address-verification) for more info).


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

        - 📁 `multipart/form-data` — upload a binary file containing the proof of address.

        - 📝 `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 - Proof of address check`

        '
      operationId: post-verifications-proofs_of_address
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateProofOfAddressFromApplicant'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/InitiateProofOfAddress'
      responses:
        '201':
          content:
            application/json:
              examples:
                pending:
                  $ref: '#/components/examples/ProofOfAddressExample'
              schema:
                $ref: '#/components/schemas/ProofOfAddressFull'
          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 Proof of Address Verification
      tags:
      - Proof of Address Verification
      x-readme:
        explorer-enabled: false
  /verifications/proofs_of_address/{proofOfAddressVerificationId}:
    get:
      description: Get the detailed results of a Proof of Address Verification.
      operationId: get-verifications-proofs_of_address-id
      parameters:
      - description: Proof of Address Verification Id
        in: path
        name: proofOfAddressVerificationId
        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: '2025-02-12T23:59:59+00:00'
                    updated_at: '2025-02-12T23:59:59+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
                        last_name: Doe
                        full_address: Rue De Suède Av Pierre Berthelot 14000 CAEN
                        issued_on: '2022-01-01'
                        document_type: tax_notice
                        2d_doc:
                          full_name: John Doe
                          address:
                            line1: 18 rue de Londres
                            postal_code: '75008'
                            city: Paris
                            country_code: FR
              schema:
                $ref: '#/components/schemas/ProofOfAddressFull'
          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 a Proof of Address Verification
      tags:
      - Proof of Address 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
    ProofOfAddressFull_allOf_data_extracted_from_document_2d_doc_address:
      description: If found, the address extracted from the 2D-Doc.
      properties:
        line1:
          description: The street type, name and number.
          example: 18 rue de Londres
          minLength: 1
          nullable: true
          type: string
        postal_code:
          description: The postal code.
          example: '75008'
          minLength: 1
          nullable: true
          type: string
        city:
          description: The city name.
          example: Paris
          minLength: 1
          nullable: true
          type: string
        country_code:
          example: FR
          format: ISO 3166-1 alpha-2
          maxLength: 2
          minLength: 1
          nullable: true
          pattern: ^[A-Za-z]{2}$
          type: string
      required:
      - city
      - country_code
      - line1
      - postal_code
      type: object
    TooManyRequestsResponse:
      properties:
        message:
          type: string
      required:
      - message
      title: TooManyRequestsResponse
      type: object
    InitiateProofOfAddressFromApplicant:
      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 Proof of Address Verification to an Applicant
      type: object
    ProofOfAddressFull_allOf_data:
      properties:
        extracted_from_document:
          $ref: '#/components/schemas/ProofOfAddressFull_allOf_data_extracted_from_document'
      required:
      - extracted_from_document
      type: object
    ProofOfAddressFull:
      allOf:
      - $ref: '#/components/schemas/ProofOfAddressMeta'
      - properties:
          data:
            $ref: '#/components/schemas/ProofOfAddressFull_allOf_data'
        required:
        - data
        type: object
      title: ProofOfAddressFull
      type: object
    get_verifications_proofs_of_address_200_response:
      properties:
        meta:
          $ref: '#/components/schemas/Pagination'
        data:
          items:
            $ref: '#/components/schemas/ProofOfAddressMeta'
          type: array
      type: object
    UnsupportedMediaTypeResponse:
      properties:
        type:
          type: string
        detail:
          type: string
      required:
      - detail
      - type
      title: UnsupportedMediaTypeResponse
      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
    InitiateProofOfAddress_natural_person_address:
      additionalProperties: false
      description: Provide the holder full address, exactly as it should appear on the proof of address document.
      nullable: true
      properties:
        line1:
          description: The first line of the address, typically the street name and number.
          example: Rue De Suède
          maxLength: 500
          minLength: 1
          type: string
        line2:
          description: If needed, the second line of the address, typically an apartment or suite number.
          maxLength: 500
          minLength: 1
          nullable: true
          type: string
          example: null
        postal_code:
          description: The postal code of the address.
          example: '14000'
          maxLength: 10
          minLength: 1
          type: string
        city:
          description: The city of the address.
          example: CAEN
          maxLength: 200
          minLength: 1
          type: string
      required:
      - city
      - line1
      - postal_code
      type: object
    BadRequestResponse:
      properties:
        type:
          type: string
        detail:
          type: string
      required:
      - detail
      - type
      title: BadRequestResponse
      type: object
    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
    WorkflowSessionApplicantId:
      description: 'Unique identifier of an Applicant.

        '
      example: 0ef334d2-7f36-4643-8a2a-4283b4a3e4a4
      format: uuid
      nullable: true
      title: Applicant
      type: string
    UUID:
      description: The unique identifier for a resource.
      example: 9a93d3b5-fb3b-4abf-9e70-26315b33506c
      format: uuid
      type: string
    ProofOfAddressFull_allOf_data_extracted_from_document_2d_doc:
      description: Data extracted from the 2D-Doc if the document has one.
      properties:
        full_name:
          description: If found, the full name extracted from the 2D-Doc.
          example: John Doe
          minLength: 1
          nullable: true
          type: string
        address:
          $ref: '#/components/schemas/ProofOfAddressFull_allOf_data_extracted_from_document_2d_doc_address'
      required:
      - address
      - full_name
      type: object
    ProofOfAddressMeta:
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        workspace_id:
          description: The Workspace ID in which the Proof of Address Verification has been created.
          example: 9a93d3b5-fb3b-4abf-9e70-26315b33506c
          format: uuid
          type: string
        created_at:
          description: Creation date of the Proof of Address Verification.
          example: '2025-02-12T23:59:59Z'
          format: date-time
          type: string
        updated_at:
          description: Update date of the Proof of Address Verification.
          example: '2025-02-12T23:59:59Z'
          format: date-time
          type: string
        status:
          description: Status of the verification
          enum:
          - pending
          - awaiting_data
          - verified
          - failed
          - inconclusive
          example: failed
          type: string
        status_codes:
          description: List of status codes. Indicates the cause when the status is `failed` or `inconclusive`.
          example:
          - POAV_1611
          - POAV_1612
          items:
            type: string
          type: array
        data_anonymized:
          description: 'Indicates if the data related to the ProofOfAddress Verification has been anonymized.

            If set to `true`, the data are removed 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: ProofOfAddressMeta
      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
    InitiateProofOfAddress_natural_person:
      additionalProperties: false
      properties:
        first_name:
          description: 'Provide the holder first name, exactly as it should appear on the proof of address 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.

            This field can not be submitted without field "last_name".

            '
          example: John
          maxLength: 255
          minLength: 1
          nullable: true
          type: string
        last_name:
          description: 'Provide the holder last name, exactly as it should appear on the proof of address 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.

            This field can not be submitted without field "first_name".

            '
          example: Doe
          maxLength: 255
          minLength: 1
          nullable: true
          type: string
        address:
          $ref: '#/components/schemas/InitiateProofOfAddress_natural_person_address'
      type: object
    ProofOfAddressFull_allOf_data_extracted_from_document:
      description: Data extracted from the provided proof of address document
      properties:
        first_name:
          description: If found, the first name as it appeared on the document.
          example: John
          minLength: 1
          nullable: true
          type: string
        last_name:
          description: If found, the last name as it appeared on the document.
          example: Doe
          minLength: 1
          nullable: true
          type: string
        full_address:
          description: If found, the address as it appeared on the document.
          example: Rue De Suède Av Pierre Berthelot 14000 CAEN
          minLength: 1
          nullable: true
          type: string
        issued_on:
          description: If found, the document's issuance date as it appeared on the document.
          example: '2022-01-01'
          format: date
          nullable: true
          type: string
        document_type:
          description: The type of document that was verified
          enum:
          - driver_license
          - energy_invoice
          - energy_schedule
          - family_allowance
          - id_card
          - insurance_attestation
          - italian_national_service_card
          - local_residence_tax_notice
          - passport
          - payslip
          - photograph
          - phone_invoice
          - property_tax_notice
          - provider_attestation
          - residence_permit
          - retirement_pension
          - rib
          - tax_justification
          - tax_notice
          - vehicle_registration_certificate
          example: tax_notice
          nullable: true
          type: string
        2d_doc:
          $ref: '#/components/schemas/ProofOfAddressFull_allOf_data_extracted_from_document_2d_doc'
      required:
      - 2d_doc
      - first_name
      - full_address
      - issued_on
      - last_name
      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
    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
    InitiateProofOfAddress:
      additionalProperties: false
      properties:
        file:
          description: 'The proof of address document.

            Accepted formats: PNG, JPEG, JPG, PDF.

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

            '
          format: binary
          type: string
        natural_person:
          $ref: '#/components/schemas/InitiateProofOfAddress_natural_person'
        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'
      required:
      - file
      title: Create Proof of Address Verification
      type: object
  examples:
    ProofOfAddressExample:
      summary: 'Pending - Verification Is In Progress: On Creation The Status Is Always Pending'
      value:
        id: 1b671a64-40d5-491e-99b0-da01ff1f3341
        workspace_id: 9412b83b-b4b9-4a94-97b5-2b43dfa4cde3
        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
            last_name: null
            full_address: null
            issued_on: null
            2d_doc:
              full_name: null
              address:
                line1: null
                postal_code: null
                city: null
                country_code: null
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http