> ## Documentation Index
> Fetch the complete documentation index at: https://docs.services.payward.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit verification evidence

> Submit identity documents, residence documents, selfies, or liveness videos already verified by your provider. This endpoint is available only to approved partners. Provide each file through an HTTPS URL on an approved domain.

Include the verifier provenance in `partner_result`. Identity-document submissions must also include the original verifier response through either `response` or `response_file`; residence-document and selfie submissions may omit it. Use `response_file` for reports whose compact JSON representation exceeds 1 MiB (1,048,576 bytes). The user's identity and residence country come from their verification profile.

Reuse the same `Idempotency-Key` only when retrying the same submission. Reusing a key with a different submission is rejected. A successful response includes the verification identifier and its current lifecycle status. Follow verification status and webhook notifications for subsequent changes.



## OpenAPI

````yaml https://d2588n1sy4m36o.cloudfront.net/uat/merged/openapi.json post /v1/users/{user_id}/verifications/evidence
openapi: 3.1.0
info:
  title: PWS Public API
  version: '1'
  description: >-
    Integrate with Payward Services to onboard users, manage accounts and funds,
    trade assets, and receive event notifications.
  contact:
    name: Payward Services
servers:
  - url: https://api.sandbox.services.payward.com
security: []
tags:
  - name: Assets
    description: List the assets PWS is willing to swap.
    x-displayName: Assets
  - name: Conversions
    description: >-
      Rule-driven and on-demand fiat ↔ crypto value movement, including
      conversion rules and deposits.
    x-displayName: Conversions
  - name: Auto Earn
    description: >-
      Manage Auto Earn preferences and retrieve allocation and reward
      information.
    x-displayName: Auto Earn
  - name: Bonded Earn
    description: >-
      Allocate funds to and deallocate funds from bonded earn strategies, review
      allocations, and track request status.
    x-displayName: Bonded Earn
  - name: Funding
    description: >-
      Discover deposit and withdrawal options, manage deposit addresses, and
      move funds between accounts.
    x-displayName: Funding
  - name: Derivative transfers
    description: >-
      Move funds between an account's spot balance and the same owner's futures
      balance.
    x-displayName: Derivative transfers
  - name: Portfolio
    description: 'Inspect a customer''s portfolio: balances, valuations, and transactions.'
    x-displayName: Portfolio
  - name: Ramp
    description: >-
      Support Ramp flows with discovery, quotes, limits, and hosted checkout
      experiences.
    x-displayName: Ramp
  - name: Reports
    description: Settlement and reconciliation reports for the partner.
    x-displayName: Reports
  - name: Swaps
    description: Account-funded quotes that lock a price until they expire or are executed.
    x-displayName: Swaps
  - name: Onchain quotes
    description: Wallet-funded quotes that return the data needed to settle onchain.
    x-displayName: Onchain quotes
  - name: Price trigger swaps
    description: Swaps that wait for a target price before submitting a trade.
    x-displayName: Price trigger swaps
  - name: Travel Rule verifications
    description: Travel Rule address ownership verification flows.
    x-displayName: Travel Rule verifications
  - name: Users
    description: >-
      User onboarding and status flows that the partner manages.


      - **Create User** provisions an account-owned user from an external
      reference and optional email.

      - **Get User** retrieves the user's profile, verification status, and
      required actions.


      Use the returned user `id` for calls that require the user's identifier.
    x-displayName: Users
  - name: Verifications
    description: Identity verification (KYC) submission and status for end users.
    x-displayName: Verifications
  - name: Webhooks
    description: >-
      Register HTTPS destinations to receive event deliveries, rotate signing
      secrets, and inspect, update, or delete existing subscriptions. Each
      subscription is owned by the authenticated partner; deliveries are signed
      with HMAC-SHA256 and retried on transient failures.
    x-displayName: Webhooks
