openapi: 3.1.0 info: title: Fin.com Authentication Customers API version: 1.0.0 description: A simple API specificationFo servers: - url: https://sandbox.api.fin.com description: Sandbox server - url: https://api.fin.com description: Production server tags: - name: Customers description: Customer management and document upload operations paths: /v2/customers: get: summary: List Customers V2 description: Retrieve a list of customers filtered by type tags: - Customers security: - bearerAuth: [] parameters: - name: type in: query description: Filter customers by type required: true schema: type: string enum: - INDIVIDUAL - BUSINESS - $ref: '#/components/parameters/PerPageParam' - $ref: '#/components/parameters/CurrentPageParam' responses: '200': description: List of customers retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: type: object properties: current_page: type: integer example: 1 per_page: type: integer example: 40 total_page: type: integer example: 1 total: type: integer example: 4 customers: type: array items: oneOf: - type: object title: Individual Customer properties: customer_id: type: string format: uuid example: 56c41b8e-e650-4f55-94f6-26a888a9b64d type: type: string enum: - INDIVIDUAL first_name: type: string example: John last_name: type: string example: Doe email: type: string format: email example: john.doe@example.com phone: type: string example: '+14155551234' country_of_residence: type: string example: USA customer_status: type: string example: INCOMPLETE tos_policies_url: type: string format: uri example: https://orchestration.fin.com/orchestration-customer-tos?customer_id=56c41b8e-e650-4f55-94f6-26a888a9b64d&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b created_at: type: string format: date-time example: '2026-04-01T12:03:03Z' updated_at: type: string format: date-time example: '2026-04-01T12:03:03Z' - type: object title: Business Customer properties: customer_id: type: string format: uuid example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06 type: type: string enum: - BUSINESS business_name: type: string example: Fin.com email: type: string format: email example: m@tech.com phone: type: string example: '+8801529876543' country_of_incorporation: type: string example: BGD customer_status: type: string example: IN_COMPLIANCE tos_policies_url: type: string format: uri example: https://orchestration.fin.com/orchestration-customer-tos?customer_id=ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24 created_at: type: string format: date-time example: '2026-04-13T11:38:57Z' updated_at: type: string format: date-time example: '2026-04-13T11:40:51Z' examples: OK: summary: OK value: data: pagination: current_page: 1 per_page: 40 total_page: 1 total: 2 customers: - customer_id: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06 type: BUSINESS business_name: Fin.com email: m@tech.com phone: '+8801529876543' country_of_incorporation: BGD customer_status: IN_COMPLIANCE tos_policies_url: https://orchestration.fin.com/orchestration-customer-tos?customer_id=ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24 created_at: '2026-04-13T11:38:57Z' updated_at: '2026-04-13T11:40:51Z' - customer_id: 56c41b8e-e650-4f55-94f6-26a888a9b64d type: INDIVIDUAL first_name: John last_name: Doe email: john.doe@example.com phone: '+14155551234' country_of_residence: USA customer_status: INCOMPLETE tos_policies_url: https://orchestration.fin.com/orchestration-customer-tos?customer_id=56c41b8e-e650-4f55-94f6-26a888a9b64d&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b created_at: '2026-04-01T12:03:03Z' updated_at: '2026-04-01T12:03:03Z' '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v1/customers: get: summary: List Customers description: Retrieve a list of customers filtered by type x-mint: content: "\n This endpoint was deprecated on May 20, 2026. Use [List Customers V2](https://developer.fin.com/api-reference/customers/list-customers-v2) instead.\n\n" tags: - Customers security: - bearerAuth: [] parameters: - name: type in: query description: Filter customers by type required: true schema: type: string enum: - INDIVIDUAL - BUSINESS - $ref: '#/components/parameters/PerPageParam' - $ref: '#/components/parameters/CurrentPageParam' responses: '200': description: List of customers retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: pagination: type: object properties: current_page: type: integer example: 1 per_page: type: integer example: 10 total_page: type: integer example: 1 total: type: integer example: 2 customers: type: array items: oneOf: - type: object properties: customer_id: type: string format: uuid example: 56c41b8e-e650-4f55-94f6-26a888a9b64d type: type: string enum: - INDIVIDUAL first_name: type: string example: John last_name: type: string example: Doe email: type: string format: email example: john.doe@example.com phone: type: string example: '+14724480512' country_of_residence: type: string example: USA customer_status: type: string example: INCOMPLETE tos_policies_url: type: string format: uri created_at: type: string format: date-time updated_at: type: string format: date-time - type: object properties: customer_id: type: string format: uuid example: 94e6b847-4e19-49e3-b3ab-ffa95872eda9 type: type: string enum: - BUSINESS business_name: type: string example: Acme Corp Ltd email: type: string format: email example: contact@acmecorp.com phone: type: string example: '+14155552671' country_of_incorporation: type: string example: USA customer_status: type: string example: INCOMPLETE tos_policies_url: type: string format: uri created_at: type: string format: date-time updated_at: type: string format: date-time '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v2/customers/{customer_id}: get: summary: Get Customer Details V2 description: Retrieve detailed information for a specific customer x-mint: content: "\n Use this endpoint to fetch business customer details. For individual customer details, use [Get Customer Details](https://developer.fin.com/api-reference/customers/get-customer-details).\n\n" tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06 responses: '200': description: Customer details retrieved successfully content: application/json: schema: type: object properties: data: oneOf: - $ref: '#/components/schemas/IndividualCustomerDetailV2' - $ref: '#/components/schemas/BusinessCustomerDetailV2' examples: Business: summary: Business customer value: data: customer_id: 671536f8-ddc5-4b1e-bd6f-27d0ed07a27c type: BUSINESS business_name: Fin.com email: contact@fin.com phone: '+14155552671' country_of_incorporation: USA verification_type: STANDARD customer_status: ACTION_REQUIRED tos_policies_url: https://orchestration.fin.com/orchestration-customer-tos?customer_id=671536f8-ddc5-4b1e-bd6f-27d0ed07a27c&tos_policies_value=4e0e505a-36f0-4c9e-8eb1-3916410f227c associated_parties: - id: 2e719a54-cdef-43f9-a5ac-f6ef679ea1dc type: INDIVIDUAL ownership_percent: 60 email: jane.smith@acmecorp.com verification: status: REJECTED reason: for_customer: null for_developer: null updated_at: '2026-05-04T12:36:42Z' - id: 4ef045ea-c7a7-46dc-84a0-9a3d83186971 type: INDIVIDUAL ownership_percent: 40 email: robert.chen@acmecorp.com verification: status: APPROVED reason: for_customer: null for_developer: null updated_at: '2026-05-04T12:29:47Z' created_at: '2026-05-04T12:11:27Z' updated_at: '2026-05-04T12:34:03Z' last_status_updated_at: '2026-05-04T12:32:34.47927Z' rejection_reason: applicant: moderation_comment: '' reject_labels: - LOW_QUALITY - UNFILLED_ID - DOCUMENT_TEMPLATE - NOT_DOCUMENT documents: - uri: /ZuyUaH3a_testdoc1.png category: SUPPORTING_DOCUMENTS moderation_comment: "This document is not accepted.\n - The document should be of good quality." reject_labels: - LOW_QUALITY - uri: /ZuyUaH3a_testdoc1.png category: OWNERSHIP_DOCUMENTS moderation_comment: "This document is not accepted.\n - The document is not authentic" reject_labels: - UNFILLED_ID - uri: /ZuyUaH3a_testdoc1.png category: OWNERSHIP_DOCUMENTS moderation_comment: "This document is not accepted.\n - The uploaded file appears to be a document template." reject_labels: - DOCUMENT_TEMPLATE - uri: /ZuyUaH3a_testdoc1.png category: SUPPORTING_DOCUMENTS moderation_comment: "This document is not accepted.\n - The file is not a document" reject_labels: - NOT_DOCUMENT associated_parties: - id: 2e719a54-cdef-43f9-a5ac-f6ef679ea1dc applicant: moderation_comment: '' reject_labels: - EXPIRATION_DATE documents: - uri: /OUkUie0z_approved_passport_sumsub.jpg category: PROOF_OF_IDENTITY moderation_comment: Your identity document must be valid for at least 2 month(s) from the date of submission. reject_labels: - EXPIRATION_DATE request_for_information: - scope: ASSOCIATED_PARTY associated_party_id: 2e719a54-cdef-43f9-a5ac-f6ef679ea1dc section: identifying_documents categories: - document_type: PASSPORT fields: - field_name: type data_type: ENUM status: INVALID options: [] - field_name: expiry_date data_type: DATE status: INVALID options: [] - field_name: issue_date data_type: DATE status: INVALID options: [] - field_name: files data_type: URI status: INVALID reason: User identity document is not valid for at least 2 month(s) from the date of submission. options: [] - scope: CUSTOMER section: formation_documents categories: - document_type: EVIDENCE_OF_DIRECTORS_AND_CONTROLLERS fields: - field_name: type data_type: ENUM status: INVALID options: [] - field_name: files data_type: URI status: INVALID reason: Unacceptable document. options: [] - scope: CUSTOMER section: supporting_documents categories: - document_type: PROOF_OF_SOURCE_OF_FUNDS fields: - field_name: type data_type: ENUM status: INVALID options: [] - field_name: files data_type: URI status: INVALID reason: Unacceptable document. options: [] - scope: CUSTOMER section: ownership_documents categories: - document_type: PROOF_OF_SIGNATORY_AUTHORITY fields: - field_name: type data_type: ENUM status: INVALID options: [] - field_name: files data_type: URI status: INVALID reason: Document appears to be corrupted options: [] Individual: summary: Individual customer value: data: customer_id: 1f45e58d-0420-4ad8-a790-413169bfab28 type: INDIVIDUAL first_name: John last_name: Doe email: atkeyafahmida290@gmail.com phone: '+8801748386269' country_of_residence: BGD verification_type: STANDARD customer_status: ACTION_REQUIRED tos_policies_url: https://orchestration.fin.com/orchestration-customer-tos?customer_id=1f45e58d-0420-4ad8-a790-413169bfab28&tos_policies_value=ffefb0cd-4f0a-4585-ad1c-f4ea76ba41b8 created_at: '2026-05-04T12:40:03Z' updated_at: '2026-05-04T12:47:50Z' last_status_updated_at: '2026-05-04T12:44:42.707598Z' rejection_reason: applicant: moderation_comment: '' reject_labels: - EXPIRATION_DATE - PROBLEMATIC_APPLICANT_DATA documents: - uri: /SuElNZpi_approved_passport_sumsub.jpg category: PROOF_OF_IDENTITY moderation_comment: Your identity document has expired and can't be used for verification. Please upload a different identity document. reject_labels: - EXPIRATION_DATE request_for_information: - scope: CUSTOMER section: proof_of_identity categories: - document_type: PASSPORT fields: - field_name: type data_type: ENUM status: INVALID options: [] - field_name: expiry_date data_type: DATE status: INVALID options: [] - field_name: issue_date data_type: DATE status: INVALID options: [] - field_name: files data_type: URI status: INVALID reason: Expired Identity document. A new document has been requested. options: [] '401': $ref: '#/components/responses/AuthenticationError' '404': $ref: '#/components/responses/NotFoundError' '422': $ref: '#/components/responses/ValidationError' /v1/customers/{customer_id}: get: summary: Get Customer Details description: Retrieve detailed information for a specific customer x-mint: content: "\n Use this endpoint to fetch individual customer details. For business customer details, use [Get Customer Details V2](https://developer.fin.com/api-reference/customers/get-customer-details-v2).\n\n" tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid example: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9 responses: '200': description: Customer details retrieved successfully content: application/json: schema: type: object properties: data: oneOf: - $ref: '#/components/schemas/IndividualCustomerDetail' - $ref: '#/components/schemas/BusinessCustomerDetail' examples: Individual Customer: summary: Individual Customer value: data: customer_id: 56c41b8e-e650-4f55-94f6-26a888a9b64d type: INDIVIDUAL first_name: John last_name: Doe email: john.doe@fin.com phone: '+14724480512' country_of_residence: USA verification_type: STANDARD customer_status: ON_HOLD tos_policies_url: https://orchestration.fin.com/orchestration-customer-tos?customer_id=56c41b8e-e650-4f55-94f6-26a888a9b64d&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b created_at: '2026-04-15T11:49:27Z' updated_at: '2026-04-15T11:52:48Z' last_status_updated_at: '2026-04-15T11:52:48Z' capabilities: on_ramp: - currency: USD status: false methods: - ACH - FEDWIRE reason: for_customer: null for_developer: null off_ramp: - currency: USD status: false methods: - ACH - FEDWIRE - ACH_SAME_DAY reason: for_customer: null for_developer: Customer is under review - currency: EUR status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: BDT status: false methods: - BANK - E_WALLET reason: for_customer: null for_developer: Customer is under review - currency: AUD status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: INR status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: JPY status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: NPR status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: CAD status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: PKR status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: PHP status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: SGD status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review - currency: GBP status: false methods: - BANK reason: for_customer: null for_developer: Customer is under review rejection_reason: null request_for_information: [] Business Customer: summary: Business Customer value: data: customer_id: 94e6b847-4e19-49e3-b3ab-ffa95872eda9 type: BUSINESS business_name: Fin.com email: contact@fin.com phone: '+6591234567' country_of_incorporation: SGP verification_type: STANDARD customer_status: APPROVED tos_policies_url: https://orchestration.fin.com/orchestration-customer-tos?customer_id=94e6b847-4e19-49e3-b3ab-ffa95872eda9&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24 associated_parties: - id: 42daffd3-09a0-4d48-8e73-2680a953d0e1 type: INDIVIDUAL ownership_percent: 10 email: john.doe@fin.com verification: status: APPROVED reason: for_customer: null for_developer: null updated_at: '2026-04-15T11:29:08Z' created_at: '2026-04-15T11:26:12Z' updated_at: '2026-04-15T11:31:18Z' last_status_updated_at: '2026-04-15T11:29:09Z' capabilities: on_ramp: - currency: USD status: false methods: - ACH - FEDWIRE reason: for_customer: null for_developer: null off_ramp: - currency: USD status: false methods: - ACH - FEDWIRE - ACH_SAME_DAY reason: for_customer: null for_developer: Unsupported at the moment - currency: EUR status: true methods: - BANK reason: for_customer: null for_developer: null - currency: BDT status: true methods: - BANK - E_WALLET reason: for_customer: null for_developer: null - currency: AUD status: true methods: - BANK reason: for_customer: null for_developer: null - currency: INR status: true methods: - BANK reason: for_customer: null for_developer: null - currency: JPY status: true methods: - BANK reason: for_customer: null for_developer: null - currency: NPR status: true methods: - BANK reason: for_customer: null for_developer: null - currency: CAD status: true methods: - BANK reason: for_customer: null for_developer: null - currency: PKR status: true methods: - BANK reason: for_customer: null for_developer: null - currency: PHP status: true methods: - BANK reason: for_customer: null for_developer: null - currency: SGD status: true methods: - BANK reason: for_customer: null for_developer: null - currency: GBP status: true methods: - BANK reason: for_customer: null for_developer: null rejection_reason: null request_for_information: [] '401': $ref: '#/components/responses/AuthenticationError' '404': description: Customer not found content: application/json: schema: type: object properties: message: type: string example: Customer not found '422': $ref: '#/components/responses/ValidationError' patch: summary: Update Customer description: Submit an RFI response for an individual or business customer. You must pass only the fields and documents specified in the RFI. Submitting data that was not requested will trigger an error. x-mint: content: "\n Only submit the fields explicitly listed in the RFI. Sending unrequested\n fields will result in an error.\n\n\nThe request body accepts the same fields as the following endpoints:\n\n- Attach Documents to Individual Customer\n- Attach Documents to Business Customer\n- Attach Documents to Business Customer V2\n- Attach Document To Associated Party\n- Attach Document To Associated Party V2\n" tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid description: Unique identifier of the customer to update example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06 requestBody: required: true content: application/json: schema: oneOf: - title: Individual Customer type: object properties: proof_of_identity: type: object properties: type: type: string example: PASSPORT number: type: string example: A12345678 country: type: string example: USA issue_date: type: string format: date example: '2020-01-15' expiry_date: type: string format: date example: '2030-01-15' files: type: array items: type: object properties: uri: type: string example: /AbAcQ4hn_0652746727637.pdf side: type: string enum: - FRONT - BACK example: FRONT proof_of_address: type: object description: The proof of address document must not be older than three months. properties: type: type: string example: UTILITY_BILL country: type: string example: USA files: type: array items: type: object properties: uri: type: string example: /AbAcQ4hn_0652746727638.pdf - title: Business Customer type: object properties: ownership_documents: type: array description: Ownership documents for the business customer (e.g. shareholder registry, proof of signatory authority) items: type: object properties: type: type: string example: PROOF_OF_SIGNATORY_AUTHORITY description: type: string example: Shareholder Registry files: type: array items: type: object properties: uri: type: string example: /AbAcQ4hn_0652746727639.pdf formation_documents: type: array description: Formation documents for the business customer (e.g. certificate of incorporation, registration document) items: type: object properties: type: type: string example: REGISTRATION_DOCUMENT description: type: string example: Certificate of Incorporation files: type: array items: type: object properties: uri: type: string example: /AbAcQ4hn_0652746727637.pdf supporting_documents: type: array description: Supporting documents for the customer items: type: object properties: type: type: string example: PROOF_OF_SOURCE_OF_FUNDS description: type: string example: Proof of source of funds doc files: type: array items: type: object properties: uri: type: string example: /PoAdef45_0652746727640.pdf associated_party_attachments: type: array description: Document attachments for associated parties of a business customer items: type: object properties: associated_party_id: type: string format: uuid description: ID of the associated party example: f6b13e01-044a-4f74-a70b-d5f66b6449af identifying_documents: type: array items: type: object properties: type: type: string enum: - PASSPORT - NATIONAL_ID - DRIVERS_LICENSE - RESIDENCE_PERMIT number: type: string country: type: string issue_date: type: string format: date expiry_date: type: string format: date files: type: array items: type: object properties: side: type: string enum: - FRONT - BACK uri: type: string address_documents: type: array items: type: object properties: type: type: string files: type: array items: type: object properties: uri: type: string supporting_documents: type: array items: type: object examples: Business Customer: value: ownership_documents: - type: PROOF_OF_SIGNATORY_AUTHORITY description: Shareholder Registry files: - uri: /AbAcQ4hn_0652746727639.pdf formation_documents: - type: REGISTRATION_DOCUMENT description: Certificate of Incorporation files: - uri: /AbAcQ4hn_0652746727637.pdf supporting_documents: - type: PROOF_OF_SOURCE_OF_FUNDS description: Proof of source of funds doc files: - uri: /PoAdef45_0652746727640.pdf 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 Individual Customer: value: proof_of_identity: type: PASSPORT number: A12345678 country: USA issue_date: '2020-01-15' expiry_date: '2030-01-15' files: - uri: /AbAcQ4hn_0652746727637.pdf side: FRONT proof_of_address: type: UTILITY_BILL country: USA files: - uri: /AbAcQ4hn_0652746727638.pdf responses: '200': description: Customer updated successfully content: application/json: schema: type: object properties: data: type: object properties: customer_id: type: string format: uuid example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06 example: data: customer_id: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06 '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' /v2/customers/{customer_id}/wallets: post: summary: Create Customer Wallets description: Provisions one or more crypto wallets for a customer across supported chains and tokens. x-mint: content: "\n Fin.com issued crypto wallets require pre-configuration. Contact support to learn more.\n\n\nWallets start with a status of `PENDING`. They move to `ACTIVE` (or\n`INACTIVE`) asynchronously once the wallet address has been issued,\nso creation is not synchronous. Poll [Get Customer\nWallets](/api-reference/crypto-orchestration/get-customer-wallets)\nto check on status.\n\nSupported rails and currencies:\n\n| Rail | Currency |\n| -------- | -------- |\n| POLYGON | USDC |\n| ETHEREUM | USDC |\n| SOLANA | USDC |\n\nIf any requested wallet (same `rail` + `currency` pair) already\nexists for the customer, the request fails with a `409` and lists\nthe colliding pairs; none of the requested wallets are created.\n" tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string example: 765d498e-a267-4154-9d2f-9e411a0b50dd requestBody: required: true content: application/json: schema: type: object required: - wallets properties: wallets: type: array minItems: 1 description: Wallets to provision, one entry per rail. items: type: object required: - rail - currency properties: rail: type: string description: Blockchain network to provision the wallet(s) on. example: SOLANA currency: type: array minItems: 1 description: Token(s) to provision a wallet for on this rail. items: type: string example: - USDC example: wallets: - rail: SOLANA currency: - USDC - rail: ETHEREUM currency: - USDC responses: '200': description: 'Wallet creation request accepted for processing. Note the nested `data`: the outer envelope wraps a `message` plus the inner `data` array of wallets being provisioned.' content: application/json: schema: type: object properties: data: type: object properties: message: type: string example: Request is being processed data: type: array items: $ref: '#/components/schemas/CustomerWallet' example: data: message: Request is being processed data: - id: b1e2c3d4-4d5e-6f70-8a90-1b2c3d4e5f60 rail: SOLANA currency: USDC status: PENDING - id: d3a4e5f6-4d5e-6f70-8a90-1b2c3d4e5f62 rail: ETHEREUM currency: USDC status: PENDING '401': $ref: '#/components/responses/AuthenticationError' '409': description: One or more of the requested wallets already exist for this customer. content: application/json: schema: type: object properties: message: type: string example: one or more wallets already exist for this customer collisions: type: array items: type: object properties: rail: type: string example: SOLANA currency: type: string example: USDC example: message: one or more wallets already exist for this customer collisions: - rail: SOLANA currency: USDC '422': $ref: '#/components/responses/ValidationError' get: summary: Get Customer Wallets description: Returns all crypto wallets linked to a customer across supported chains and tokens. x-mint: content: "\n Fin.com issued crypto wallets require pre-configuration. Contact support to learn more.\n\n\nUpon approval, the customer is provisioned wallet addresses for the following rails and currencies:\n\n| Rail | Currency |\n| -------- | -------- |\n| POLYGON | USDC |\n| ETHEREUM | USDC |\n| SOLANA | USDC |\n\n`address` is `null` until the wallet finishes provisioning (see\n`status` on [Create Customer Wallets](/api-reference/crypto-orchestration/create-customer-wallets)).\n" tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string example: 765d498e-a267-4154-9d2f-9e411a0b50dd responses: '200': description: Customer wallets retrieved successfully content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/CustomerWallet' example: data: - id: 27dbc0f2-e5ae-444b-b4ab-0764252aedf6 status: ACTIVE currency: USDC rail: ETHEREUM address: '0xc42a5f7083c7e8f1d9820c7660867277289cd998' balance: 10.000001 - id: e1dcce59-0309-43de-ab6c-a0bd3497b9c3 status: ACTIVE currency: USDC rail: SOLANA address: BCSZEokfpVsSpUuuZJMScLiUpYjvvUmrrAJkNbrTTnng balance: 25.000001 - id: c92dfe1d-220e-4446-a5e4-cd7d46031ba5 status: PENDING currency: USDC rail: POLYGON address: null balance: 0 '401': $ref: '#/components/responses/AuthenticationError' '404': $ref: '#/components/responses/NotFoundError' /v2/customers/{customer_id}/capabilities: get: summary: Get Customer Capabilities description: Returns the on-ramp and off-ramp capabilities available for a customer, including the supported rails and their activation status for each currency and corridor. tags: - Customers security: - bearerAuth: [] parameters: - name: customer_id in: path required: true schema: type: string format: uuid example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06 responses: '200': description: Customer capabilities retrieved successfully content: application/json: schema: type: object properties: data: type: object properties: on_ramp: type: array items: type: object properties: currency: type: string example: USD rail: type: string example: ACH status: type: boolean example: true off_ramp: type: array items: type: object properties: corridor: type: string example: BGD currency_wise_rail: type: array items: type: object properties: currency: type: string example: BDT rails: type: array items: type: object properties: rail: type: string example: LOCAL status: type: boolean example: true examples: OK: summary: OK value: data: on_ramp: - currency: USD rail: ACH status: false - currency: USD rail: FEDWIRE status: true - currency: USD rail: SWIFT status: true off_ramp: - corridor: BGD currency_wise_rail: - currency: BDT rails: - rail: LOCAL status: true - currency: USD rails: - rail: SWIFT status: true - corridor: AUS currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - corridor: GBR currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - currency: GBP rails: - rail: LOCAL status: true - corridor: CAN currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - corridor: DEU currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - currency: EUR rails: - rail: LOCAL status: true - corridor: POL currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - corridor: IND currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - currency: INR rails: - rail: LOCAL status: true - corridor: PAK currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - corridor: NPL currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - corridor: PHL currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - corridor: SGP currency_wise_rail: - currency: USD rails: - rail: SWIFT status: true - currency: SGD rails: - rail: LOCAL status: true '401': $ref: '#/components/responses/AuthenticationError' '404': $ref: '#/components/responses/NotFoundError' '422': $ref: '#/components/responses/ValidationError' /v2/customers/individual: post: summary: Create Individual Customer V2 description: Create a new individual customer with verification details, basic info, address, and financial profile. tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateIndividualCustomerV2Input' example: verification_type: STANDARD basic_info: first_name: Maria middle_name: Elena last_name: Garcia dob: '1990-04-15' email: maria.garcia@example.com phone: '+14155552671' country_of_residence: USA primary_nationality: USA secondary_nationality: MEX gender: FEMALE tax_info: - country_code: USA document_type: SSN document_id: 123-45-6789 address: street_line_1: 123 Market Street street_line_2: Apt 4B city: San Francisco subdivision_code: US-CA postal_code: '94103' country: USA financial_profile: employment_status: EMPLOYED occupation_id: 42 purpose_id: 3 purpose_remarks: Personal remittances to family source_of_funds_description: Monthly salary from employment source_of_fund_ids: - 1 - 5 monthly_volume_usd: 5000 meta_data: reference: client-ref-abc-001 responses: '200': description: Individual customer created successfully content: application/json: schema: type: object properties: data: type: object properties: customer_id: type: string format: uuid example: 0ca13984-63f3-45d7-99a7-52b9133f0259 tos_policies_url: type: string format: uri description: URL for the customer to accept Terms of Service. Parse the tos_policies_value query parameter for later use. example: https://orchestration.fin.com/orchestration-customer-tos?customer_id=0ca13984-63f3-45d7-99a7-52b9133f0259&tos_policies_value=7e8873f7-519b-43d7-9565-c81befc52dd6 '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' '423': description: Locked. RELIANCE verification is not available for your client. content: application/json: schema: type: object properties: message: type: string example: RELIANCE is not available for your client /v1/customers/individual: post: summary: Create Individual Customer description: Create a new individual customer with verification details x-mint: content: "\n Only English (Latin) characters are allowed as inputs for all fields.\n\n\n## Important Requirements\n\n- **Email Address**: Must be all lowercase or you will receive a validation error\n- **RELIANCE Verification**: If you attempt to use `RELIANCE` verification type but it's not enabled for your client, you will receive a 423 error with message: \"RELIANCE is not available for your client\"\n" tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateIndividualCustomerInput' responses: '200': description: Individual customer created successfully content: application/json: schema: type: object properties: data: type: object properties: customer_id: type: string format: uuid example: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9 tos_policies_url: type: string format: uri example: https://orchestration.fin.com/orchestration-customer-tos?customer_id=55bd6b4e-c20a-4cc8-9535-91d5557a67d9&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' '423': description: Locked. RELIANCE verification is not available for your client. content: application/json: schema: type: object properties: message: type: string example: RELIANCE is not available for your client /v2/customers/business: post: summary: Create Business Customer V2 description: Create a new business customer with full KYB profile, associated parties (UBOs/directors), compliance data, and optionally holding structure and public listing details. x-mint: content: '## Important Requirements - **Email Address**: Must be all lowercase or you will receive a validation error - **RELIANCE Verification**: If you attempt to use `RELIANCE` verification type but it''s not enabled for your client, you will receive a 423 error with message: "RELIANCE is not available for your client" - **Non-ASCII characters**: If any input field contains non-ASCII characters, you must provide a transliterated (Latin) value in the corresponding `_en` field (e.g., `legal_name_en`, `street_line_1_en`, `first_name_en`) - **Third-party Fund Usage**: The `third_party_fund_usage` field indicates whether this customer will be moving other people''s money - **Ownership Percentages**: The total ownership percentages of all associated parties must add up to more than 0 and less than 100 - **Reference Data**: `purpose_id`, `source_of_fund_ids` and `source_of_wealth_ids` are integer foreign keys. Fetch valid values from [List Account Purposes](https://developer.fin.com/api-reference/catalogue/list-account-purposes) , [List Source of Funds](https://developer.fin.com/api-reference/catalogue/list-source-of-funds) and [List Source of Wealth](https://developer.fin.com/api-reference/catalogue/list-source-of-wealth) - **subdivision_code**: Pass the ISO 3166-2 code. For example for CA, pass US-CA. ' tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBusinessCustomerV2Input' example: verification_type: STANDARD industry_codes: - '541512' - '522390' basic_info: legal_name: Fin.com legal_name_en: Fin.com trade_name: Toronggo trade_name_en: Toronggo description: Bangladesh-based technology company providing cross-border B2B payment and financial technology services to enterprise clients entity_type: LIMITED_LIABILITY_COMPANY email: m@tech.com phone: '+8801529876543' incorporation_date: '2018-06-15' country_of_incorporation: BGD registration_number: C-123456/2018 is_dao: false tax_info: - country_code: BGD document_type: TIN document_id: '123456789012' websites: - https://fin.com financial_profile: purpose_id: 3 purpose_remarks: Cross-border B2B payments for international suppliers source_of_fund_ids: - 1 - 4 source_of_funds_description: Revenue from software licensing and technology services source_of_wealth_ids: - 2 estimated_annual_revenue_usd: 5000000 expected_monthly_deposits_usd: 400000 expected_monthly_withdrawals_usd: 350000 expected_transaction_value_usd: 50000 expected_monthly_transaction_count: 20 third_party_fund_usage: false addresses: is_incorporated_address_same: false incorporated_address: street_line_1: House 12, Road 4, Dhanmondi city: Dhaka state: BD-13 subdivision_code: BD-13 postal_code: '1205' country: BGD physical_address: street_line_1: Level 5, 45 Gulshan Avenue city: Dhaka state: BD-13 subdivision_code: BD-13 postal_code: '1212' country: BGD associated_parties: - ref: owner-001 basic_info: first_name: Fatima last_name: Rahman dob: '1990-05-15' email: fatima.rahman22@acmecorp.com.bd phone: '+8801711223344' country_of_residence: BGD primary_nationality: BGD tax_info: - country_code: BGD document_type: TIN document_id: '1234567890123' address: street_line_1: House 12, Road 4, Dhanmondi city: Dhaka state: BD-13 subdivision_code: BD-13 postal_code: '1205' country: BGD roles: - shareholder ownership_info: designation: CEO & Founder percentage_of_ownership: 60 relationship_establishment_date: '2018-06-15' has_control: true is_signer: true is_director: true - ref: owner-002 basic_info: first_name: Karim last_name: Islam dob: '1992-08-22' email: karim.islam22@acmecorp.com.bd phone: '+8801822334455' country_of_residence: BGD primary_nationality: BGD tax_info: - country_code: BGD document_type: TIN document_id: '9876543210123' address: street_line_1: Flat 3B, 78 Mirpur Road city: Dhaka state: BD-13 subdivision_code: BD-13 postal_code: '1216' country: BGD roles: - ubo ownership_info: designation: CTO & Co-Founder percentage_of_ownership: 40 relationship_establishment_date: '2018-06-15' has_control: false is_signer: false is_director: false holding_structure: has_material_intermediary_ownership: true corporate_shareholders: - entity_name: Toronggo Ventures Limited entity_name_en: Toronggo Ventures Limited registration_country_code: BGD ownership_percentage: 0 registration_number: C-987654/2015 entity_type: LIMITED_LIABILITY_COMPANY incorporation_date: '2015-03-01' compliance: operates_in_prohibited_countries: false additional_description_for_compliance_screening: We do not operate in any OFAC-sanctioned jurisdictions. risk_profile: high_risk_activities: - adult_entertainment high_risk_activities_explanation: We facilitate cross-border B2B payments, subject to enhanced due diligence. conducts_money_services: true conducts_money_services_via_fin: false conducts_money_services_description: Licensed payment service provider offering international transfer services. regulated_activity: description: Licensed payment service provider under Bangladesh Bank regulation primary_authority_country_code: BGD primary_authority_name: Bangladesh Bank license_number: PSP-2019-00123 aml: supervisory_authority_name: Bangladesh Financial Intelligence Unit license_number: PSP-2019-00123 has_appointed_mlro: true customer_risk_split: low_risk: 70 medium_risk: 25 high_risk: 5 prohibits_anonymous_or_fictitious_accounts: true prohibits_accounts_for_unlicensed_or_shell_customers: true customer_identity_verification: method: automated system: Jumio pep_and_sanctions_screening: method: automated system: Dow Jones Risk & Compliance sanction_lists: - OFAC - EU - UN - HMT customer_risk_classification_from_due_diligence: true enhanced_due_diligence_process: true transaction_monitoring: method: automated system: Actimize procedures_for_transaction_monitoring: true subject_to_ml_or_tf_investigation: none subject_to_regulatory_enforcement_past_2_years: none confirms_no_service_to_sanctioned_countries: true client_funds_accessibility: closed_loop aml_ctf_audit_completed: true planned_audit_date: '2026-12-01' meta_data: reference: REF-20250123-TORONGGO responses: '201': description: Business customer created successfully content: application/json: schema: type: object properties: customer_id: type: string format: uuid description: Unique identifier for the created customer example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06 tos_policies_url: type: string format: uri description: URL for customer to accept Terms of Service. Parse the tos_policies_value query parameter and pass it when attaching business documents. example: https://orchestration.fin.com/orchestration-customer-tos?customer_id=ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24 '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 example: basic_info.email: Must be a valid email address associated_parties[0].basic_info.dob: Party must be at least 18 years old addresses.physical_address: Required when is_incorporated_address_same is false '401': $ref: '#/components/responses/AuthenticationError' '423': description: Locked. RELIANCE verification is not available for your client. content: application/json: schema: type: object properties: status: type: integer example: 423 message: type: string example: RELIANCE is not available for your client '500': description: Internal server error content: application/json: schema: type: object properties: status: type: integer example: 500 message: type: string example: Internal server error /v1/customers/business: post: summary: Create Business Customer description: Create a new business customer with verification details, addresses, and associated parties x-mint: content: "\n This endpoint was deprecated on May 20, 2026. Use [Create Business Customer V2](https://developer.fin.com/api-reference/customers/create-business-customer-v2) instead.\n\n\n## Important Requirements\n\n- **Email Address**: Must be all lowercase or you will receive a validation error\n- **RELIANCE Verification**: If you attempt to use `RELIANCE` verification type but it's not enabled for your client, you will receive a 423 error with message: \"RELIANCE is not available for your client\"\n- **Third-party Fund Usage**: The `third_party_fund_usage` field indicates whether this customer will be moving other people's money\n- **Ownership Percentages**: The total ownership percentages of all associated parties must add up to more than 0 and less than 100\n" tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBusinessCustomerInput' responses: '200': description: Business customer created successfully content: application/json: schema: type: object properties: data: type: object properties: customer_id: type: string format: uuid description: Unique identifier for the created customer example: 2d0a9df3-e1e5-4955-9759-ce0522e0ddc9 tos_policies_url: type: string format: uri description: URL for customer to accept Terms of Service policies example: https://orchestration.fin.com/orchestration-customer-tos?customer_id=2d0a9df3-e1e5-4955-9759-ce0522e0ddc9&tos_policies_value=f11e77c6-8dc0-4d4b-a3f2-ed84c8ccfc69 '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' '423': description: Locked. RELIANCE verification is not available for your client. content: application/json: schema: type: object properties: message: type: string example: RELIANCE is not available for your client /v1/customers/upload: post: summary: Upload Document description: Upload customer documents using multipart/form-data. Files can be uploaded with arbitrary field names (e.g., poa, poi, passport, file1, etc.) x-mint: content: "## Allowed File Types\n\n- `PDF`\n- `JPG` / `JPEG`\n- `PNG`\n\n\n Files should be uploaded as separate form fields with arbitrary names.\n You can use any field name for files (e.g., `passport`, `poa`, `poi`, `file1`, `document1`, etc.).\n The field name you use will be returned as the key in the response.\n\n" tags: - Customers security: - bearerAuth: [] requestBody: required: true content: multipart/form-data: schema: type: object properties: customer_id: type: string format: uuid example: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9 passport: type: string format: binary poa: type: string format: binary poi: type: string format: binary responses: '200': description: Documents uploaded successfully content: application/json: schema: type: object properties: data: type: object properties: files: type: array items: type: object additionalProperties: type: string example: - passport: /CwW9PHhP_Germany-passport.jpg - poa: /KVdLfqjR_germany-poa-green.jpg '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v2/customers/{customer_id}/individual/attach: post: 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. tags: - Customers security: - bearerAuth: [] 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 /v1/customers/individual/attach: post: summary: Attach Documents to Individual Customer description: Attach proof of identity and proof of address documents to an existing individual customer x-mint: content: "\n Before calling this endpoint, upload documents using the [Upload document](https://developer.fin.com/api-reference/customers/upload-document) endpoint\n to obtain the URIs needed for the `files` arrays.\n\n\n\n The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter\n returned from the Create Individual Customer endpoint.\n\n" tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AttachDocumentForIndividualCustomerInput' responses: '200': description: Documents attached successfully content: application/json: schema: type: object properties: data: type: object properties: customer_id: type: string format: uuid example: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9 '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v1/customers/associated-parties/individual/attach: post: summary: Attach Document To Associated Party description: Attach proof of identity and proof of address documents to associated parties of an existing customer x-mint: content: "\n This endpoint was deprecated on May 20, 2026. Use [Attach Documents to Associated Party V2](https://developer.fin.com/api-reference/customers/attach-documents-to-associated-party-v2) instead.\n\n\n\n Before calling this endpoint, upload documents using the [Upload document](https://developer.fin.com/api-reference/customers/upload-document) endpoint\n to obtain the URIs needed for the `files` arrays.\n\n\n\n This endpoint allows attaching documents for multiple associated parties in a single request.\n\n" tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AttachDocumentToAssociatedPartyInput' responses: '200': description: Documents attached successfully content: application/json: schema: type: object properties: data: type: object description: Generic response object '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v1/customers/business/attach: post: summary: Attach Documents to Business Customer description: Attach ownership structure, company details, and legal presence documents to an existing business customer x-mint: content: "\n This endpoint was deprecated on May 20, 2026. Use [Attach Documents to Business Customer V2](https://developer.fin.com/api-reference/customers/attach-documents-to-business-customer-v2) instead.\n\n\n\n - Before calling this endpoint, upload documents using the [Upload document](https://developer.fin.com/api-reference/customers/upload-document) endpoint to obtain the URIs needed for the `files` arrays.\n - The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter returned from the Create Business Customer endpoint.\n\n" tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AttachDocumentsToBusinessCustomerInput' responses: '200': description: Documents attached successfully content: application/json: schema: type: object properties: data: type: object description: Generic response object '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v1/customers/enable-preference: post: summary: Enable USD Features description: Enable USD features for an existing customer x-mint: content: "\n This endpoint is deprecated and will be removed in a future release. Do not use it in new integrations. You can skip this step entirely and call [Create Virtual Account V2](https://developer.fin.com/api-reference/virtual-accounts/create-virtual-account-v2) directly, which handles USD feature enablement as part of account creation.\n\n" tags: - Customers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - customer_id properties: customer_id: type: string format: uuid example: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9 responses: '200': description: USD features enabled successfully content: application/json: schema: type: object properties: data: type: object description: Generic response object '401': $ref: '#/components/responses/AuthenticationError' '422': $ref: '#/components/responses/ValidationError' /v2/customers/{customer_id}/business/attach: post: summary: Attach Documents to Business Customer V2 description: 'Attach formation, ownership, and supporting documents to an existing business customer. Documents are categorised into three arrays: formation_documents, ownership_documents, and supporting_documents, replacing the v1 ownership_structure / company_details / legal_presence structure.' x-mint: content: "\n - Upload files first using the [Upload document](https://developer.fin.com/api-reference/customers/upload-document) endpoint to obtain URIs, then reference them here.\n - Parse `tos_policies_value` from the `tos_policies_url` returned by `POST /v2/customers/business` and include it in this request.\n\n\n## Document Type Reference\n\nSee [Entity-wise document requirement](https://developer.fin.com/guides/compliance-and-regulatory/entity-wise-document-requirement) for all valid `type` values per\ncategory and entity type.\n" tags: - Customers security: - bearerAuth: [] 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/AttachDocumentsToBusinessCustomerV2Input' example: formation_documents: - type: EVIDENCE_OF_DIRECTORS_AND_CONTROLLERS description: Certificate of Incorporation files: - uri: /AbAcQ4hn_0652746727637.pdf - type: REGISTRATION_DOCUMENT description: Business registration doc files: - uri: /AbAcQ4hn_0652746727638.pdf ownership_documents: - type: PROOF_OF_SIGNATORY_AUTHORITY description: Shareholder Registry files: - uri: /XyZ123mn_0652746727639.pdf supporting_documents: - type: PROOF_OF_SOURCE_OF_FUNDS files: - uri: /PoAdef45_0652746727640.pdf - type: PROOF_OF_ADDRESS files: - uri: /PoAdef45_0652746727641.pdf tos_policies_value: 6955e70b-f9f3-4076-b1ce-5c897085dd24 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' /v2/customers/{customer_id}/associated-parties/individual/attach: post: 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. x-mint: content: "\n Upload files first using [Upload document](https://developer.fin.com/api-reference/customers/upload-document) to obtain URIs,\n then reference them here.\n\n\n\n The `associated_party_id` for each party is returned in the\n [Get Customer Details V2](https://developer.fin.com/api-reference/customers/get-customer-details-v2) response.\n\n\n## Identity Document Side Requirements\n\n| Type | Sides Required |\n|------|---------------|\n| `PASSPORT` | No (single image) |\n| `NATIONAL_ID` | Yes: `FRONT` + `BACK` |\n| `DRIVERS_LICENSE` | Yes: `FRONT` + `BACK` |\n| `RESIDENCE_PERMIT` | No (single image) |\n" tags: - Customers security: - bearerAuth: [] 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' components: schemas: V2Addresses: type: object required: - is_incorporated_address_same - incorporated_address properties: is_incorporated_address_same: type: boolean description: Whether the physical operating address is the same as the incorporated address. If false, physical_address is required. example: false incorporated_address: $ref: '#/components/schemas/V2Address' physical_address: allOf: - $ref: '#/components/schemas/V2Address' description: Physical operating address. Required when is_incorporated_address_same is false. CreateIndividualCustomerInput: type: object required: - verification_type - basic_info - address - financial_profile properties: verification_type: type: string enum: - STANDARD - RELIANCE example: STANDARD basic_info: type: object required: - first_name - last_name - dob - email - phone - country_of_residence - nationality - tin properties: first_name: type: string example: John last_name: type: string example: Doe dob: type: string format: date example: '1990-01-15' email: type: string format: email example: john.doe@example.com phone: type: string example: '+14155551234' country_of_residence: $ref: '#/components/schemas/CountryCode' nationality: $ref: '#/components/schemas/CountryCode' tin: type: string example: 123-45-6789 address: type: object required: - street - city - state - postal_code - country properties: street: type: string example: 123 Main St city: type: string example: New York state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: US-NY postal_code: type: string example: '10001' country: $ref: '#/components/schemas/CountryCode' financial_profile: type: object required: - occupation_id - source_of_fund_id - purpose_id - monthly_volume_usd properties: occupation_id: type: integer example: 1 source_of_fund_id: type: integer example: 1 purpose_id: type: integer example: 1 monthly_volume_usd: type: integer minimum: 0 example: 5000 meta_data: type: object additionalProperties: true example: customer_reference: REF-12345 V2Compliance: type: object properties: operates_in_prohibited_countries: type: boolean description: Whether the business operates in OFAC/sanctioned countries. example: false additional_description_for_compliance_screening: type: string description: Free-text compliance notes for manual review. example: We do not operate in any OFAC-sanctioned jurisdictions. risk_profile: $ref: '#/components/schemas/V2RiskProfile' regulated_activity: $ref: '#/components/schemas/V2RegulatedActivity' aml: $ref: '#/components/schemas/V2AML' V2RiskProfile: type: object properties: high_risk_activities: type: array description: High-risk activities the business engages in. If non-empty, high_risk_activities_explanation is required. items: type: string enum: - adult_entertainment - crypto_exchange - gambling - cannabis - weapons - money_services - cross_border_payments example: - cross_border_payments high_risk_activities_explanation: type: string description: Explanation of declared high-risk activities. Required when high_risk_activities is non-empty. example: We facilitate cross-border B2B payments, subject to enhanced due diligence procedures. conducts_money_services: type: boolean description: Whether the business provides money services. example: true conducts_money_services_via_fin: type: boolean description: Whether money services are provided via financial intermediaries. example: false conducts_money_services_description: type: string description: Details about the money services offered. example: Licensed money transmitter providing international wire transfer services. AttachDocumentForIndividualCustomerInput: type: object required: - customer_id - proof_of_identity - proof_of_address - tos_policies_value properties: customer_id: type: string format: uuid example: 55bd6b4e-c20a-4cc8-9535-91d5557a67d9 proof_of_identity: $ref: '#/components/schemas/ProofOfIdentity' proof_of_address: $ref: '#/components/schemas/ProofOfAddressIndividual' tos_policies_value: type: string example: e9414388-fbdf-4407-b5c2-bc39eae3645b CustomerWallet: type: object properties: id: type: string format: uuid description: Unique wallet identifier. example: 27dbc0f2-e5ae-444b-b4ab-0764252aedf6 status: type: string enum: - PENDING - ACTIVE - INACTIVE description: Wallet provisioning status. Wallets start PENDING and move to ACTIVE (or INACTIVE) asynchronously once the wallet address has been issued; creation is not synchronous. example: ACTIVE currency: type: string description: Token held in this wallet. example: USDC rail: type: string description: Blockchain network for this wallet. example: ETHEREUM address: type: string nullable: true description: On-chain wallet address. Null until the wallet is provisioned. example: '0xc42a5f7083c7e8f1d9820c7660867277289cd998' balance: type: number description: Current wallet balance. example: 10.000001 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 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 V2FinancialProfile: type: object required: - purpose_id - source_of_fund_ids - source_of_wealth_ids - estimated_annual_revenue_usd - expected_monthly_deposits_usd - expected_monthly_withdrawals_usd - third_party_fund_usage properties: purpose_id: type: integer description: Account purpose. Foreign key to purposes reference table. Fetch valid values from [List Account Purposes](https://developer.fin.com/api-reference/catalogue/list-account-purposes) endpoint. example: 3 purpose_remarks: type: string description: Additional context for the account purpose. Required if purpose represents "Other". example: Cross-border B2B payments for international suppliers source_of_fund_ids: type: array description: Source(s) of business funds. FK array to source_of_funds reference table. Min 1 item. Fetch valid values from [List Source of Funds](https://developer.fin.com/api-reference/catalogue/list-source-of-funds). Order items from the largest to smallest contributor. The ID representing the primary source of funds must come first, followed by secondary sources in descending order. minItems: 1 items: type: integer example: - 1 - 4 source_of_funds_description: type: string description: Additional context for source of funds. example: Revenue from software licensing and SaaS subscriptions source_of_wealth_ids: type: array description: Source(s) of owner's wealth. FK array to source_of_wealth reference table. Min 1 item. Fetch valid values from [List Source of Wealth](https://developer.fin.com/api-reference/catalogue/list-source-of-wealth). Order items from the largest to smallest contributor. The primary source must come first. minItems: 1 items: type: integer example: - 2 estimated_annual_revenue_usd: type: integer minimum: 0 description: Estimated annual revenue in USD (not cents). Must be >= 0. example: 5000000 expected_monthly_deposits_usd: type: integer minimum: 0 description: Expected monthly deposit volume in USD (not cents). Must be >= 0. example: 400000 expected_monthly_withdrawals_usd: type: integer minimum: 0 description: Expected monthly withdrawal volume in USD (not cents). Must be >= 0. example: 350000 expected_transaction_value_usd: type: integer minimum: 0 description: Typical single transaction value in USD (not cents). Optional. example: 50000 expected_monthly_transaction_count: type: integer minimum: 0 description: Expected number of transactions per month. Optional. example: 20 third_party_fund_usage: type: boolean description: Whether this business will process, hold, or move funds on behalf of other parties. Set to true only for MSBs and payment processors. Triggers enhanced compliance review. example: false V2BasicInfo: type: object required: - legal_name - legal_name_en - trade_name - description - entity_type - email - phone - incorporation_date - country_of_incorporation - registration_number - tax_info - websites properties: legal_name: type: string maxLength: 255 description: Official registered business name. Must match incorporation documents. example: Fin.com legal_name_en: type: string description: English translation of the legal name. Required if legal_name contains non-ASCII characters. example: Fin.com trade_name: type: string description: Common operating name or DBA (Doing Business As). example: Toronggo trade_name_en: type: string description: English translation of the trade name. example: Toronggo description: type: string maxLength: 500 description: Description of the company's business activities and purpose. example: Bangladesh-based technology company providing cross-border B2B payment and financial technology services entity_type: type: string enum: - LIMITED_LIABILITY_COMPANY - PUBLICLY_LISTED_COMPANY - SOLE_PROPRIETOR - PARTNERSHIP - CORPORATION - TRUST - PRIVATE_FOUNDATION - CHARITY - NONPROFIT_ORGANIZATION - PUBLIC_AGENCY_OR_AUTHORITY description: Legal entity type of the business. example: LIMITED_LIABILITY_COMPANY email: type: string format: email description: Business email address. Must be all lowercase. example: m@tech.com phone: type: string description: Business phone number in E.164 format. example: '+8801529876543' incorporation_date: type: string format: date description: Date of incorporation in YYYY-MM-DD format. Cannot be a future date. example: '2018-06-15' country_of_incorporation: $ref: '#/components/schemas/CountryCode' registration_number: type: string description: Business registration or company number. Required. example: 12-3456789 legal_entity_identifier: type: string minLength: 20 maxLength: 20 description: LEI code (20-character alphanumeric). Optional. example: 549300EXAMPLE0001X23 is_dao: type: boolean description: Whether the entity is a Decentralized Autonomous Organization. example: false tax_info: type: array description: Tax and identifying documents for the business. Min 1 item. minItems: 1 items: $ref: '#/components/schemas/V2IdentifyingDocument' websites: type: array description: Business website URLs. Min 1 item. minItems: 1 items: type: string format: uri example: - https://fin.com BusinessCustomerDetail: type: object title: Business properties: customer_id: type: string format: uuid example: 94e6b847-4e19-49e3-b3ab-ffa95872eda9 type: type: string enum: - BUSINESS business_name: type: string example: Fin.com email: type: string format: email example: contact@fin.com phone: type: string example: '+6591234567' country_of_incorporation: type: string example: SGP verification_type: type: string example: STANDARD customer_status: type: string example: APPROVED tos_policies_url: type: string format: uri example: https://orchestration.fin.com/orchestration-customer-tos?customer_id=94e6b847-4e19-49e3-b3ab-ffa95872eda9&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24 associated_parties: type: array items: type: object properties: id: type: string format: uuid example: 42daffd3-09a0-4d48-8e73-2680a953d0e1 type: type: string example: INDIVIDUAL ownership_percent: type: number example: 10 email: type: string format: email example: john.doe@fin.com verification: type: object properties: status: type: string example: APPROVED reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true updated_at: type: string format: date-time example: '2026-04-15T11:29:08Z' created_at: type: string format: date-time example: '2026-04-15T11:26:12Z' updated_at: type: string format: date-time example: '2026-04-15T11:31:18Z' last_status_updated_at: type: string format: date-time example: '2026-04-15T11:29:09Z' capabilities: type: object description: On-ramp and off-ramp capabilities for the customer properties: on_ramp: type: array items: type: object properties: currency: type: string example: USD status: type: boolean example: false methods: type: array items: type: string example: - ACH - FEDWIRE reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true off_ramp: type: array items: type: object properties: currency: type: string example: USD status: type: boolean example: true methods: type: array items: type: string example: - BANK reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true rejection_reason: type: object nullable: true description: Populated when customer_status is REJECTED. Null otherwise. request_for_information: type: array description: List of pending information requests. Empty when none are outstanding. items: type: object 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 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 CreateBusinessCustomerInput: type: object required: - basic_info - financial_profile - addresses - associated_parties properties: verification_type: type: string enum: - STANDARD - RELIANCE description: Type of verification to perform (optional, defaults to STANDARD). Note that RELIANCE verification must be enabled for your client, or you will receive a 423 error. example: RELIANCE basic_info: type: object required: - business_name - description - entity_type - website - email - incorporation_date - phone - country_of_incorporation - registration_number - tax_id properties: business_name: type: string description: Legal name of the business example: Acme Corp Ltd business_trade_name: type: string description: Trading name or DBA (Doing Business As) name example: Acme description: type: string description: Description of the company's business example: International software and payments company entity_type: type: string enum: - LIMITED_LIABILITY_COMPANY - PUBLICLY_LISTED_COMPANY - SOLE_PROPRIETOR - PARTNERSHIP - CORPORATION - TRUST - PRIVATE_FOUNDATION - CHARITY - NONPROFIT_ORGANIZATION - PUBLIC_AGENCY_OR_AUTHORITY - PRIVATE_LIMITED description: Legal entity type of the business example: LIMITED_LIABILITY_COMPANY website: type: string format: uri description: Company website URL example: https://fin.com email: type: string format: email description: Business email address. Must be all lowercase or a validation error will occur. example: contact@acmecorp.com incorporation_date: type: string format: date description: Date of incorporation in YYYY-MM-DD format example: '2018-06-15' phone: type: string description: Business phone number example: '+14155552671' country_of_incorporation: $ref: '#/components/schemas/CountryCode' registration_number: type: string description: Business registration number example: 12-3456789 tax_id: type: string description: Tax identification number or EIN (must be EIN for USA) example: 12-3456789 financial_profile: type: object required: - purpose_id - business_industry_id - monthly_volume - source_of_fund_id - third_party_fund_usage properties: purpose_id: type: integer description: Unique identifier for account purpose retrieved from the catalogue API [List Account Purposes](https://developer.fin.com/api-reference/catalogue/list-account-purposes). example: 10 other_purpose: type: string description: Custom purpose description (only when purpose_id represents "Other") example: custom other purpose business_industry_id: type: integer description: Unique identifier for business industry retrieved from the catalogue API [List Industries](https://developer.fin.com/api-reference/catalogue/list-industries) example: 1 monthly_volume: type: integer minimum: 0 description: Expected monthly transaction volume in USD (not cents) example: 100000 source_of_fund_id: type: integer description: Unique identifier for source of funds retrieved from the catalogue API [List Source of Funds](https://developer.fin.com/api-reference/catalogue/list-source-of-funds) example: 13 third_party_fund_usage: type: boolean description: Indicates whether this customer will be moving other people's money (third-party funds) example: false addresses: type: object required: - is_incorporated_address_same - incorporated_address properties: is_incorporated_address_same: type: boolean description: Whether the physical address is the same as the incorporated address example: true incorporated_address: type: object required: - street - city - state - postal_code - country properties: street: type: string description: Street address example: '10 Anson Road #26-04 International Plaza' city: type: string description: City name example: Singapore state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: SG-01 postal_code: type: string description: Postal or ZIP code example: 079903 country: $ref: '#/components/schemas/CountryCode' physical_address: type: object description: Physical operating address (required only if is_incorporated_address_same is false) required: - street - city - state - postal_code - country properties: street: type: string example: 456 Market Street Floor 3 city: type: string example: San Francisco state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: US-CA postal_code: type: string example: '94103' country: $ref: '#/components/schemas/CountryCode' associated_parties: type: array description: Array of associated parties (UBOs, directors, shareholders, etc.) minItems: 1 items: type: object required: - basic_info - address - ownership_info properties: basic_info: type: object required: - first_name - last_name - dob - email - phone - country_of_residence - nationality - tin properties: first_name: type: string example: John last_name: type: string example: Doe dob: type: string format: date example: '1985-03-20' email: type: string format: email example: john.doe@acmecorp.com phone: type: string example: '+14155551234' country_of_residence: $ref: '#/components/schemas/CountryCode' nationality: $ref: '#/components/schemas/CountryCode' tin: type: string description: Tax Identification Number example: 123-45-6789 address: type: object required: - street - city - state - postal_code - country properties: street: type: string example: 456 Oak Avenue city: type: string example: San Francisco state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: US-CA postal_code: type: string example: '94102' country: $ref: '#/components/schemas/CountryCode' ownership_info: type: object required: - designation - percentage_of_ownership - relationship_establishment_date properties: designation: type: string description: Role or position in the company (e.g., CEO, Director, UBO) example: CEO percentage_of_ownership: type: number format: float minimum: 0 description: Percentage of ownership in the business. Total must be < 100. example: 75 relationship_establishment_date: type: string format: date description: Date when the relationship was established in YYYY-MM-DD format example: '2018-06-15' meta_data: type: object additionalProperties: true description: Additional custom metadata as key-value pairs example: reference: ref-20250910-XYZ V2RegulatedActivity: type: object required: - description - primary_authority_country_code - primary_authority_name - license_number properties: description: type: string description: Description of the regulated activity. example: Licensed money transmitter operating under FinCEN registration and state-level MSB licenses primary_authority_country_code: $ref: '#/components/schemas/CountryCode' primary_authority_name: type: string description: Name of the primary regulatory authority. example: FinCEN license_number: type: string description: Regulatory license or registration number. example: MSB-12345678 V2AssociatedParty: type: object required: - basic_info - address - roles properties: ref: type: string description: Client-defined reference identifier for this party. Used for internal tracking only. example: owner-001 basic_info: $ref: '#/components/schemas/V2APBasicInfo' address: $ref: '#/components/schemas/V2Address' roles: type: array description: Roles held by this party. At least one role is required. A party may hold both roles simultaneously. At least one party must hold both shareholder and ubo. minItems: 1 items: type: string enum: - shareholder - ubo example: - shareholder - ubo ownership_info: $ref: '#/components/schemas/V2OwnershipInfo' V2FormationDocumentItem: type: object required: - files properties: type: type: string enum: - REGISTRATION_DOCUMENT - CONSTITUTIONAL_DOCUMENT - FORMATION_DOCUMENT - PROOF_OF_TAX_IDENTIFICATION - EVIDENCE_OF_DIRECTORS_AND_CONTROLLERS description: Formation document type. example: REGISTRATION_DOCUMENT description: type: string description: Optional human-readable description of this specific document. example: Certificate of Incorporation files: type: array description: One or more file URIs obtained 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_0652746727639.pdf CreateBusinessCustomerV2Input: type: object required: - verification_type - industry_codes - basic_info - financial_profile - addresses - associated_parties properties: verification_type: type: string enum: - STANDARD - RELIANCE description: Verification level. Defaults to STANDARD if omitted. RELIANCE must be explicitly enabled for your client. example: STANDARD industry_codes: type: array description: NAICS 2022 6-digit industry codes. Min 1 item. See the full list at [Business-industry-codes](https://developer.fin.com/business-industry-codes). minItems: 1 items: type: string example: - '523130' basic_info: $ref: '#/components/schemas/V2BasicInfo' financial_profile: $ref: '#/components/schemas/V2FinancialProfile' addresses: $ref: '#/components/schemas/V2Addresses' associated_parties: type: array description: UBOs (≥25% ownership), directors, and authorized signatories. Min 1 item required. minItems: 1 items: $ref: '#/components/schemas/V2AssociatedParty' holding_structure: $ref: '#/components/schemas/V2HoldingStructure' public_listings: type: array description: Stock exchange listings. Required for publicly traded companies. items: $ref: '#/components/schemas/V2PublicListing' compliance: $ref: '#/components/schemas/V2Compliance' meta_data: type: object description: Client-defined key-value metadata for internal tracking. properties: reference: type: string description: Client-defined external reference identifier. example: REF-20250123-ACME additionalProperties: true V2IndividualIdentifyingDocument: type: object required: - country_code - document_type - document_id properties: country_code: $ref: '#/components/schemas/CountryCode' document_type: type: string description: Individual tax ID document type, validated per country. See all available types at [Individual Tax ID documents](https://developer.fin.com/guides/compliance-and-regulatory/individual-tax-id-documents). example: TIN document_id: type: string description: The document ID or number. Format validated per country and document type. example: '1234567890123' ProofOfAddressIndividual: type: object description: The proof of address document must not be older than three months. required: - type - country - files properties: type: type: string enum: - PASSPORT - NATIONAL_ID - DRIVERS_LICENSE - RESIDENCE_PERMIT - UTILITY_BILL - GOVERNMENT_LETTER - BANK_STATEMENT example: UTILITY_BILL country: $ref: '#/components/schemas/CountryCode' files: type: array items: type: object required: - uri properties: uri: type: string example: /AbAcQ4hn_0652746727638.pdf CreateIndividualCustomerV2Input: type: object required: - verification_type - basic_info - address - financial_profile properties: verification_type: type: string enum: - STANDARD - RELIANCE example: STANDARD basic_info: type: object required: - first_name - last_name - dob - email - phone - country_of_residence - primary_nationality - tax_info properties: first_name: type: string example: Maria first_name_en: type: string description: English transliteration. Required if first_name contains non-ASCII characters. example: Maria middle_name: type: string example: Elena middle_name_en: type: string description: English transliteration. Required if middle_name contains non-ASCII characters. example: Elena last_name: type: string example: Garcia last_name_en: type: string description: English transliteration. Required if last_name contains non-ASCII characters. example: Garcia dob: type: string format: date description: Date of birth in YYYY-MM-DD format. Age must be between 18 and 120 years. example: '1990-04-15' email: type: string format: email description: Must be all lowercase. example: maria.garcia@example.com phone: type: string description: E.164 format. example: '+14155552671' country_of_residence: $ref: '#/components/schemas/CountryCode' primary_nationality: $ref: '#/components/schemas/CountryCode' secondary_nationality: $ref: '#/components/schemas/CountryCode' gender: type: string enum: - MALE - FEMALE example: FEMALE tax_info: type: array minItems: 1 description: Tax identification documents. Each entry must have a unique document_id. items: type: object required: - country_code - document_type - document_id properties: country_code: $ref: '#/components/schemas/CountryCode' document_type: type: string description: Tax document type (e.g. SSN, TIN). example: SSN document_id: type: string example: 123-45-6789 address: type: object required: - street_line_1 - city - subdivision_code - postal_code - country properties: street_line_1: type: string example: 123 Market Street street_line_1_en: type: string description: English transliteration. Required if street_line_1 contains non-ASCII characters. example: 123 Market Street street_line_2: type: string example: Apt 4B street_line_2_en: type: string description: English transliteration. Required if street_line_2 contains non-ASCII characters. example: Apt 4B city: type: string example: San Francisco subdivision_code: type: string description: ISO 3166-2 subdivision code (e.g. US-CA). example: US-CA postal_code: type: string example: '94103' country: $ref: '#/components/schemas/CountryCode' financial_profile: type: object required: - employment_status - occupation_id - purpose_id - source_of_fund_ids - monthly_volume_usd properties: employment_status: type: string enum: - EMPLOYED - SELF_EMPLOYED - RETIRED - STUDENT - UNEMPLOYED description: Employment status of the individual. example: EMPLOYED occupation_id: type: integer description: Occupation. FK to occupations reference table. Fetch valid values from GET /v1/occupations?type=INDIVIDUAL. example: 42 purpose_id: type: integer description: Account purpose. FK to purposes reference table. Fetch valid values from GET /v1/purposes?type=INDIVIDUAL. example: 3 purpose_remarks: type: string example: Personal remittances to family source_of_fund_ids: type: array minItems: 1 items: type: integer description: Source(s) of funds. FK array to source_of_funds reference table. Fetch valid values from GET /v1/source-of-funds?type=INDIVIDUAL. example: - 1 - 5 source_of_funds_description: type: string example: Monthly salary from employment monthly_volume_usd: type: integer minimum: 0 example: 5000 meta_data: type: object additionalProperties: true example: reference: client-ref-abc-001 V2Address: type: object required: - street_line_1 - street_line_1_en - city - state - subdivision_code - postal_code - country properties: street_line_1: type: string description: Primary street address. P.O. Box addresses are not accepted. example: 123 Main Street street_line_1_en: type: string description: English translation of street_line_1. Required if address contains non-ASCII characters. example: 123 Main Street street_line_2: type: string description: Secondary address (suite, floor, unit, etc.). Optional. example: Suite 400 street_line_2_en: type: string description: English translation of street_line_2. Optional. example: Suite 400 city: type: string maxLength: 100 description: City or municipality name. example: San Francisco state: type: string description: State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: US-CA subdivision_code: type: string description: State/province code from [List Subdivisions](https://developer.fin.com/api-reference/catalogue/list-subdivisions). Same value as state field. example: US-CA postal_code: type: string description: ZIP or postal code. Format validated per country. example: '94105' country: $ref: '#/components/schemas/CountryCode' AttachDocumentsToBusinessCustomerV2Input: type: object required: - tos_policies_value properties: formation_documents: type: array description: Documents proving the legal existence of the business (e.g., Certificate of Incorporation, Articles of Incorporation, Trust Agreement, Tax registration certificate). items: $ref: '#/components/schemas/V2FormationDocumentItem' ownership_documents: type: array description: Documents proving who controls and owns the business (e.g., Shareholder Register, Org Chart, Power of Attorney, Directors Registry). items: $ref: '#/components/schemas/V2OwnershipDocumentItem' supporting_documents: type: array description: Additional compliance and operational documents (e.g., Proof of Address, Proof of Source of Funds, AML Comfort Letter, Marketing Materials). items: $ref: '#/components/schemas/V2SupportingDocumentItem' tos_policies_value: type: string description: Parsed from the tos_policies_value query parameter in the tos_policies_url returned by POST /v2/customers/business. Signifies the customer has accepted the Terms of Service. example: f11e77c6-8dc0-4d4b-a3f2-ed84c8ccfc69 IndividualCustomerDetail: type: object title: Individual properties: customer_id: type: string format: uuid example: 56c41b8e-e650-4f55-94f6-26a888a9b64d type: type: string enum: - INDIVIDUAL first_name: type: string example: John last_name: type: string example: Doe email: type: string format: email example: john.doe@fin.com phone: type: string example: '+14724480512' country_of_residence: type: string example: USA verification_type: type: string example: STANDARD customer_status: type: string example: ON_HOLD tos_policies_url: type: string format: uri example: https://orchestration.fin.com/orchestration-customer-tos?customer_id=56c41b8e-e650-4f55-94f6-26a888a9b64d&tos_policies_value=e9414388-fbdf-4407-b5c2-bc39eae3645b created_at: type: string format: date-time example: '2026-04-15T11:49:27Z' updated_at: type: string format: date-time example: '2026-04-15T11:52:48Z' last_status_updated_at: type: string format: date-time example: '2026-04-15T11:52:48Z' capabilities: type: object description: On-ramp and off-ramp capabilities for the customer properties: on_ramp: type: array items: type: object properties: currency: type: string example: USD status: type: boolean example: false methods: type: array items: type: string example: - ACH - FEDWIRE reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true off_ramp: type: array items: type: object properties: currency: type: string example: USD status: type: boolean example: false methods: type: array items: type: string example: - BANK reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true example: Customer is under review rejection_reason: type: object nullable: true description: Populated when customer_status is REJECTED. Null otherwise. example: null request_for_information: type: array description: List of open requests for additional information. Empty when none are outstanding. items: type: object example: [] V2AML: type: object properties: supervisory_authority_name: type: string description: Name of the AML supervisory authority. example: FinCEN license_number: type: string description: AML license number. example: MSB-12345678 has_appointed_mlro: type: boolean description: Whether a Money Laundering Reporting Officer has been appointed. example: true customer_risk_split: $ref: '#/components/schemas/V2CustomerRiskSplit' prohibits_anonymous_or_fictitious_accounts: type: boolean description: Policy on anonymous or fictitious accounts. example: true prohibits_accounts_for_unlicensed_or_shell_customers: type: boolean description: Policy on unlicensed or shell customers. example: true customer_identity_verification: $ref: '#/components/schemas/V2VerificationMethod' pep_and_sanctions_screening: $ref: '#/components/schemas/V2VerificationMethod' sanction_lists: type: array description: Names of sanction lists screened against. items: type: string example: - OFAC - EU - UN - HMT customer_risk_classification_from_due_diligence: type: boolean example: true enhanced_due_diligence_process: type: boolean example: true transaction_monitoring: $ref: '#/components/schemas/V2VerificationMethod' procedures_for_transaction_monitoring: type: boolean example: true subject_to_ml_or_tf_investigation: type: string description: Current ML/TF investigation status. example: none subject_to_regulatory_enforcement_past_2_years: type: string description: Regulatory enforcement history over the last 2 years. example: none confirms_no_service_to_sanctioned_countries: type: boolean example: true client_funds_accessibility: type: string description: Policy on client fund accessibility. example: closed_loop aml_ctf_audit_completed: type: boolean example: true planned_audit_date: type: string format: date description: Planned next audit date in YYYY-MM-DD format. example: '2026-12-01' 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' V2IdentifyingDocument: type: object required: - country_code - document_type - document_id properties: country_code: $ref: '#/components/schemas/CountryCode' document_type: type: string description: 'Business tax ID document type, validated per country. Examples: EIN, TIN, VAT_ID, TAX_ID, etc. See all available types at [Business tax id documents by region](https://developer.fin.com/business-tax-id-documents-by-region).' example: EIN document_id: type: string description: The document ID or number. Format validated per country and document type. example: 12-3456789 V2HoldingStructure: type: object properties: has_material_intermediary_ownership: type: boolean description: Whether any intermediary holds a material ownership stake. example: true corporate_shareholders: type: array description: List of corporate (non-individual) shareholders. items: $ref: '#/components/schemas/V2CorporateShareholder' foreign_branches: type: array description: List of foreign branch registrations. items: $ref: '#/components/schemas/V2ForeignBranch' 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 V2CorporateShareholder: type: object required: - entity_name - entity_name_en - registration_country_code - ownership_percentage properties: entity_name: type: string description: Corporate shareholder's legal name. example: Acme Ventures LLC entity_name_en: type: string description: English translation of entity name. Required if entity_name contains non-ASCII characters. example: Acme Ventures LLC registration_country_code: $ref: '#/components/schemas/CountryCode' ownership_percentage: type: number format: float minimum: 0 maximum: 100 description: Ownership stake as a percentage (0 to 100). example: 60 registration_number: type: string description: Entity registration number. Optional. example: 98-7654321 entity_type: type: string enum: - LIMITED_LIABILITY_COMPANY - PUBLICLY_LISTED_COMPANY - SOLE_PROPRIETOR - PARTNERSHIP - CORPORATION - TRUST - PRIVATE_FOUNDATION - CHARITY - NONPROFIT_ORGANIZATION - PUBLIC_AGENCY_OR_AUTHORITY description: Legal entity type of the corporate shareholder. Optional. example: LIMITED_LIABILITY_COMPANY incorporation_date: type: string format: date description: Incorporation date in YYYY-MM-DD format. Optional. example: '2015-03-01' V2CustomerRiskSplit: type: object description: Breakdown of customer risk classifications. Percentages must sum to 100. required: - low_risk - medium_risk - high_risk properties: low_risk: type: integer minimum: 0 maximum: 100 description: Percentage of low-risk customers. example: 70 medium_risk: type: integer minimum: 0 maximum: 100 description: Percentage of medium-risk customers. example: 25 high_risk: type: integer minimum: 0 maximum: 100 description: Percentage of high-risk customers. example: 5 AttachDocumentsToBusinessCustomerInput: type: object required: - customer_id - ownership_structure - company_details - legal_presence - tos_policies_value properties: customer_id: type: string format: uuid example: 2d0a9df3-e1e5-4955-9759-ce0522e0ddc9 ownership_structure: type: array items: type: object required: - type - files properties: type: type: string enum: - SHAREHOLDER_REGISTRY example: SHAREHOLDER_REGISTRY files: type: array items: type: object required: - uri properties: uri: type: string example: /AbAcQ4hn_0652746727639.pdf company_details: type: array items: type: object required: - type - files properties: type: type: string enum: - CERT_OF_INCORPORATION - MEMORANDUM_OF_ASSOCIATION example: CERT_OF_INCORPORATION files: type: array items: type: object required: - uri properties: uri: type: string example: /AbAcQ4hn_0652746727640.pdf legal_presence: type: array items: type: object required: - type - files properties: type: type: string enum: - PROOF_OF_ADDRESS example: PROOF_OF_ADDRESS files: type: array items: type: object required: - uri properties: uri: type: string example: /AbAcQ4hn_0652746727641.pdf tos_policies_value: type: string example: e9414388-fbdf-4407-b5c2-bc39eae3645b V2OwnershipInfo: type: object description: Required when roles includes ubo. required: - designation - percentage_of_ownership - relationship_establishment_date - has_control - is_signer - is_director properties: designation: type: string maxLength: 100 description: Title or position in the company (e.g., CEO, CFO, Founder). example: CEO percentage_of_ownership: type: number format: float minimum: 0 maximum: 100 description: Ownership stake as a percentage (0 to 100). Individual parties may have 0% ownership. Total across all parties must be < 100%. example: 75 relationship_establishment_date: type: string format: date description: 'Date when the relationship with the business began. Format: YYYY-MM-DD. Cannot be a future date.' example: '2018-06-15' has_control: type: boolean description: Whether this party has significant control over the entity. example: true is_signer: type: boolean description: Whether this party is an authorized signatory. example: true is_director: type: boolean description: Whether this party serves as a director. example: true BusinessCustomerDetailV2: title: Business type: object properties: customer_id: type: string format: uuid example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06 type: type: string enum: - BUSINESS business_name: type: string example: Fin.com email: type: string format: email example: m@tech.com phone: type: string example: '+8801529876543' country_of_incorporation: type: string example: BGD verification_type: type: string example: STANDARD customer_status: type: string description: 'The following statuses have been changed from V1. QUEUED (V1) → PROCESSING (V2). ON_HOLD (V1) → IN_COMPLIANCE (V2). REINITIATE (V1) → ACTION_REQUIRED (V2).' enum: - INCOMPLETE - PROCESSING - REVIEWING - APPROVED - ASSOCIATED_PARTIES_REMAINING - IN_COMPLIANCE - ACTION_REQUIRED - REJECTED example: IN_COMPLIANCE tos_policies_url: type: string format: uri associated_parties: type: array items: type: object properties: id: type: string format: uuid example: f6b13e01-044a-4f74-a70b-d5f66b6449af type: type: string example: INDIVIDUAL ownership_percent: type: number example: 60 email: type: string format: email example: fatima.rahman22@acmecorp.com.bd verification: type: object properties: status: type: string enum: - INITIATED - REVIEWING - APPROVED - REJECTED example: APPROVED reason: type: object properties: for_customer: type: string nullable: true for_developer: type: string nullable: true updated_at: type: string format: date-time example: '2026-04-13T11:40:49Z' created_at: type: string format: date-time example: '2026-04-01T12:03:03Z' updated_at: type: string format: date-time example: '2026-04-01T12:03:03Z' rejection_reason: type: object nullable: true description: Populated when customer_status is REJECTED or ACTION_REQUIRED. Contains applicant-level, document-level, and associated party-level rejection details. Null when no rejection exists. properties: applicant: type: object nullable: true description: Applicant-level rejection reason. properties: moderation_comment: type: string example: If you're a sole entrepreneur, upload corporate documents confirming your company's legal status. reject_labels: type: array items: type: string example: - DOCUMENT_MISSING documents: type: array description: Document-level rejection reasons. items: type: object properties: uri: type: string example: /7zlLPvlx_testdoc6.jpg category: type: string example: SUPPORTING_DOCUMENTS moderation_comment: type: string example: This document is not accepted. The document should be of good quality. reject_labels: type: array items: type: string example: - LOW_QUALITY associated_parties: type: array description: Associated party-level rejection reasons. items: type: object example: null request_for_information: type: array description: List of open requests for additional information. Populated when customer_status is ACTION_REQUIRED. Same structure as customer.rfi webhook payload. items: type: object properties: section: type: string example: ownership_documents categories: type: array items: type: object properties: document_type: type: string example: SHAREHOLDER_REGISTRY fields: type: array items: type: object properties: field_name: type: string example: files data_type: type: string enum: - URI - DATE - TEXT - ENUM example: URI status: type: string enum: - MISSING - EXPIRED - INVALID example: INVALID reason: type: string nullable: true example: Unacceptable document. example: [] V2VerificationMethod: type: object description: Used for customer_identity_verification, pep_and_sanctions_screening, and transaction_monitoring. required: - method - system properties: method: type: string description: Verification method (e.g., automated, manual, third_party). example: automated system: type: string description: System or vendor used (e.g., Jumio, Onfido, Internal). example: Jumio ProofOfIdentity: type: object required: - type - number - country - issue_date - expiry_date - files properties: type: type: string enum: - PASSPORT - NATIONAL_ID - DRIVERS_LICENSE - RESIDENCE_PERMIT description: '- `PASSPORT`: Passport - `NATIONAL_ID`: National ID card - `DRIVERS_LICENSE`: Driver''s license - `RESIDENCE_PERMIT` - Residence permit ' example: PASSPORT number: type: string example: A12345678 country: $ref: '#/components/schemas/CountryCode' issue_date: type: string format: date example: '2020-01-15' expiry_date: type: string format: date example: '2030-01-15' files: type: array items: type: object required: - uri properties: side: type: string enum: - FRONT - BACK example: FRONT uri: type: string example: /AbAcQ4hn_0652746727637.pdf V2SupportingDocumentItem: type: object required: - files properties: type: type: string enum: - SHAREHOLDER_REGISTER - PROOF_OF_NATURE_OF_BUSINESS - PROOF_OF_ENTITY_NAME_CHANGE - CERT_OF_INCUMBENCY - PROOF_OF_SOURCE_OF_FUNDS - PROOF_OF_SOURCE_OF_WEALTH - AML_COMFORT_LETTER - MARKETING_MATERIALS - TAX_EXEMPT_ENTITY_CONFIRMATION - E_SIGNATURE_CERTIFICATE - FLOW_OF_FUNDS - PROOF_OF_NATURE_OF_BUSINESS_LICENSE - PROOF_OF_NATURE_OF_BUSINESS_AML_POLICY - EVIDENCE_OF_GOOD_STANDING - PROOF_OF_ACCOUNT_PURPOSE - PROOF_OF_ADDRESS - OTHER description: Supporting document type. example: PROOF_OF_SOURCE_OF_FUNDS description: type: string description: Optional human-readable description of this specific document. example: Bank statements for the past 6 months files: type: array description: One or more file URIs obtained 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_0652746727639.pdf V2PublicListing: type: object properties: mic: type: string description: ISO 10383 Market Identifier Code (e.g., XNAS for NASDAQ). example: XNAS isin: type: string minLength: 12 maxLength: 12 description: International Securities Identification Number (12 chars). example: US0231351067 ticker_symbol: type: string description: Stock exchange ticker symbol. example: ACME 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 IndividualCustomerDetailV2: title: Individual type: object properties: customer_id: type: string format: uuid example: 56c41b8e-e650-4f55-94f6-26a888a9b64d type: type: string enum: - INDIVIDUAL first_name: type: string example: John last_name: type: string example: Doe email: type: string format: email example: john.doe@example.com phone: type: string example: '+14155551234' country_of_residence: type: string example: USA verification_type: type: string example: STANDARD customer_status: type: string example: ACTION_REQUIRED tos_policies_url: type: string format: uri example: https://orchestration.fin.com/orchestration-customer-tos?customer_id=1f45e58d-0420-4ad8-a790-413169bfab28&tos_policies_value=ffefb0cd-4f0a-4585-ad1c-f4ea76ba41b8 created_at: type: string format: date-time example: '2026-05-04T12:40:03Z' updated_at: type: string format: date-time example: '2026-05-04T12:47:50Z' last_status_updated_at: type: string format: date-time example: '2026-05-04T12:44:42.707598Z' rejection_reason: type: object nullable: true description: Populated when customer_status is REJECTED or ACTION_REQUIRED. Contains applicant-level and document-level rejection details. Null when no rejection exists. properties: applicant: type: object nullable: true description: Applicant-level rejection reason. properties: moderation_comment: type: string example: '' reject_labels: type: array items: type: string example: - EXPIRATION_DATE - PROBLEMATIC_APPLICANT_DATA documents: type: array description: Document-level rejection reasons. items: type: object properties: uri: type: string example: /SuElNZpi_approved_passport_sumsub.jpg category: type: string example: PROOF_OF_IDENTITY moderation_comment: type: string example: Your identity document has expired and can't be used for verification. Please upload a different identity document. reject_labels: type: array items: type: string example: - EXPIRATION_DATE example: null request_for_information: type: array description: List of open requests for additional information. Populated when customer_status is ACTION_REQUIRED. Same structure as customer.rfi webhook payload. items: type: object properties: scope: type: string enum: - CUSTOMER - ASSOCIATED_PARTY example: CUSTOMER section: type: string example: proof_of_identity categories: type: array items: type: object properties: document_type: type: string example: PASSPORT fields: type: array items: type: object properties: field_name: type: string example: files data_type: type: string enum: - URI - DATE - TEXT - ENUM example: URI status: type: string enum: - MISSING - EXPIRED - INVALID example: INVALID reason: type: string nullable: true example: Expired Identity document. A new document has been requested. options: type: array items: type: string example: [] example: [] AttachDocumentToAssociatedPartyInput: type: object required: - customer_id - associated_party_attachments properties: customer_id: type: string format: uuid example: 2d0a9df3-e1e5-4955-9759-ce0522e0ddc9 associated_party_attachments: type: array items: type: object required: - associated_party_id - proof_of_identity - proof_of_address properties: associated_party_id: type: string format: uuid example: 42daffd3-09a0-4d48-8e73-2680a953d0e1 proof_of_identity: $ref: '#/components/schemas/ProofOfIdentity' proof_of_address: $ref: '#/components/schemas/ProofOfAddressBusiness' V2OwnershipDocumentItem: type: object required: - files properties: type: type: string enum: - OWNERSHIP_INFORMATION - OWNERSHIP_CHART - PROOF_OF_SIGNATORY_AUTHORITY description: Ownership document type. example: OWNERSHIP_INFORMATION description: type: string description: Optional human-readable description of this specific document. example: Ownership information document files: type: array description: One or more file URIs obtained 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_0652746727639.pdf V2ForeignBranch: type: object required: - registration_country_code properties: registration_country_code: $ref: '#/components/schemas/CountryCode' name: type: string description: Branch name. Optional. example: Acme Corp UK Branch registration_number: type: string description: Branch registration number. Optional. example: BR000123 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 ProofOfAddressBusiness: type: object required: - type - country - files properties: type: type: string enum: - PASSPORT - NATIONAL_ID - DRIVERS_LICENSE - RESIDENCE_PERMIT - UTILITY_BILL - GOVERNMENT_LETTER - BANK_STATEMENT - COMPANY_DOC example: UTILITY_BILL country: $ref: '#/components/schemas/CountryCode' files: type: array items: type: object required: - uri properties: uri: type: string example: /AbAcQ4hn_0652746727638.pdf V2APBasicInfo: type: object required: - first_name - first_name_en - last_name - last_name_en - dob - email - phone - country_of_residence - primary_nationality - tax_info properties: first_name: type: string maxLength: 50 description: First name. example: John first_name_en: type: string description: English transliteration of first name. Required if name contains non-ASCII characters. example: John middle_name: type: string description: Middle name(s). Optional. example: Michael middle_name_en: type: string description: English transliteration of middle name. Optional. example: Michael last_name: type: string maxLength: 50 description: Last or family name. example: Doe last_name_en: type: string description: English transliteration of last name. Required if name contains non-ASCII characters. example: Doe dob: type: string format: date description: Date of birth in YYYY-MM-DD format. Party must be at least 18 years old. example: '1985-03-20' email: type: string format: email description: Personal email address. Must be unique across all associated parties in the same request. example: john.doe@acmecorp.com phone: type: string description: Personal phone number in E.164 format. example: '+14155551234' country_of_residence: $ref: '#/components/schemas/CountryCode' primary_nationality: $ref: '#/components/schemas/CountryCode' secondary_nationality: allOf: - $ref: '#/components/schemas/CountryCode' description: Secondary nationality for dual citizens. Optional. tax_info: type: array description: Tax and identifying documents for this individual. See all available individual tax ID document types at [Individual Tax ID documents](https://developer.fin.com/guides/compliance-and-regulatory/individual-tax-id-documents). items: $ref: '#/components/schemas/V2IndividualIdentifyingDocument' 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 parameters: PerPageParam: name: per_page in: query description: Number of items to return per page required: false schema: type: integer default: 10 minimum: 1 maximum: 512 CurrentPageParam: name: current_page in: query description: The page number to retrieve required: false schema: type: integer default: 1 minimum: 1 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