> ## 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 Associated Party

> Attach identifying documents and address documents for one or more associated parties of a business customer. Replaces the v1 proof_of_identity / proof_of_address structure with separate identifying_documents and address_documents arrays, allowing multiple ID documents per party.

<Note>
  * Upload files first using [Upload document](https://developer.fin.com/api-reference/customers/upload-document) to obtain URIs, then reference them here.
  * The `associated_party_id` for each party is returned in the [Get Customer Details V2](https://developer.fin.com/api-reference/customers/get-customer-details-v2) response.
</Note>

## Identity Document Side Requirements

| Type               | Sides Required        |
| ------------------ | --------------------- |
| `PASSPORT`         | No (single image)     |
| `NATIONAL_ID`      | Yes: `FRONT` + `BACK` |
| `DRIVERS_LICENSE`  | Yes: `FRONT` + `BACK` |
| `RESIDENCE_PERMIT` | No (single image)     |


## OpenAPI

````yaml POST /v2/customers/{customer_id}/associated-parties/individual/attach
openapi: 3.1.0
info:
  title: Fin.com API
  version: 1.0.0
  description: >-
    A simple API specification for Fin.com, a financial services platform that
    provides a range of banking and payment solutions for businesses and
    individuals. This API allows developers to integrate Fin.com's services into
    their applications, enabling functionalities such as customer management,
    transaction processing, and access to financial data.
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}/associated-parties/individual/attach:
    post:
      tags:
        - Customers
      summary: Attach Documents to Associated Party
      description: >-
        Attach identifying documents and address documents for one or more
        associated parties of a business customer. Replaces the v1
        proof_of_identity / proof_of_address structure with separate
        identifying_documents and address_documents arrays, allowing multiple ID
        documents per party.
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier for the business customer
          example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachDocumentsToAssociatedPartyV2Input'
            example:
              associated_party_attachments:
                - associated_party_id: f6b13e01-044a-4f74-a70b-d5f66b6449af
                  identifying_documents:
                    - type: PASSPORT
                      number: A12345678
                      country: USA
                      issue_date: '2020-01-15'
                      expiry_date: '2030-01-15'
                      files:
                        - uri: /AbAcQ4hn_0652746727637.pdf
                    - type: DRIVERS_LICENSE
                      number: DL987654321
                      country: USA
                      issue_date: '2019-06-01'
                      expiry_date: '2029-06-01'
                      files:
                        - side: FRONT
                          uri: /AbAcQ4hn_0652746727645.pdf
                        - side: BACK
                          uri: /AbAcQ4hn_0652746727646.pdf
                  address_documents:
                    - type: BANK_STATEMENT
                      files:
                        - uri: /AbAcQ4hn_0652746727638.pdf
                - associated_party_id: f71dc19f-b9a0-49fb-bd2d-5add3c01626e
                  identifying_documents:
                    - type: NATIONAL_ID
                      number: NID-987654
                      country: USA
                      issue_date: '2021-03-10'
                      expiry_date: '2031-03-10'
                      files:
                        - side: FRONT
                          uri: /XyZ123mn_0652746727650.pdf
                        - side: BACK
                          uri: /XyZ123mn_0652746727651.pdf
                  address_documents:
                    - type: UTILITY_BILL
                      files:
                        - uri: /XyZ123mn_0652746727652.pdf
      responses:
        '200':
          description: Documents attached successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Generic response object
        '400':
          description: Validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: Validation failed
                  data:
                    type: object
                    additionalProperties:
                      type: string
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
        - bearerAuth: []
components:
  schemas:
    AttachDocumentsToAssociatedPartyV2Input:
      type: object
      required:
        - associated_party_attachments
      properties:
        associated_party_attachments:
          type: array
          description: >-
            Array of document attachments, one entry per associated party.
            Multiple parties can be submitted in a single request.
          minItems: 1
          items:
            $ref: '#/components/schemas/V2AssociatedPartyAttachment'
    V2AssociatedPartyAttachment:
      type: object
      required:
        - associated_party_id
        - identifying_documents
        - address_documents
      properties:
        associated_party_id:
          type: string
          format: uuid
          description: >-
            Unique identifier for the associated party, returned in GET
            /v2/customers/:customer-id.
          example: f6b13e01-044a-4f74-a70b-d5f66b6449af
        identifying_documents:
          type: array
          description: >-
            Government-issued identity documents for this party. Multiple
            documents may be provided (e.g., passport + driver license).
            NATIONAL_ID and DRIVERS_LICENSE require both FRONT and BACK sides.
          items:
            $ref: '#/components/schemas/V2IdentifyingDocumentAttachment'
        address_documents:
          type: array
          description: Proof of address documents. Must be issued within the last 90 days.
          items:
            $ref: '#/components/schemas/V2AddressDocumentAttachment'
    V2IdentifyingDocumentAttachment:
      type: object
      required:
        - type
        - number
        - country
        - issue_date
        - expiry_date
        - files
      properties:
        type:
          type: string
          enum:
            - PASSPORT
            - NATIONAL_ID
            - DRIVERS_LICENSE
            - RESIDENCE_PERMIT
          description: >
            Type of government-issued identity document. At least one
            identifying

            document is required. Double-sided documents must include both front

            and back images.


            Supported types:

            - `PASSPORT`: Passport

            - `NATIONAL_ID`: National ID card

            - `DRIVERS_LICENSE`: Driver's license

            - `RESIDENCE_PERMIT`: Residence permit
          example: PASSPORT
        number:
          type: string
          description: Document number.
          example: A12345678
        country:
          $ref: '#/components/schemas/CountryCode'
        issue_date:
          type: string
          format: date
          description: Document issue date in YYYY-MM-DD format.
          example: '2020-01-15'
        expiry_date:
          type: string
          format: date
          description: Document expiry date in YYYY-MM-DD format. Must not be expired.
          example: '2030-01-15'
        files:
          type: array
          description: >-
            One or more file URIs from [Upload
            Document](https://developer.fin.com/api-reference/customers/upload-document)
            endpoint. For NATIONAL_ID and DRIVERS_LICENSE, provide both FRONT
            and BACK.
          minItems: 1
          items:
            type: object
            required:
              - uri
            properties:
              side:
                type: string
                enum:
                  - FRONT
                  - BACK
                description: >-
                  Required for NATIONAL_ID and DRIVERS_LICENSE. Optional for
                  PASSPORT and RESIDENCE_PERMIT.
                example: FRONT
              uri:
                type: string
                description: File URI returned by the upload endpoint.
                example: /AbAcQ4hn_0652746727637.pdf
    V2AddressDocumentAttachment:
      type: object
      required:
        - type
        - files
      properties:
        type:
          type: string
          enum:
            - UTILITY_BILL
            - GOVERNMENT_LETTER
            - BANK_STATEMENT
          description: Type of address proof document. Must be within the last 90 days.
          example: BANK_STATEMENT
        files:
          type: array
          description: >-
            One or more file URIs from [Upload
            Document](https://developer.fin.com/api-reference/customers/upload-document)
            endpoint.
          minItems: 1
          items:
            type: object
            required:
              - uri
            properties:
              uri:
                type: string
                description: File URI returned by the upload endpoint.
                example: /AbAcQ4hn_0652746727638.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

````