paths:
  /v1/users/{user_id}/verifications/evidence:
    post:
      tags:
        - Verifications
      summary: Submit verification evidence
      description: >-
        Submit identity documents, residence documents, selfies, or liveness
        videos already verified by your provider. This endpoint is available
        only to approved partners. Provide each file through an HTTPS URL on an
        approved domain.


        Include the verifier provenance in `partner_result`. Identity-document
        submissions must also include the original verifier response through
        either `response` or `response_file`; residence-document and selfie
        submissions may omit it. Use `response_file` for reports whose compact
        JSON representation exceeds 1 MiB (1,048,576 bytes). The user's identity
        and residence country come from their verification profile.


        Reuse the same `Idempotency-Key` only when retrying the same submission.
        Reusing a key with a different submission is rejected. A successful
        response includes the verification identifier and its current lifecycle
        status. Follow verification status and webhook notifications for
        subsequent changes.
      operationId: submitVerificationEvidence
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/RequiredIdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/Verifications_SubmitVerificationEvidenceRequestBody
            examples:
              verifications-evidence-identity-minimal:
                summary: Passport with an inline verifier response
                value:
                  type: identity_document
                  document:
                    type: passport
                    number: X12345678
                    issuing_country: US
                    front:
                      https_url: >-
                        https://your-allowlisted-bucket.s3.amazonaws.com/passport.jpg
                  partner_result:
                    verifier: partner-verifier
                    completed_at: '2026-09-21T10:00:00Z'
                    response:
                      status: approved
              verifications-evidence-identity-complete:
                summary: Two-sided identity document with a verifier report file
                value:
                  type: identity_document
                  document:
                    type: drivers_license
                    number: D1234567
                    issuing_country: US
                    nationality: US
                    expiration_date: '2030-04-15'
                    front:
                      https_url: >-
                        https://your-allowlisted-bucket.s3.amazonaws.com/identity-front.jpg
                    back:
                      https_url: >-
                        https://your-allowlisted-bucket.s3.amazonaws.com/identity-back.jpg
                  partner_result:
                    verifier: partner-verifier
                    verifier_reference: verification-123
                    completed_at: '2026-09-21T10:00:00Z'
                    response_file:
                      https_url: >-
                        https://your-allowlisted-bucket.s3.amazonaws.com/identity-result.json
              verifications-evidence-residence-minimal:
                summary: Residence evidence with verifier provenance
                value:
                  type: residence_document
                  address:
                    line1: 123 Example Street
                    city: San Francisco
                    postal_code: '94105'
                  document:
                    type: bank_statement
                    source:
                      https_url: >-
                        https://your-allowlisted-bucket.s3.amazonaws.com/bank-statement.pdf
                  partner_result:
                    verifier: partner-verifier
                    completed_at: '2026-09-21T10:00:00Z'
              verifications-evidence-residence-complete:
                summary: Residence certificate with an inline verifier response
                value:
                  type: residence_document
                  address:
                    line1: 123 Example Street
                    line2: Apartment 4B
                    city: San Francisco
                    province: CA
                    postal_code: '94105'
                  document:
                    type: residence_certificate
                    expiration_date: '2027-09-21'
                    source:
                      https_url: >-
                        https://your-allowlisted-bucket.s3.amazonaws.com/residence-certificate.pdf
                  partner_result:
                    verifier: partner-verifier
                    verifier_reference: verification-456
                    completed_at: '2026-09-21T10:00:00Z'
                    response:
                      status: approved
              verifications-evidence-selfie-minimal:
                summary: Selfie image with verifier provenance
                value:
                  type: selfie
                  selfie:
                    type: image
                    source:
                      https_url: >-
                        https://your-allowlisted-bucket.s3.amazonaws.com/selfie.jpg
                  partner_result:
                    verifier: partner-verifier
                    completed_at: '2026-09-21T10:00:00Z'
              verifications-evidence-selfie-complete:
                summary: Liveness video with a verifier report file
                value:
                  type: selfie
                  selfie:
                    type: video
                    source:
                      https_url: >-
                        https://your-allowlisted-bucket.s3.amazonaws.com/liveness.mp4
                  partner_result:
                    verifier: partner-verifier
                    verifier_reference: verification-789
                    completed_at: '2026-09-21T10:00:00Z'
                    response_file:
                      https_url: >-
                        https://your-allowlisted-bucket.s3.amazonaws.com/selfie-result.json
      responses:
        '200':
          description: Verification started.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: >-
                      #/components/schemas/Verifications_VerificationEvidenceSubmission
                required:
                  - data
              examples:
                started-verification:
                  summary: Verification started
                  value:
                    data:
                      verification_id: PVABCDE-FGHIJ-KLMNOP
                      status: started
          headers:
            X-Trace-Id:
              $ref: '#/components/headers/TraceId'
            Strict-Transport-Security:
              $ref: '#/components/headers/StrictTransportSecurity'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
        '400':
          $ref: '#/components/responses/VerificationsBadRequestResponse'
        '401':
          $ref: '#/components/responses/VerificationsUnauthenticatedResponse'
        '403':
          $ref: '#/components/responses/VerificationsForbiddenResponse'
        '409':
          $ref: '#/components/responses/VerificationsConflictResponse'
        '429':
          $ref: '#/components/responses/VerificationsResourceExhaustedResponse'
        '500':
          $ref: '#/components/responses/VerificationsInternalResponse'
        '501':
          $ref: '#/components/responses/VerificationsUnimplementedResponse'
        '503':
          $ref: '#/components/responses/VerificationsUnavailableResponse'
        '504':
          $ref: '#/components/responses/VerificationsDeadlineExceededResponse'
      security:
        - ApiKey: []
          ApiSign: []
          ApiTimestamp: []
      x-codeSamples:
        - lang: bash
          label: curl
          source: >-
            curl -X POST
            "https://api.sandbox.services.payward.com/v1/users/AA45N8G4MLDYWAR7/verifications/evidence"
            \
              -H "API-Key: $PWS_API_KEY" \
              -H "API-Timestamp: $PWS_API_TIMESTAMP" \
              -H "API-Sign: $PWS_API_SIGN" \
              -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
              -H "Content-Type: application/json" \
              -d '{
                "type": "identity_document",
                "document": {
                  "type": "passport",
                  "number": "X12345678",
                  "issuing_country": "US",
                  "front": {
                    "https_url": "https://your-allowlisted-bucket.s3.amazonaws.com/passport.jpg"
                  }
                },
                "partner_result": {
                  "verifier": "partner-verifier",
                  "completed_at": "2026-09-21T10:00:00Z",
                  "response": {
                    "status": "approved"
                  }
                }
              }'
