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

# Attach Documents to Individual Customer

> Attach identifying and address documents to an existing individual customer, using separate identifying_documents and address_documents arrays. Documents are processed asynchronously.

> [!NOTE]
>
> * Upload files first using the [Upload document](https://docs.engagexpay.com/api-reference/customers/upload-document) endpoint to obtain the URIs needed for the `files` arrays, then reference them here.
> * The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter returned from the Create Individual Customer endpoint.
> * Maximum file size is 5 MB per file.

## Prerequisites

The customer must satisfy `customer_type = INDIVIDUAL`, `api_version = v2`, and a `customer_status` of `INCOMPLETE` or `ACTION_REQUIRED`. Any other state returns `403`. Only one attach can be in flight per customer; a second concurrent attach returns `409`.

## Identity Document Side Requirements

| Type | Files | Sides |
| - | - | - |
| `PASSPORT` | 1 | Side optional |
| `NATIONAL_ID` | 2 | One `FRONT` and one `BACK` |
| `DRIVERS_LICENSE` | 2 | One `FRONT` and one `BACK` |
| `RESIDENCE_PERMIT` | 2 | One `FRONT` and one `BACK` |
| `SELFIE` | 1 | Side optional |

## Key Rules

* At most one non-SELFIE document may be included in `identifying_documents`. To switch the primary document type, re-attach with the new type.
* `state` is required when `type` is `DRIVERS_LICENSE` and `country` is `USA`. It is optional for a `DRIVERS_LICENSE` issued elsewhere, and forbidden for `PASSPORT`, `NATIONAL_ID`, and `RESIDENCE_PERMIT`.
* Exactly one `address_documents` entry is required.
* File URIs must be unique across the entire request (SELFIE files excluded) and must belong to this customer.
* A `SELFIE` entry may be required depending on your client configuration. When required, include exactly one `SELFIE` entry carrying at least one file.


## OpenAPI

````yaml POST /v2/customers/{customer_id}/individual/attach
openapi: 3.1.0
info:
  title: EngageXPay API
  version: 1.0.0
  description: >-
    A simple API specification for EngageXPay, a financial services platform
    that provides a range of banking and payment solutions for businesses and
    individuals. This API allows developers to integrate EngageXPay's services
    into their applications, enabling functionalities such as customer
    management, transaction processing, and access to financial data.
servers:
  - url: https://sandbox.api.engagexpay.com
    description: Sandbox server
  - url: https://api.engagexpay.com
    description: Production server
security: []
tags:
  - name: Authentication
    description: A modified OAuth 2.0 Client Credential Flow
  - name: Customers
    description: Customer management and document upload operations
  - name: Balances
    description: Retrieve wallet balance information
  - name: Catalogue
    description: |
      A set of endpoints to retrieve contextual data to assemble requests
      to EngageXPay's API
  - name: Beneficiaries
    description: Manage beneficiary accounts for payments and transfers
  - name: Transactions
    description: Transaction history and management for beneficiaries
  - name: Virtual Accounts
    description: Create and manage virtual accounts for USD to USDC conversions
  - name: Fees & FX Rates
    description: Retrieve fees and foreign exchange rates
paths:
  /v2/customers/{customer_id}/individual/attach:
    post:
      tags:
        - Customers
      summary: Attach Documents to Individual Customer
      description: >-
        Attach identifying and address documents to an existing individual
        customer, using separate identifying_documents and address_documents
        arrays. Documents are processed asynchronously.
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier for the individual customer
          example: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachDocumentsToIndividualCustomerV2Input'
            example:
              identifying_documents:
                - type: SELFIE
                  files:
                    - uri: /AbAcQ4hn_0652746727637.pdf
                - type: DRIVERS_LICENSE
                  number: DL987654321
                  country: USA
                  state: US-CA
                  issue_date: '2019-06-01'
                  expiry_date: '2029-06-01'
                  files:
                    - side: FRONT
                      uri: /AbAcQ4hn_0652746727638.pdf
                    - side: BACK
                      uri: /XyZ123mn_0652746727639.pdf
              address_documents:
                - type: BANK_STATEMENT
                  country: USA
                  files:
                    - uri: /PoAdef45_0652746727640.pdf
              tos_policies_value: e9414388-fbdf-4407-b5c2-bc39eae3645b
      responses:
        '200':
          description: Request validated and queued for asynchronous processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      customer_id:
                        type: string
                        format: uuid
                        example: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9
                  meta:
                    type: object
                    nullable: true
                    example: null
        '400':
          description: Malformed JSON or unparseable payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: Malformed request body
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          description: >-
            Customer not owned by the client, wrong api_version, or not in an
            allowed status, or a file URI does not belong to the customer
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: forbidden
                      message:
                        type: string
                        example: Customer is not eligible for this operation
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Another attach for this customer is already in flight
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: conflict
                      message:
                        type: string
                        example: >-
                          An attach request is already in progress for this
                          customer
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal server error
      security:
        - bearerAuth: []
components:
  schemas:
    AttachDocumentsToIndividualCustomerV2Input:
      type: object
      required:
        - identifying_documents
        - address_documents
        - tos_policies_value
      properties:
        identifying_documents:
          type: array
          minItems: 1
          description: >-
            Government-issued identity documents. Include at most one non-SELFIE
            primary document (PASSPORT, NATIONAL_ID, DRIVERS_LICENSE, or
            RESIDENCE_PERMIT) plus an optional SELFIE entry. NATIONAL_ID,
            DRIVERS_LICENSE, and RESIDENCE_PERMIT require both FRONT and BACK
            files.
          items:
            $ref: '#/components/schemas/V2IndividualAttachIdentifyingDocument'
        address_documents:
          type: array
          minItems: 1
          maxItems: 1
          description: Proof of address. Exactly one entry is required.
          items:
            $ref: '#/components/schemas/V2IndividualAddressDocument'
        tos_policies_value:
          type: string
          description: >-
            Parsed from the tos_policies_value query parameter in the
            tos_policies_url returned by POST /v2/customers/individual.
            Signifies the customer has accepted the Terms of Service.
          example: e9414388-fbdf-4407-b5c2-bc39eae3645b
    V2IndividualAttachIdentifyingDocument:
      type: object
      required:
        - type
        - files
      allOf:
        - if:
            properties:
              type:
                const: DRIVERS_LICENSE
              country:
                const: USA
            required:
              - type
              - country
          then:
            required:
              - state
      properties:
        type:
          type: string
          enum:
            - PASSPORT
            - NATIONAL_ID
            - DRIVERS_LICENSE
            - RESIDENCE_PERMIT
            - SELFIE
          description: >-
            Type of identity document. At most one non-SELFIE document may be
            included per request. A SELFIE entry carries only `type` and
            `files`; all other fields are ignored for SELFIE.
          example: PASSPORT
        number:
          type: string
          description: Document number. Required for all types except SELFIE.
          example: A12345678
        country:
          $ref: '#/components/schemas/CountryCode'
        state:
          type: string
          maxLength: 64
          description: >-
            Document issuing state. Max 64 characters. Required when the type is
            DRIVERS_LICENSE and country is USA.
          example: US-CA
        issue_date:
          type: string
          format: date
          description: >-
            Optional issue date in YYYY-MM-DD format. When provided together
            with expiry_date, expiry_date must be strictly later.
          example: '2020-01-15'
        expiry_date:
          type: string
          format: date
          description: >-
            Expiry date in YYYY-MM-DD format. Required for all types except
            SELFIE. Must be in the future.
          example: '2030-01-15'
        files:
          type: array
          minItems: 1
          description: >-
            File URIs from the [Upload
            Document](https://docs.engagexpay.com/api-reference/customers/upload-document)
            endpoint. PASSPORT and SELFIE take a single file; NATIONAL_ID,
            DRIVERS_LICENSE, and RESIDENCE_PERMIT require one FRONT and one BACK
            file. File URIs must be unique across the entire request (SELFIE
            files excluded).
          items:
            type: object
            required:
              - uri
            properties:
              side:
                type: string
                enum:
                  - FRONT
                  - BACK
                description: >-
                  Required for NATIONAL_ID, DRIVERS_LICENSE, and
                  RESIDENCE_PERMIT. Optional for PASSPORT and SELFIE.
                example: FRONT
              uri:
                type: string
                description: File URI returned by the upload endpoint.
                example: /AbAcQ4hn_0652746727637.pdf
    V2IndividualAddressDocument:
      type: object
      required:
        - type
        - country
        - files
      properties:
        type:
          type: string
          enum:
            - UTILITY_BILL
            - GOVERNMENT_LETTER
            - BANK_STATEMENT
          description: Type of address proof document.
          example: BANK_STATEMENT
        country:
          allOf:
            - $ref: '#/components/schemas/CountryCode'
          description: >-
            Country the address document was issued in. Must match the
            customer's country_of_residence.
        issue_date:
          type: string
          format: date
          description: Optional issue date in YYYY-MM-DD format.
          example: '2024-06-15'
        files:
          type: array
          minItems: 1
          maxItems: 1
          description: >-
            Exactly one file URI from the [Upload
            Document](https://docs.engagexpay.com/api-reference/customers/upload-document)
            endpoint.
          items:
            type: object
            required:
              - uri
            properties:
              side:
                type: string
                enum:
                  - FRONT
                  - BACK
                description: Optional.
                example: FRONT
              uri:
                type: string
                description: File URI returned by the upload endpoint.
                example: /XyZ123mn_0652746727639.pdf
    CountryCode:
      type: string
      description: ISO 3166-1 alpha-3 country code
      example: USA
      enum:
        - AFG
        - ALB
        - DZA
        - ASM
        - AND
        - AGO
        - AIA
        - ATA
        - ATG
        - ARG
        - ARM
        - ABW
        - AUS
        - AUT
        - AZE
        - BHS
        - BHR
        - BGD
        - BRB
        - BLR
        - BEL
        - BLZ
        - BEN
        - BMU
        - BTN
        - BOL
        - BES
        - BIH
        - BWA
        - BVT
        - BRA
        - IOT
        - BRN
        - BGR
        - BFA
        - BDI
        - CPV
        - KHM
        - CMR
        - CAN
        - CYM
        - CAF
        - TCD
        - CHL
        - CHN
        - CXR
        - CCK
        - COL
        - COM
        - COD
        - COG
        - COK
        - CRI
        - HRV
        - CUB
        - CUW
        - CYP
        - CZE
        - CIV
        - DNK
        - DJI
        - DMA
        - DOM
        - ECU
        - EGY
        - SLV
        - GNQ
        - ERI
        - EST
        - SWZ
        - ETH
        - FLK
        - FRO
        - FJI
        - FIN
        - FRA
        - GUF
        - PYF
        - ATF
        - GAB
        - GMB
        - GEO
        - DEU
        - GHA
        - GIB
        - GRC
        - GRL
        - GRD
        - GLP
        - GUM
        - GTM
        - GGY
        - GIN
        - GNB
        - GUY
        - HTI
        - HMD
        - VAT
        - HND
        - HKG
        - HUN
        - ISL
        - IND
        - IDN
        - IRN
        - IRQ
        - IRL
        - IMN
        - ISR
        - ITA
        - JAM
        - JPN
        - JEY
        - JOR
        - KAZ
        - KEN
        - KIR
        - PRK
        - KOR
        - KWT
        - KGZ
        - LAO
        - LVA
        - LBN
        - LSO
        - LBR
        - LBY
        - LIE
        - LTU
        - LUX
        - MAC
        - MDG
        - MWI
        - MYS
        - MDV
        - MLI
        - MLT
        - MHL
        - MTQ
        - MRT
        - MUS
        - MYT
        - MEX
        - FSM
        - MDA
        - MCO
        - MNG
        - MNE
        - MSR
        - MAR
        - MOZ
        - MMR
        - NAM
        - NRU
        - NPL
        - NLD
        - NCL
        - NZL
        - NIC
        - NER
        - NGA
        - NIU
        - NFK
        - MNP
        - NOR
        - OMN
        - PAK
        - PLW
        - PSE
        - PAN
        - PNG
        - PRY
        - PER
        - PHL
        - PCN
        - POL
        - PRT
        - PRI
        - QAT
        - MKD
        - ROU
        - RUS
        - RWA
        - REU
        - BLM
        - SHN
        - KNA
        - LCA
        - MAF
        - SPM
        - VCT
        - WSM
        - SMR
        - STP
        - SAU
        - SEN
        - SRB
        - SYC
        - SLE
        - SGP
        - SXM
        - SVK
        - SVN
        - SLB
        - SOM
        - ZAF
        - SGS
        - SSD
        - ESP
        - LKA
        - SDN
        - SUR
        - SJM
        - SWE
        - CHE
        - SYR
        - TWN
        - TJK
        - TZA
        - THA
        - TLS
        - TGO
        - TKL
        - TON
        - TTO
        - TUN
        - TUR
        - TKM
        - TCA
        - TUV
        - UGA
        - UKR
        - ARE
        - GBR
        - UMI
        - USA
        - URY
        - UZB
        - VUT
        - VEN
        - VNM
        - VGB
        - VIR
        - WLF
        - ESH
        - YEM
        - ZMB
        - ZWE
        - ALA
  responses:
    AuthenticationError:
      description: Authentication failed due to invalid credentials
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Authentication failed
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Resource not found
    ValidationError:
      description: Failed due to a formatting error.
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
              errors:
                type: array
                items:
                  type: object
                  additionalProperties:
                    type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token authentication. Obtain token from [Issue a
        Token](https://docs.engagexpay.com/api-reference/authentication/issue-a-token)
        endpoint

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.