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.


        Adyen uses the information from the legal entity to run automated verification checks. If these checks fail, you will be notified to provide additional documents.


        You should only upload documents when Adyen requests additional information for the legal entity.


        >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.


        >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:
  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
    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
    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
  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
    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
    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
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http