components:
  parameters:
    UserId:
      name: user_id
      in: path
      required: true
      example: AA23N84GGQN4WE6I
      schema:
        $ref: '#/components/schemas/UserId'
    RequiredIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/IdempotencyKey'
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    Verifications_SubmitVerificationEvidenceRequestBody:
      description: Evidence of a check already completed by the partner's verifier.
      oneOf:
        - $ref: >-
            #/components/schemas/Verifications_SubmitIdentityDocumentEvidenceRequest
          title: Identity document
        - $ref: >-
            #/components/schemas/Verifications_SubmitResidenceDocumentEvidenceRequest
          title: Residence document
        - $ref: '#/components/schemas/Verifications_SubmitSelfieEvidenceRequest'
          title: Selfie
      discriminator:
        propertyName: type
        mapping:
          identity_document: >-
            #/components/schemas/Verifications_SubmitIdentityDocumentEvidenceRequest
          residence_document: >-
            #/components/schemas/Verifications_SubmitResidenceDocumentEvidenceRequest
          selfie: '#/components/schemas/Verifications_SubmitSelfieEvidenceRequest'
    Verifications_VerificationEvidenceSubmission:
      description: >-
        Identifier and current lifecycle status of an accepted partner-managed
        document submission.
      type: object
      properties:
        verification_id:
          type: string
          description: Public identifier for the verification submission.
          pattern: ^PV[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{6}$
          minLength: 20
          maxLength: 20
          example: PVABCDE-FGHIJ-KLMNOP
        status:
          $ref: '#/components/schemas/Verifications_VerificationStatus'
      required:
        - verification_id
        - status
    UserId:
      description: Globally unique public identifier for a user.
      type: string
      minLength: 14
      maxLength: 42
    IdempotencyKey:
      description: >-
        Client-generated canonical UUIDv4 that uniquely identifies a request for
        safe retries.
      type: string
      format: uuid
      pattern: >-
        ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
      example: 550e8400-e29b-41d4-a716-446655440000
    Verifications_SubmitIdentityDocumentEvidenceRequest:
      title: Identity document
      type: object
      description: >-
        Verified identity-document evidence. The user's name and date of birth
        are collected through the profile.
      additionalProperties: false
      properties:
        type:
          description: Selects an identity-document submission.
          type: string
          enum:
            - identity_document
        document:
          $ref: '#/components/schemas/Verifications_IdentityDocumentEvidence'
          description: Identity document and the images supporting the completed check.
        partner_result:
          $ref: '#/components/schemas/Verifications_PartnerVerificationResult'
          if:
            required:
              - response
          then:
            not:
              required:
                - response_file
          else:
            required:
              - response_file
          description: >-
            Provenance of the partner's identity-document check. Exactly one of
            `response` or `response_file` is required.
      required:
        - type
        - document
        - partner_result
    Verifications_SubmitResidenceDocumentEvidenceRequest:
      title: Residence document
      type: object
      description: >-
        Verified residence-document evidence. The user's residence country is
        collected through the profile.
      additionalProperties: false
      properties:
        type:
          description: Selects a residence-document submission.
          type: string
          enum:
            - residence_document
        address:
          $ref: '#/components/schemas/Verifications_ResidenceAddressEvidence'
          description: Address recorded on the verified residence document.
        document:
          $ref: '#/components/schemas/Verifications_ResidenceDocumentEvidence'
          description: Residence document supporting the completed address check.
        partner_result:
          $ref: '#/components/schemas/Verifications_PartnerVerificationResult'
          description: Provenance of the partner's residence-document check.
      required:
        - type
        - address
        - document
        - partner_result
    Verifications_SubmitSelfieEvidenceRequest:
      title: Selfie
      type: object
      description: >-
        Selfie image or liveness video already checked by the partner's
        verifier.
      additionalProperties: false
      properties:
        type:
          description: Selects a selfie submission.
          type: string
          enum:
            - selfie
        selfie:
          $ref: '#/components/schemas/Verifications_SelfieEvidence'
          description: Image or video supporting the completed selfie check.
        partner_result:
          $ref: '#/components/schemas/Verifications_PartnerVerificationResult'
          description: Provenance of the partner's selfie or liveness check.
      required:
        - type
        - selfie
        - partner_result
    Verifications_VerificationStatus:
      type: string
      description: Lifecycle status of a verification.
      enum:
        - started
        - pending
        - completed
        - failed
    BadRequestError:
      title: Bad Request
      description: Request validation failed or the request could not be processed.
      oneOf:
        - title: Bad Request
          allOf:
            - $ref: '#/components/schemas/PwsValidationErrorEnvelope'
            - type: object
              required:
                - error
              properties:
                error:
                  allOf:
                    - $ref: '#/components/schemas/PwsValidationError'
                    - type: object
                      required:
                        - status
                        - code
                      properties:
                        status:
                          type: integer
                          format: int32
                          const: 400
                        code:
                          type: string
                          enum:
                            - bad_request
        - title: Gateway
          description: >-
            Gateway-level validation failure returned before the request reaches
            the service.
          allOf:
            - $ref: '#/components/schemas/PwsValidationErrorEnvelope'
            - type: object
              required:
                - error
              properties:
                error:
                  allOf:
                    - $ref: '#/components/schemas/PwsValidationError'
                    - type: object
                      required:
                        - status
                        - code
                      properties:
                        type:
                          type: string
                          const: service_error
                        status:
                          type: integer
                          format: int32
                          const: 400
                        code:
                          type: string
                          const: gateway
    UnauthenticatedError:
      title: Unauthenticated
      description: Authentication credentials are missing, invalid, or not accepted.
      oneOf:
        - title: Unauthenticated
          allOf:
            - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
            - type: object
              required:
                - error
              properties:
                error:
                  allOf:
                    - $ref: '#/components/schemas/PwsGeneralError'
                    - type: object
                      required:
                        - status
                        - code
                      properties:
                        status:
                          type: integer
                          format: int32
                          const: 401
                        code:
                          type: string
                          enum:
                            - unauthenticated
        - title: Gateway
          description: Authentication failure returned by the API gateway.
          allOf:
            - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
            - type: object
              required:
                - error
              properties:
                error:
                  allOf:
                    - $ref: '#/components/schemas/PwsGeneralError'
                    - type: object
                      required:
                        - status
                        - code
                      properties:
                        type:
                          type: string
                          const: service_error
                        status:
                          type: integer
                          format: int32
                          const: 401
                        code:
                          type: string
                          const: gateway
    ForbiddenError:
      title: Forbidden
      description: The caller is not allowed to perform this operation.
      oneOf:
        - title: Forbidden
          allOf:
            - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
            - type: object
              required:
                - error
              properties:
                error:
                  allOf:
                    - $ref: '#/components/schemas/PwsGeneralError'
                    - type: object
                      required:
                        - status
                        - code
                      properties:
                        status:
                          type: integer
                          format: int32
                          const: 403
                        code:
                          type: string
                          enum:
                            - forbidden
        - title: Gateway
          description: Authorization failure returned by the API gateway.
          allOf:
            - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
            - type: object
              required:
                - error
              properties:
                error:
                  allOf:
                    - $ref: '#/components/schemas/PwsGeneralError'
                    - type: object
                      required:
                        - status
                        - code
                      properties:
                        type:
                          type: string
                          const: service_error
                        status:
                          type: integer
                          format: int32
                          const: 403
                        code:
                          type: string
                          const: gateway
    Verifications_ConflictError:
      description: The request conflicts with an existing resource or idempotency binding.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 409
                    code:
                      type: string
                      enum:
                        - conflict
    ResourceExhaustedError:
      description: The request was rate limited or a resource quota was exhausted.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 429
                    code:
                      type: string
                      enum:
                        - resource_exhausted
    InternalError:
      description: An unexpected server-side error occurred.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 500
                    code:
                      type: string
                      enum:
                        - internal
    UnimplementedError:
      description: The requested operation is not implemented.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 501
                    code:
                      type: string
                      enum:
                        - unimplemented
    UnavailableError:
      description: The service is temporarily unavailable.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 503
                    code:
                      type: string
                      enum:
                        - unavailable
    DeadlineExceededError:
      description: The request deadline was exceeded before a response could be produced.
      allOf:
        - $ref: '#/components/schemas/PwsGeneralErrorEnvelope'
        - type: object
          required:
            - error
          properties:
            error:
              allOf:
                - $ref: '#/components/schemas/PwsGeneralError'
                - type: object
                  required:
                    - status
                    - code
                  properties:
                    status:
                      type: integer
                      format: int32
                      const: 504
                    code:
                      type: string
                      enum:
                        - deadline_exceeded
    Verifications_IdentityDocumentEvidence:
      type: object
      description: Identity-document attributes and file sources.
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/Verifications_IdentityDocumentType'
          description: Kind of identity document submitted.
        number:
          type: string
          description: Identifier printed on the identity document.
          minLength: 1
          maxLength: 256
        issuing_country:
          $ref: '#/components/schemas/Verifications_CountryCode'
          description: Country that issued the identity document.
        nationality:
          $ref: '#/components/schemas/Verifications_CountryCode'
          description: Nationality of the holder as recorded on the document.
        expiration_date:
          $ref: '#/components/schemas/Verifications_EvidenceDocumentExpirationDate'
          description: Date on which the identity document expires.
        front:
          $ref: '#/components/schemas/Verifications_DocumentSource'
          description: Front or only image of the identity document.
        back:
          $ref: '#/components/schemas/Verifications_DocumentSource'
          description: >-
            Reverse side of the identity document, when applicable. Omit for
            passports.
      required:
        - type
        - number
        - issuing_country
        - front
    Verifications_PartnerVerificationResult:
      type: object
      description: >-
        Provenance of a check completed by the partner's verifier. The original
        verifier response may be supplied inline or by file; these fields are
        mutually exclusive. Omission leaves the submission without raw response
        evidence.
      additionalProperties: false
      not:
        required:
          - response
          - response_file
      properties:
        verifier:
          type: string
          description: Identifier of the partner or provider that performed the check.
          minLength: 1
          maxLength: 256
        verifier_reference:
          type: string
          description: Reference assigned by the verifier to this check.
          maxLength: 256
        completed_at:
          type: string
          format: date-time
          description: Time when the partner's verifier completed the check.
        response:
          type: object
          additionalProperties: true
          description: >-
            Original JSON object returned by the verifier. Its contents retain
            the verifier's own response structure.
        response_file:
          $ref: '#/components/schemas/Verifications_DocumentSource'
          description: Source file containing the original verifier response.
      required:
        - verifier
        - completed_at
    Verifications_ResidenceAddressEvidence:
      type: object
      description: >-
        Address shown by the residence evidence. The same collection rules apply
        to submissions for every country.
      additionalProperties: false
      properties:
        line1:
          type: string
          description: Street address shown by the document.
          minLength: 1
          maxLength: 256
        line2:
          type: string
          description: >-
            Apartment, suite, or additional address detail shown by the
            document.
          minLength: 1
          maxLength: 256
        city:
          type: string
          description: City shown by the document.
          minLength: 1
          maxLength: 128
        province:
          type: string
          description: State or province shown by the document.
          minLength: 1
          maxLength: 128
        postal_code:
          type: string
          description: Postal code shown by the document.
          minLength: 1
          maxLength: 32
      required:
        - line1
        - city
        - postal_code
    Verifications_ResidenceDocumentEvidence:
      type: object
      description: Residence-document attributes and file source.
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/Verifications_ResidenceDocumentType'
          description: Kind of residence document submitted.
        expiration_date:
          $ref: '#/components/schemas/Verifications_EvidenceDocumentExpirationDate'
          description: >-
            Date on which the residence document expires, when it has an expiry
            date.
        source:
          $ref: '#/components/schemas/Verifications_DocumentSource'
          description: File containing the verified residence document.
      required:
        - type
        - source
    Verifications_SelfieEvidence:
      type: object
      description: Media used by the verifier to check the user's selfie or liveness.
      additionalProperties: false
      properties:
        type:
          type: string
          description: >-
            Indicates whether the submitted file is a selfie image or a liveness
            video.
          enum:
            - image
            - video
        source:
          $ref: '#/components/schemas/Verifications_DocumentSource'
          description: File containing the verified selfie image or liveness video.
      required:
        - type
        - source
    PwsValidationErrorEnvelope:
      description: Error envelope for request validation failures.
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/PwsValidationError'
          description: Validation error details.
    PwsValidationError:
      description: Standard PWS API error object for request validation failures.
      type: object
      required:
        - type
        - status
        - instance
        - code
      properties:
        type:
          description: Machine-readable error class.
          type: string
        status:
          description: HTTP status code returned for this error.
          type: integer
          format: int32
        instance:
          description: Request identifier for this specific error occurrence.
          type: string
        code:
          description: Stable machine-readable error code.
          type: string
        doc_url:
          description: Optional link to documentation for this error.
          type: string
          format: uri
        causes:
          description: Validation failures that contributed to the error.
          type: array
          items:
            $ref: '#/components/schemas/PwsErrorCause'
    PwsGeneralErrorEnvelope:
      description: Error envelope for operational or domain failures.
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/PwsGeneralError'
          description: General error details.
    PwsGeneralError:
      description: Standard PWS API error object for non-validation failures.
      allOf:
        - $ref: '#/components/schemas/PwsErrorBase'
        - type: object
          properties:
            causes:
              description: Additional error details, when present.
              type: array
              items:
                type: object
                additionalProperties: true
    Verifications_IdentityDocumentType:
      type: string
      description: Type of identity verification document.
      enum:
        - passport
        - drivers_license
        - id_card
        - residence_card
        - special_permanent_residence_card
    Verifications_CountryCode:
      description: ISO 3166-1 alpha-2 country code.
      type: string
      enum:
        - AD
        - AE
        - AF
        - AG
        - AI
        - AL
        - AM
        - AO
        - AQ
        - AR
        - AS
        - AT
        - AU
        - AW
        - AX
        - AZ
        - BA
        - BB
        - BD
        - BE
        - BF
        - BG
        - BH
        - BI
        - BJ
        - BL
        - BM
        - BN
        - BO
        - BQ
        - BR
        - BS
        - BT
        - BV
        - BW
        - BY
        - BZ
        - CA
        - CC
        - CD
        - CF
        - CG
        - CH
        - CI
        - CK
        - CL
        - CM
        - CN
        - CO
        - CR
        - CU
        - CV
        - CW
        - CX
        - CY
        - CZ
        - DE
        - DJ
        - DK
        - DM
        - DO
        - DZ
        - EC
        - EE
        - EG
        - EH
        - ER
        - ES
        - ET
        - FI
        - FJ
        - FK
        - FM
        - FO
        - FR
        - GA
        - GB
        - GD
        - GE
        - GF
        - GG
        - GH
        - GI
        - GL
        - GM
        - GN
        - GP
        - GQ
        - GR
        - GS
        - GT
        - GU
        - GW
        - GY
        - HK
        - HM
        - HN
        - HR
        - HT
        - HU
        - ID
        - IE
        - IL
        - IM
        - IN
        - IO
        - IQ
        - IR
        - IS
        - IT
        - JE
        - JM
        - JO
        - JP
        - KE
        - KG
        - KH
        - KI
        - KM
        - KN
        - KP
        - KR
        - KW
        - KY
        - KZ
        - LA
        - LB
        - LC
        - LI
        - LK
        - LR
        - LS
        - LT
        - LU
        - LV
        - LY
        - MA
        - MC
        - MD
        - ME
        - MF
        - MG
        - MH
        - MK
        - ML
        - MM
        - MN
        - MO
        - MP
        - MQ
        - MR
        - MS
        - MT
        - MU
        - MV
        - MW
        - MX
        - MY
        - MZ
        - NA
        - NC
        - NE
        - NF
        - NG
        - NI
        - NL
        - 'NO'
        - NP
        - NR
        - NU
        - NZ
        - OM
        - PA
        - PE
        - PF
        - PG
        - PH
        - PK
        - PL
        - PM
        - PN
        - PR
        - PS
        - PT
        - PW
        - PY
        - QA
        - RE
        - RO
        - RS
        - RU
        - RW
        - SA
        - SB
        - SC
        - SD
        - SE
        - SG
        - SH
        - SI
        - SJ
        - SK
        - SL
        - SM
        - SN
        - SO
        - SR
        - SS
        - ST
        - SV
        - SX
        - SY
        - SZ
        - TC
        - TD
        - TF
        - TG
        - TH
        - TJ
        - TK
        - TL
        - TM
        - TN
        - TO
        - TR
        - TT
        - TV
        - TW
        - TZ
        - UA
        - UG
        - UM
        - US
        - UY
        - UZ
        - VA
        - VC
        - VE
        - VG
        - VI
        - VN
        - VU
        - WF
        - WS
        - YE
        - YT
        - ZA
        - ZM
        - ZW
        - AC
        - AN
        - AP
        - CP
        - DG
        - EA
        - EU
        - IC
        - JX
        - TA
        - QO
        - XK
        - 0C
      minLength: 2
      maxLength: 2
      example: US
    Verifications_EvidenceDocumentExpirationDate:
      type: string
      description: Date after which the submitted document is no longer valid.
      format: date
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
    Verifications_DocumentSource:
      type: object
      description: >-
        Source for one document role. This version requires an HTTPS URL. Future
        source forms extend this object without renaming the document role.
      additionalProperties: false
      properties:
        https_url:
          type: string
          description: >-
            HTTPS URL for the source document. The URL is forwarded unchanged
            and must meet the partner source policy.
          minLength: 1
          maxLength: 4096
          format: uri
          pattern: ^https://
          example: >-
            https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256
      required:
        - https_url
    Verifications_ResidenceDocumentType:
      type: string
      description: Type of residence verification document.
      enum:
        - bank_statement
        - credit_card_statement
        - employer_letter_or_work_contract
        - government_issued_document
        - home_or_rental_insurance
        - internet_or_cable_bill
        - mobile_phone_bill
        - mortgage_statement
        - official_government_letter
        - passport_address_page
        - rental_or_lease_agreement
        - residence_certificate
        - social_insurance_payment_receipt
        - tax_receipt
        - tax_return
        - utility_bill
        - other
    PwsErrorCause:
      description: A single request validation failure.
      type: object
      required:
        - field
        - message
      properties:
        field:
          description: Dot-notation path to the offending request field.
          type: string
        message:
          description: Human-readable explanation of the failed validation rule.
          type: string
    PwsErrorBase:
      description: Common fields present on every PWS API error object.
      type: object
      required:
        - type
        - status
        - instance
        - code
      properties:
        type:
          description: Machine-readable error class.
          type: string
        status:
          description: HTTP status code returned for this error.
          type: integer
          format: int32
        instance:
          description: Request identifier for this specific error occurrence.
          type: string
        code:
          description: Stable machine-readable error code.
          type: string
        doc_url:
          description: Optional link to documentation for this error.
          type: string
          format: uri
  headers:
    TraceId:
      description: Trace identifier for the request. Include it when contacting support.
      schema:
        type: string
        example: 4bf92f3577b34da6a3ce929d0e0e4736
    StrictTransportSecurity:
      description: Enforces HTTPS for the duration specified by `max-age`.
      schema:
        type: string
        example: max-age=31536000; includeSubDomains; preload
    CacheControl:
      description: Prevents caching of sensitive financial data. Always `no-store`.
      schema:
        type: string
        enum:
          - no-store
        example: no-store
  responses:
    VerificationsBadRequestResponse:
      description: Validation error
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
          examples:
            bad-request:
              value:
                error:
                  type: validation_error
                  status: 400
                  instance: req_123
                  code: bad_request
    VerificationsUnauthenticatedResponse:
      description: Authentication required
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthenticatedError'
          examples:
            unauthenticated:
              value:
                error:
                  type: authentication_error
                  status: 401
                  instance: req_123
                  code: unauthenticated
    VerificationsForbiddenResponse:
      description: >-
        The API gateway rejected the request (`gateway`), for example because
        `user_id` doesn't identify one of your users, or the service refused the
        operation (`forbidden`). Branch on `error.code`.
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
          examples:
            forbidden:
              value:
                error:
                  type: authorization_error
                  status: 403
                  instance: req_123
                  code: forbidden
            unknown-user:
              summary: The user ID doesn't identify one of your users
              value:
                error:
                  type: service_error
                  status: 403
                  instance: req_123
                  code: gateway
    VerificationsConflictResponse:
      description: The idempotency key is already bound to different metadata or sources.
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Verifications_ConflictError'
          examples:
            conflict:
              value:
                error:
                  type: api_error
                  status: 409
                  instance: req_123
                  code: conflict
    VerificationsResourceExhaustedResponse:
      description: Rate limit exceeded
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceExhaustedError'
          examples:
            resource-exhausted:
              value:
                error:
                  type: rate_limit_error
                  status: 429
                  instance: req_123
                  code: resource_exhausted
    VerificationsInternalResponse:
      description: Internal server error
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalError'
          examples:
            internal-error:
              value:
                error:
                  type: internal_error
                  status: 500
                  instance: req_123
                  code: internal
    VerificationsUnimplementedResponse:
      description: Error response
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnimplementedError'
          examples:
            unimplemented:
              value:
                error:
                  type: api_error
                  status: 501
                  instance: req_123
                  code: unimplemented
    VerificationsUnavailableResponse:
      description: Service unavailable
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnavailableError'
          examples:
            unavailable:
              value:
                error:
                  type: service_error
                  status: 503
                  instance: req_123
                  code: unavailable
    VerificationsDeadlineExceededResponse:
      description: Deadline exceeded
      headers:
        X-Trace-Id:
          $ref: '#/components/headers/TraceId'
        Strict-Transport-Security:
          $ref: '#/components/headers/StrictTransportSecurity'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeadlineExceededError'
          examples:
            deadline-exceeded:
              value:
                error:
                  type: service_error
                  status: 504
                  instance: req_123
                  code: deadline_exceeded
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: API-Key
      description: Your public API key. Identifies the partner making the request.
    ApiSign:
      type: apiKey
      in: header
      name: API-Sign
      description: HMAC signature over the request, computed with your private key.
    ApiTimestamp:
      type: apiKey
      in: header
      name: API-Timestamp
      description: >-
        Time the request was signed, as Unix milliseconds. Included in the
        request signature. Requests signed too far from the server's time are
        rejected.

````