> ## 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 V2
> 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.
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.
## 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
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 V2
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
supporting_documents: []
- 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
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'
supporting_documents:
type: array
description: >-
Any additional supporting documents for this party. Optional. Pass
empty array if not applicable.
items:
$ref: '#/components/schemas/V2AssociatedPartySupportingDocumentAttachment'
V2IdentifyingDocumentAttachment:
type: object
required:
- type
- number
- country
- issue_date
- expiry_date
- files
properties:
type:
type: string
enum:
- PASSPORT
- NATIONAL_ID
- DRIVERS_LICENSE
- RESIDENCE_PERMIT
- PERMANENT_RESIDENCY_ID
description: >
Type of government-issued identity document. At least one
identifying
document is required. Double-sided documents must include both front
and back images.
**USA residents** — all ID types are supported:
- `PASSPORT` — Passport
- `NATIONAL_ID` — National ID card
- `DRIVERS_LICENSE` — Driver's license
- `PERMANENT_RESIDENCY_ID` — Permanent Residency / Green Card
**Non-USA residents** — only the following are accepted:
- `PASSPORT` — Passport
- `NATIONAL_ID` — National ID card
- `DRIVERS_LICENSE` — Driver's license
`PERMANENT_RESIDENCY_ID` is **not supported** for non-USA residents
and will be rejected.
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
- PROOF_OF_TAX_IDENTIFICATION
- COURT_DOCUMENT
- INSURANCE_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
V2AssociatedPartySupportingDocumentAttachment:
type: object
required:
- type
- files
properties:
type:
type: string
enum:
- MILITARY_ID
- MATRICULATE_ID
- STATE_OR_PROVINCIAL_ID
- VISA
- OTHER
description: Type of additional supporting document for the associated party.
example: MILITARY_ID
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
````