Adyen Documents API

openapi: 3.2.0
info:
  version: '3'
  x-publicVersion: true
  title: Adyen Legal Entity Management Documents API
  description: The Legal Entity Management API enables you to manage legal entities that contain information required for verification.
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
servers:
- url: https://kyc-test.adyen.com/lem/v3
tags:
- name: Documents
paths:
  /documents:
    post:
      tags:
      - Documents
      summary: Adyen Upload a Document for Verification Checks
      description: "Uploads a document for verification checks.\n\n Adyen uses the information from the [legal entity](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/legalEntities) to run automated verification checks. If these checks fail, you will be notified to provide additional documents.\n\n You should only upload documents when Adyen requests additional information for the legal entity.\n\n >You can upload a maximum of 15 pages for photo IDs."
      x-addedInVersion: '1'
      operationId: post-documents
      x-sortIndex: 4
      x-methodName: uploadDocumentForVerificationChecks
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              uploadDocument:
                $ref: '#/components/examples/post-documents-uploadDocument'
            schema:
              $ref: '#/components/schemas/Document'
      parameters:
      - description: Use a suberror code as your requested verification code. You can include one code at a time in your request header. Requested verification codes can only be used in your test environment.
        example: '1_3008'
        name: x-requested-verification-code
        in: header
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                uploadDocument:
                  $ref: '#/components/examples/post-documents-uploadDocument-200'
              schema:
                $ref: '#/components/schemas/Document'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-documents400Example:
                  summary: Default post-documents 400 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-documents401Example:
                  summary: Default post-documents 401 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-documents403Example:
                  summary: Default post-documents 403 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-documents422Example:
                  summary: Default post-documents 422 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-documents500Example:
                  summary: Default post-documents 500 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{id}:
    delete:
      tags:
      - Documents
      summary: Adyen Delete a Document
      description: Deletes a document.
      x-addedInVersion: '1'
      operationId: delete-documents-id
      x-sortIndex: 7
      x-methodName: deleteDocument
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: The unique identifier of the document to be deleted.
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'No Content - look at the actual response code for the status of the request. '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                delete-documents-id400Example:
                  summary: Default delete-documents-id 400 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                delete-documents-id401Example:
                  summary: Default delete-documents-id 401 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                delete-documents-id403Example:
                  summary: Default delete-documents-id 403 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                delete-documents-id422Example:
                  summary: Default delete-documents-id 422 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                delete-documents-id500Example:
                  summary: Default delete-documents-id 500 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      tags:
      - Documents
      summary: Adyen Get a Document
      description: Returns a document.
      x-addedInVersion: '1'
      operationId: get-documents-id
      x-sortIndex: 5
      x-methodName: getDocument
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: The unique identifier of the document.
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  $ref: '#/components/examples/get-documents-id-success-200'
              schema:
                $ref: '#/components/schemas/Document'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                get-documents-id400Example:
                  summary: Default get-documents-id 400 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                get-documents-id401Example:
                  summary: Default get-documents-id 401 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                get-documents-id403Example:
                  summary: Default get-documents-id 403 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                get-documents-id422Example:
                  summary: Default get-documents-id 422 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                get-documents-id500Example:
                  summary: Default get-documents-id 500 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      tags:
      - Documents
      summary: Adyen Update a Document
      description: "Updates a document.\n\n >You can upload a maximum of 15 pages for photo IDs."
      x-addedInVersion: '1'
      operationId: patch-documents-id
      x-sortIndex: 6
      x-methodName: updateDocument
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              updateDocument:
                $ref: '#/components/examples/patch-documents-id-updateDocument'
            schema:
              $ref: '#/components/schemas/Document'
      parameters:
      - description: The unique identifier of the document to be updated.
        name: id
        in: path
        required: true
        schema:
          type: string
      - description: Use the requested verification code 0_0001 to resolve any suberrors associated with the document. Requested verification codes can only be used in your test environment.
        example: '0_0001'
        name: x-requested-verification-code
        in: header
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                updateDocument:
                  $ref: '#/components/examples/patch-documents-id-updateDocument-200'
              schema:
                $ref: '#/components/schemas/Document'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                patch-documents-id400Example:
                  summary: Default patch-documents-id 400 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                patch-documents-id401Example:
                  summary: Default patch-documents-id 401 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                patch-documents-id403Example:
                  summary: Default patch-documents-id 403 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                patch-documents-id422Example:
                  summary: Default patch-documents-id 422 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                patch-documents-id500Example:
                  summary: Default patch-documents-id 500 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Document:
      properties:
        attachment:
          deprecated: true
          x-deprecatedInVersion: '1'
          x-deprecatedMessage: Use the `attachments` array instead.
          description: Object that contains the document.
          $ref: '#/components/schemas/Attachment'
        attachments:
          description: Array that contains the document. The array supports multiple attachments for uploading different sides or pages of a document.
          items:
            $ref: '#/components/schemas/Attachment'
          type: array
        creationDate:
          description: The creation date of the document.
          format: date-time
          readOnly: true
          type: string
        description:
          description: Your description for the document.
          type: string
        expiryDate:
          deprecated: true
          x-deprecatedInVersion: '1'
          description: The expiry date of the document, in YYYY-MM-DD format.
          type: string
        fileName:
          description: The filename of the document.
          type: string
        id:
          description: The unique identifier of the document.
          readOnly: true
          type: string
        issuerCountry:
          deprecated: true
          x-deprecatedInVersion: '1'
          description: The two-character [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code where the document was issued. For example, **US**.
          type: string
        issuerState:
          deprecated: true
          x-deprecatedInVersion: '1'
          description: The state or province where the document was issued (AU only).
          type: string
        modificationDate:
          description: The modification date of the document.
          format: date-time
          readOnly: true
          type: string
        number:
          description: The number in the document.
          type: string
        owner:
          description: Contains information about the resource that owns the document.
          $ref: '#/components/schemas/OwnerEntity'
        type:
          description: 'Type of document, used when providing an ID number or uploading a document. The possible values depend on the legal entity type.


            * For **organization**, the `type` values can be **proofOfAddress**, **registrationDocument**, **vatDocument**, **proofOfOrganizationTaxInfo**, **proofOfOwnership**, **proofOfIndustry**, or **proofOfFundingOrWealthSource**.


            * For **individual**, the `type` values can be **identityCard**, **driversLicense**, **passport**, **proofOfNationalIdNumber**, **proofOfResidency**, **proofOfIndustry**, **proofOfIndividualTaxId**, or **proofOfFundingOrWealthSource**.


            * For **soleProprietorship**, the `type` values can be **constitutionalDocument**, **proofOfAddress**, or **proofOfIndustry**.


            * Use **bankStatement** to upload documents for a [transfer instrument](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments__resParam_id).'
          enum:
          - bankStatement
          - driversLicense
          - identityCard
          - nationalIdNumber
          - passport
          - proofOfAddress
          - proofOfNationalIdNumber
          - proofOfResidency
          - registrationDocument
          - vatDocument
          - proofOfOrganizationTaxInfo
          - proofOfIndustry
          - constitutionalDocument
          - proofOfFundingOrWealthSource
          type: string
      required:
      - description
      - type
      type: object
    OwnerEntity:
      properties:
        id:
          description: Unique identifier of the resource that owns the document. For `type` **legalEntity**, this value is the unique identifier of the [legal entity](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id). For `type` **bankAccount**, this value is the unique identifier of the [transfer instrument](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments#responses-200-id).
          type: string
        type:
          description: 'Type of resource that owns the document.


            Possible values: **legalEntity**, **bankAccount**.'
          type: string
      required:
      - id
      - type
      type: object
    Attachment:
      properties:
        content:
          description: The document in Base64-encoded string format.
          format: byte
          type: string
        contentType:
          deprecated: true
          x-deprecatedInVersion: '1'
          description: "The file format.\n\n Possible values: **application/pdf**, **image/jpg**, **image/jpeg**, **image/png**. "
          type: string
        filename:
          deprecated: true
          x-deprecatedInVersion: '1'
          description: The name of the file including the file extension.
          type: string
        pageName:
          x-addedInVersion: '2'
          description: The name of the file including the file extension.
          type: string
        pageType:
          description: 'Specifies which side of the ID card is uploaded.


            * When `type` is **driversLicense** or **identityCard**, set this to **front** or **back**.


            * When omitted, we infer the page number based on the order of attachments.'
          type: string
      required:
      - content
      type: object
    ServiceError:
      properties:
        errorCode:
          description: The error code mapped to the error message.
          type: string
        errorType:
          description: The category of the error.
          type: string
        message:
          description: A short explanation of the issue.
          type: string
        pspReference:
          description: The PSP reference of the payment.
          type: string
        status:
          description: The HTTP response status.
          format: int32
          type: integer
      type: object
  examples:
    post-documents-uploadDocument:
      summary: Upload a document
      description: Example request for uploading a document
      value:
        type: registrationDocument
        attachments:
        - content: JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBv+f/ub0j6JPRX+E3EmC==
        description: Registration doc for Example Company
        owner:
          id: LE00000000000000000000001
          type: legalEntity
    patch-documents-id-updateDocument:
      summary: Update a document
      description: Example request for updating a document
      value:
        type: proofOfIndustry
        description: Proof of industry doc for Example Company
    patch-documents-id-updateDocument-200:
      summary: Document updated
      description: Example response when a document is updated
      value:
        type: proofOfIndustry
        attachments:
        - content: JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBv+f/ub0j6JPRX+E3EmC==
        description: Proof of industry for Example Company
        fileName: Proof of industry for Example Company
        owner:
          id: LE00000000000000000000001
          type: legalEntity
        id: SE322JV223222F5GV2N9L8GDK
    get-documents-id-success-200:
      summary: Details of a document
      description: Example response when getting document details
      value:
        type: registrationDocument
        attachments:
        - content: JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBv+f/ub0j6JPRX+E3EmC==
        description: Registration doc for Example Company
        fileName: Registration doc for Example Company
        owner:
          id: LE00000000000000000000001
          type: legalEntity
        id: SE322JV223222F5GV2N9L8GDK
    post-documents-uploadDocument-200:
      summary: Document uploaded
      description: Example response when a document is uploaded
      value:
        type: registrationDocument
        attachments:
        - content: JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBv+f/ub0j6JPRX+E3EmC==
        description: Registration doc for Example Company
        fileName: Registration doc for Example Company
        owner:
          id: LE00000000000000000000001
          type: legalEntity
        id: SE322JV223222F5GV2N9L8GDK
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http