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

# Attach Documents to Individual Customer V2

> Attach identifying and address documents to an existing v2 individual customer. Replaces the v1 proof_of_identity / proof_of_address structure with separate identifying_documents and address_documents arrays. Documents are processed asynchronously.

<Note>
  * Upload files first using the [Upload document](https://developer.fin.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 V2 endpoint.
</Note>

## 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: Fin.com API
  version: 1.0.0
  description: A simple API specification
servers:
  - url: https://sandbox.api.fin.com
    description: Sandbox server
  - url: https://api.fin.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 fin.com'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 V2
      description: >-
        Attach identifying and address documents to an existing v2 individual
        customer. Replaces the v1 proof_of_identity / proof_of_address structure
        with 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://developer.fin.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://developer.fin.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://developer.fin.com/api-reference/authentication/issue-a-token)
        endpoint

````