> ## Documentation Index > Fetch the complete documentation index at: https://developer.fin.com/llms.txt > Use this file to discover all available pages before exploring further. # Onboarding Business Customers > Complete guide to onboarding business clients with company details, financial profiles, addresses, and associated parties. Onboard business customers to enable cross-border payments and payouts through Fin.com's platform. This guide walks you through creating business customer profiles, uploading verification documents, and managing the compliance workflow. ## Prerequisites \* Required field Before you begin, ensure you have: * **API credentials**: Client ID and secret from the [**API Keys**](https://orchestration.fin.com/api-keys) section * **Access token**: Generated via [**POST /v1/oauth/token**](https://developer.fin.com/api-reference/authentication/issue-a-token) * **Reference data**: Familiarity with [**GET /v1/purposes**](https://developer.fin.com/api-reference/catalogue/list-account-purposes), [**GET /v1/source-of-funds**](https://developer.fin.com/api-reference/catalogue/list-source-of-funds), and [**GET /v1/source-of-wealth**](https://developer.fin.com/api-reference/catalogue/list-source-of-wealth) endpoints *** ## Onboarding Steps | **Step** | **Endpoint** | **Description** | | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- | | 1. Fetch Reference Data | [**GET /v1/purposes?type=BUSINESS**](https://developer.fin.com/api-reference/catalogue/list-account-purposes), [**GET /v1/source-of-funds?type=BUSINESS**](https://developer.fin.com/api-reference/catalogue/list-source-of-funds), [**GET /v1/source-of-wealth?type=BUSINESS**](https://developer.fin.com/api-reference/catalogue/list-source-of-wealth) | Retrieve valid integer IDs for purpose, source of funds, and source of wealth | | 2. Create Customer | [**POST /v2/customers/business**](https://developer.fin.com/api-reference/customers/create-business-customer-v2) | Submit company details, addresses, financial profile, and associated parties | | 3. Upload Documents | [**POST /v1/customers/upload**](https://developer.fin.com/api-reference/customers/upload-document) | Upload business and associated party documents | | 4. Attach Business Docs | [**POST /v2/customers/:customer-id/business/attach**](https://developer.fin.com/api-reference/customers/attach-documents-to-business-customer-v2) | Link formation, ownership, and supporting documents with TOS acceptance | | 5. Attach Party Docs | [**POST /v2/customers/:customer-id/associated-parties/individual/attach**](https://developer.fin.com/api-reference/customers/attach-document-to-associated-party-v2) | Link identity and address proofs for each associated party | | 6. Monitor Status | Webhooks: `customer.status`, `customer.rfi` | Track verification progress (`INCOMPLETE` → `REVIEWING` → `APPROVED`) | *** ## Request Body Structure ### Verification Type (Optional) Verification type determines how customer identity is validated. `STANDARD` uses traditional document verification (default). `RELIANCE` leverages third-party KYB data when enabled for your client. ```json theme={null} { "verification_type": "STANDARD" } ``` The `verification_type` field is optional and defaults to `STANDARD` if omitted. **RELIANCE verification** must be explicitly enabled for your client. If not available, you'll receive a `423` error with message: `"RELIANCE is not available for your client"` *** ### Industry Codes (Required) NAICS 2022 6-digit industry codes describing the business. Minimum 1 item required. ```json theme={null} { "industry_codes": ["541513", "541519"] } ``` | **Field** | **Type** | **Description** | | :---------------------------- | :-------- | :------------------------------------ | | `industry_codes`\* | string\[] | NAICS 2022 6-digit codes. Min 1 item. | Get the full list of industry codes [**here**](https://developer.fin.com/business-industry-codes). *** ### Basic Information (Required) Company details exactly as shown on incorporation documents. All fields must use only English (Latin) characters. | **Field** | **Type** | **Description** | | :-------------------------------------- | :-------- | :--------------------------------------------------------------------- | | `legal_name`\* | string | Official registered business name. Max 255 chars. | | `legal_name_en` | string | English translation of the legal name. Required if non-ASCII. | | `trade_name` | string | Common/operating name (DBA). | | `trade_name_en` | string | English translation of trade name. | | `description`\* | string | Business purpose and activities. Max 500 chars. | | `entity_type`\* | string | Legal entity type. See entity types table below. | | `email`\* | string | Business email address — **must be all lowercase**. | | `phone`\* | string | Business phone in E.164 format. | | `incorporation_date`\* | string | Date of incorporation in `YYYY-MM-DD` format. Cannot be a future date. | | `country_of_incorporation`\* | string | ISO Alpha-3 country code. | | `registration_number`\* | string | Business registration / company number. | | `legal_entity_identifier` | string | LEI code (20-character alphanumeric). | | `is_dao` | boolean | Whether the entity is a Decentralized Autonomous Organization. | | `tax_info`\* | object\[] | Tax/identifying documents. Min 1 item. See Tax Info below. | | `websites`\* | string\[] | Business website URLs. Min 1 item. | **Tax Info object (`tax_info[]`):** | **Field** | **Type** | **Description** | | :--------------------------- | :------- | :----------------------------------------- | | `country_code`\* | string | ISO Alpha-3 issuing country. | | `document_type`\* | string | Document type code, validated per country. | | `document_id`\* | string | The tax ID or registration number. | **Valid Entity Types:** | **Entity Type** | **Description** | | :-------------------- | :----------------------------- | | `LLC` | Limited Liability Company | | `PUBLICLY_LISTED` | Publicly traded company | | `CORPORATION` | Corporation (Inc, Corp) | | `SOLE_PROPRIETORSHIP` | Sole Proprietorship | | `PARTNERSHIP` | Partnership | | `TRUST` | Trust | | `PRIVATE_FOUNDATION` | Private Foundation | | `CHARITY` | Charitable Organization | | `NON_PROFIT` | Non-profit Organization | | `GOVERNMENT_AGENCY` | Government Agency or Authority | Email must be **all lowercase** or validation will fail: `contact@acmecorp.com` ✓ not `Contact@AcmeCorp.com` ✗ Example: ```json theme={null} { "basic_info": { "legal_name": "Acme Corp Ltd", "legal_name_en": "Acme Corp Ltd", "trade_name": "Acme", "trade_name_en": "Acme", "description": "International software and payments company providing cross-border B2B services", "entity_type": "CORPORATION", "email": "contact@acmecorp.com", "phone": "+14155552671", "incorporation_date": "2018-06-15", "country_of_incorporation": "USA", "registration_number": "12-3456789", "legal_entity_identifier": "549300EXAMPLE0001X23", "is_dao": false, "tax_info": [ { "country_code": "USA", "document_type": "EIN", "document_id": "12-3456789" } ], "websites": ["https://acmecorp.com", "https://acmepayments.com"] } } ``` *** ### Financial Profile (Required) Describes account purpose, transaction volumes, and fund sources. Use reference endpoints to fetch valid integer IDs. | **Field** | **Type** | **Description** | **How to Get Value** | | :---------------------------------------------- | :--------- | :------------------------------------------------------------------------------ | :--------------------------------------- | | `purpose_id`\* | integer | Account purpose. | `GET /v1/purposes?type=BUSINESS` | | `purpose_remarks` | string | Additional context for the account purpose. | User input | | `source_of_fund_ids`\* | integer\[] | Source(s) of business funds. Min 1. Order from largest to smallest contributor. | `GET /v1/source-of-funds?type=BUSINESS` | | `source_of_funds_description` | string | Additional context for source of funds. | User input | | `source_of_wealth_ids`\* | integer\[] | Source(s) of owner's wealth. Min 1. | `GET /v1/source-of-wealth?type=BUSINESS` | | `estimated_annual_revenue_usd`\* | integer | Estimated annual revenue in USD. Must be >= 0. | User estimate: `5000000` | | `expected_monthly_deposits_usd`\* | integer | Expected monthly inflow in USD. Must be >= 0. | User estimate: `400000` | | `expected_monthly_withdrawals_usd`\* | integer | Expected monthly outflow in USD. Must be >= 0. | User estimate: `350000` | | `expected_transaction_value_usd` | integer | Typical single transaction value in USD. | User estimate: `50000` | | `expected_monthly_transaction_count` | integer | Expected number of transactions per month. | User estimate: `20` | | `third_party_fund_usage` | boolean | Whether third-party funds will be processed. | User confirmation | **Third-Party Fund Usage**: Set to `true` **only if** this business will be processing, holding, or moving funds on behalf of other parties (e.g., payment processors, escrow services, MSBs). This triggers enhanced compliance review. For most normal businesses (SaaS, import/export, consulting), `third_party_fund_usage` should be `false`. `purpose_id`, `source_of_fund_ids`, and `source_of_wealth_ids` are integer foreign keys — not string enums. Always fetch valid IDs from the reference endpoints before submitting. Use `source_of_funds_description` (not `sof_remarks`) for additional context on source of funds. Enter all amounts in whole USD dollars — `50000` = \$50,000, not cents. Example: ```json theme={null} { "financial_profile": { "purpose_id": 3, "purpose_remarks": "Cross-border B2B payments for international suppliers", "source_of_fund_ids": [13, 16], "source_of_funds_description": "Revenue generated from software licensing and SaaS subscriptions", "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 } } ``` In this example: `purpose_id: 3` = Cross-border payments, `source_of_fund_ids: [13, 16]` = IDs from the source-of-funds catalogue, `estimated_annual_revenue_usd: 5000000` = \$5,000,000 USD (integer, not cents). *** ### Addresses (Required) Registered and operational addresses for the business. | **Field** | **Description** | | :------------------------------------------ | :----------------------------------------------------------------------- | | `is_incorporated_address_same`\* | `true` if physical and incorporated addresses are identical | | `incorporated_address`\* | Registered address from incorporation documents | | `physical_address` | Operating address — required only if different from incorporated address | **Address object:** | **Field** | **Type** | **Description** | | :------------------------------ | :------- | :----------------------------------------------------------------------------------------------------------------------------------- | | `street_line_1`\* | string | Primary street address. P.O. Boxes not accepted. | | `street_line_2` | string | Secondary address (suite, floor, etc.). | | `street_line_1_en` | string | English translation. Required if non-ASCII. | | `street_line_2_en` | string | English translation of street line 2. | | `city`\* | string | City name. Max 100 chars. | | `state`\* | string | State/province code from [**/v1/countries/subdivisions**](https://developer.fin.com/api-reference/catalogue/list-subdivision-codes). | | `subdivision_code`\* | string | State/province code from [**/v1/countries/subdivisions**](https://developer.fin.com/api-reference/catalogue/list-subdivision-codes). | | `postal_code`\* | string | ZIP or postal code. | | `country`\* | string | ISO Alpha-3 country code. | **Avoid P.O. Boxes** — Use verifiable street addresses for both incorporated and physical addresses. P.O. Boxes may be rejected during verification. Example: ```json theme={null} { "addresses": { "is_incorporated_address_same": false, "incorporated_address": { "street_line_1": "123 Main Street", "street_line_2": "Suite 400", "street_line_1_en": "123 Main Street", "street_line_2_en": "Suite 400", "city": "San Francisco", "state": "US-CA", "subdivision_code": "US-CA", "postal_code": "94105", "country": "USA" }, "physical_address": { "street_line_1": "789 Market Street", "street_line_2": "Floor 10", "city": "San Francisco", "state": "US-CA", "subdivision_code": "US-CA", "postal_code": "94103", "country": "USA" } } } ``` *** ### Associated Parties (Minimum 1 Required) Each business customer must have at least one associated party. At least one party must hold **both** `shareholder` and `ubo` roles simultaneously. A single person can hold both roles. Each associated party must include: **`basic_info`:** | **Field** | **Type** | **Description** | | :---------------------------------- | :-------- | :---------------------------------------------------------------- | | `first_name`\* | string | First name. Max 50 chars. | | `middle_name` | string | Middle name(s). | | `last_name`\* | string | Last/family name. Max 50 chars. | | `first_name_en` | string | English transliteration. Required if non-ASCII. | | `middle_name_en` | string | English transliteration of middle name. | | `last_name_en` | string | English transliteration. Required if non-ASCII. | | `dob`\* | string | Date of birth `YYYY-MM-DD`. Party must be at least 18 years old. | | `email`\* | string | Personal email. Must be unique across all parties in the request. | | `phone`\* | string | Phone in E.164 format. | | `country_of_residence`\* | string | ISO Alpha-3 country code. | | `primary_nationality`\* | string | ISO Alpha-3 country code. | | `secondary_nationality` | string | ISO Alpha-3 for dual citizens. | | `tax_info` | object\[] | Tax/ID documents. Same structure as business `tax_info`. | **`address`:** Residential address using the same Address object structure as business addresses. **`roles` (required):** | **Value** | **Description** | | :------------ | :------------------------------------------------------------------------- | | `shareholder` | Has a shareholding stake in the business | | `ubo` | Ultimate Beneficial Owner — exercises control or has significant ownership | At least one associated party must hold **both** `shareholder` and `ubo` roles. A single party can hold both: `"roles": ["shareholder", "ubo"]` **`ownership_info` (required when `roles` includes `ubo`):** | **Field** | **Type** | **Description** | | :--------------------------------------------- | :------- | :------------------------------------------------------- | | `designation`\* | string | Title or position. Max 100 chars. | | `percentage_of_ownership`\* | float | Ownership stake as a percentage (0–100). | | `relationship_establishment_date`\* | string | When relationship with the business began. `YYYY-MM-DD`. | | `has_control`\* | boolean | Whether this party has significant control. | | `is_signer`\* | boolean | Whether this party is an authorized signatory. | | `is_director`\* | boolean | Whether this party serves as a director. | **Ownership Validation**: Total ownership percentages across all associated parties must be > 0.01% and \< 100%. Individual parties may have a `percentage_of_ownership` of 0. Example: ```json theme={null} { "associated_parties": [ { "ref": "owner-001", "basic_info": { "first_name": "John", "middle_name": "Michael", "last_name": "Doe", "first_name_en": "John", "middle_name_en": "Michael", "last_name_en": "Doe", "dob": "1985-03-20", "email": "john.doe@acmecorp.com", "phone": "+14155551234", "country_of_residence": "USA", "primary_nationality": "USA", "secondary_nationality": "GBR", "tax_info": [ { "country_code": "USA", "document_type": "SSN", "document_id": "123-45-6789" } ] }, "address": { "street_line_1": "456 Oak Avenue", "street_line_2": "Apt 12B", "city": "San Francisco", "state": "US-CA", "subdivision_code": "US-CA", "postal_code": "94102", "country": "USA" }, "roles": ["shareholder", "ubo"], "ownership_info": { "designation": "CEO & Founder", "percentage_of_ownership": 60.0, "relationship_establishment_date": "2018-06-15", "has_control": true, "is_signer": true, "is_director": true } }, { "ref": "owner-002", "basic_info": { "first_name": "Jane", "last_name": "Doe", "dob": "1988-07-12", "email": "jane.doe@acmecorp.com", "phone": "+14155555678", "country_of_residence": "USA", "primary_nationality": "USA", "tax_info": [ { "country_code": "USA", "document_type": "SSN", "document_id": "987-65-4321" } ] }, "address": { "street_line_1": "321 Pine Street", "city": "San Francisco", "state": "US-CA", "subdivision_code": "US-CA", "postal_code": "94108", "country": "USA" }, "roles": ["ubo"], "ownership_info": { "designation": "CTO & Co-Founder", "percentage_of_ownership": 40.0, "relationship_establishment_date": "2018-06-15", "has_control": false, "is_signer": false, "is_director": false } } ] } ``` *** ### Holding Structure (Optional) For businesses with corporate shareholders or foreign branches. | **Field** | **Type** | **Description** | | :------------------------------------ | :-------- | :--------------------------------------------------------- | | `has_material_intermediary_ownership` | boolean | Whether any intermediary holds a material ownership stake. | | `corporate_shareholders` | object\[] | List of corporate shareholders. See below. | | `foreign_branches` | object\[] | List of foreign branch registrations. See below. | **Corporate Shareholder object:** | **Field** | **Type** | **Description** | | :--------------------------------------- | :------- | :------------------------------------------ | | `entity_name`\* | string | Corporate shareholder's legal name. | | `entity_name_en` | string | English translation. Required if non-ASCII. | | `registration_country_code`\* | string | ISO Alpha-3 country of registration. | | `ownership_percentage`\* | float | Ownership stake (0–100). | | `registration_number` | string | Entity registration number. | | `entity_type` | string | Type of entity. | | `incorporation_date` | string | Incorporation date `YYYY-MM-DD`. | **Foreign Branch object:** | **Field** | **Type** | **Description** | | :--------------------------------------- | :------- | :-------------------------------------------------- | | `registration_country_code`\* | string | ISO Alpha-3 country where the branch is registered. | | `name` | string | Branch name. | | `registration_number` | string | Branch registration number. | Example: ```json theme={null} { "holding_structure": { "has_material_intermediary_ownership": true, "corporate_shareholders": [ { "entity_name": "Acme Ventures LLC", "entity_name_en": "Acme Ventures LLC", "registration_country_code": "USA", "ownership_percentage": 0.0, "registration_number": "98-7654321", "entity_type": "LLC", "incorporation_date": "2015-03-01" } ], "foreign_branches": [ { "registration_country_code": "GBR", "name": "Acme Corp UK Branch", "registration_number": "BR000123" }, { "registration_country_code": "SGP", "name": "Acme Corp Singapore Branch", "registration_number": "T18FC0001A" } ] } } ``` *** ### Public Listings (Optional) For publicly traded companies. | **Field** | **Type** | **Description** | | :-------------- | :------- | :--------------------------------------------------------- | | `mic` | string | ISO 10383 Market Identifier Code. | | `isin` | string | International Securities Identification Number (12 chars). | | `ticker_symbol` | string | Stock exchange ticker. | Example: ```json theme={null} { "public_listings": [ { "mic": "XNAS", "isin": "US0231351067", "ticker_symbol": "ACME" } ] } ``` *** ### Compliance (Optional) For regulated businesses, MSBs, and high-risk industries. | **Field** | **Type** | **Description** | | :------------------------------------------------ | :------- | :---------------------------------------------------------- | | `operates_in_prohibited_countries` | boolean | Whether the business operates in OFAC/sanctioned countries. | | `additional_description_for_compliance_screening` | string | Free-text compliance notes for manual review. | | `risk_profile` | object | Risk classification details. See Risk Profile below. | | `regulated_activity` | object | Regulatory licensing details. See Regulated Activity below. | | `aml` | object | AML/CFT program details. See AML below. | **Risk Profile (`risk_profile`):** | **Field** | **Type** | **Description** | | :------------------------------------ | :-------- | :------------------------------------------------------------------ | | `high_risk_activities` | string\[] | High-risk activities the business engages in. | | `high_risk_activities_explanation` | string | Explanation of declared activities. Required if array is non-empty. | | `conducts_money_services` | boolean | Whether the business provides money services. | | `conducts_money_services_via_fin` | boolean | Whether money services are provided via financial intermediaries. | | `conducts_money_services_description` | string | Details about the money services offered. | Valid `high_risk_activities` values: `adult_entertainment`, `crypto_exchange`, `gambling`, `cannabis`, `weapons`, `money_services`, `cross_border_payments` **Regulated Activity (`regulated_activity`):** | **Field** | **Type** | **Description** | | :-------------------------------------------- | :------- | :----------------------------------------------- | | `description`\* | string | Description of the regulated activity. | | `primary_authority_country_code`\* | string | ISO Alpha-3 country of the regulatory authority. | | `primary_authority_name`\* | string | Name of the primary regulatory authority. | | `license_number`\* | string | Regulatory license or registration number. | **AML (`aml`):** | **Field** | **Type** | **Description** | | :----------------------------------------------------- | :-------- | :------------------------------------------------------------------ | | `supervisory_authority_name` | string | Name of the AML supervisory authority. | | `license_number` | string | AML license number. | | `has_appointed_mlro` | boolean | Whether a Money Laundering Reporting Officer has been appointed. | | `customer_risk_split` | object | Breakdown of customer risk percentages. Must sum to 100. See below. | | `prohibits_anonymous_or_fictitious_accounts` | boolean | Policy on anonymous or fictitious accounts. | | `prohibits_accounts_for_unlicensed_or_shell_customers` | boolean | Policy on unlicensed or shell customers. | | `customer_identity_verification` | object | CDD verification method and system. See Verification Method below. | | `pep_and_sanctions_screening` | object | PEP/sanctions screening method and system. | | `sanction_lists` | string\[] | Sanction lists screened against. | | `customer_risk_classification_from_due_diligence` | boolean | Whether risk classification is based on due diligence. | | `enhanced_due_diligence_process` | boolean | Whether enhanced due diligence is in place. | | `transaction_monitoring` | object | Transaction monitoring method and system. | | `procedures_for_transaction_monitoring` | boolean | Whether formal TM procedures are documented. | | `subject_to_ml_or_tf_investigation` | string | Current ML/TF investigation status. | | `subject_to_regulatory_enforcement_past_2_years` | string | Regulatory enforcement history (last 2 years). | | `confirms_no_service_to_sanctioned_countries` | boolean | Confirmation of no services to sanctioned jurisdictions. | | `client_funds_accessibility` | string | Client fund accessibility policy. | | `aml_ctf_audit_completed` | boolean | Whether an AML/CTF audit has been completed. | | `planned_audit_date` | string | Planned next audit date. `YYYY-MM-DD`. | **Customer Risk Split object (`customer_risk_split`):** Represents how your customer base is distributed across risk tiers. These percentages reflect what proportion of your customers you classify as low, medium, or high risk based on your own due diligence process. | **Field** | **Type** | **Description** | | :------------------------- | :------- | :------------------------------------------------- | | `low_risk`\* | integer | Percentage of customers classified as low risk. | | `medium_risk`\* | integer | Percentage of customers classified as medium risk. | | `high_risk`\* | integer | Percentage of customers classified as high risk. | Percentages must sum to 100. **Verification Method object** (used by `customer_identity_verification`, `pep_and_sanctions_screening`, `transaction_monitoring`): | **Field** | **Type** | **Description** | | :-------------------- | :------- | :-------------------------------------------------------------------------- | | `method`\* | enum | How the verification is performed. One of: `automated`, `manual`, `hybrid`. | | `system`\* | string | The vendor or system used. Required when `method` is `automated`. | | **`method` value** | **Description** | | :----------------- | :----------------------------------------------------- | | `automated` | Fully system-driven verification with no manual review | | `manual` | Human-reviewed verification process | | `hybrid` | Combination of automated screening and manual review | Example: ```json theme={null} { "compliance": { "operates_in_prohibited_countries": false, "additional_description_for_compliance_screening": "We do not operate in any OFAC-sanctioned jurisdictions. All transactions are screened against OFAC, EU, and UN sanction lists in real time.", "risk_profile": { "high_risk_activities": ["adult_entertainment"], "high_risk_activities_explanation": "We facilitate cross-border B2B payments, which are subject to enhanced due diligence procedures.", "conducts_money_services": true, "conducts_money_services_via_fin": false, "conducts_money_services_description": "Licensed money transmitter providing international wire transfer services to business clients." }, "regulated_activity": { "description": "Licensed money transmitter operating under FinCEN registration and state-level MSB licenses", "primary_authority_country_code": "USA", "primary_authority_name": "FinCEN", "license_number": "MSB-12345678" }, "aml": { "supervisory_authority_name": "FinCEN", "license_number": "MSB-12345678", "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" } } } ``` *** ### Metadata (Optional) Client-defined reference for internal tracking: ```json theme={null} { "meta_data": { "reference": "client-internal-ref-00123" } } ``` *** ## Document Upload & Attachment After creating the business customer, upload and attach verification documents. ### Step 1: Upload Documents Upload files using `multipart/form-data`: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/customers/upload \ --header 'Authorization: Bearer ' \ --header 'Content-Type: multipart/form-data' \ --form 'customer_id=3fa85f64-5717-4562-b3fc-2c963f66afa6' \ --form 'file1=@/path/to/certificate_of_incorporation.pdf' \ --form 'file2=@/path/to/shareholder_registry.pdf' ``` **Allowed file types**: PDF, JPG, JPEG, PNG **Response:** ```json theme={null} { "data": { "files": [ { "file1": "/AbAcQ4hn_0652746727637.pdf" }, { "file2": "/XyZ123mn_0652746727638.pdf" } ] } } ``` Save these URIs — you'll use them in the attachment requests. *** ### Step 2: Attach Business Documents Link formation, ownership, and supporting documents to the business customer: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v2/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/business/attach \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "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": "f11e77c6-8dc0-4d4b-a3f2-ed84c8ccfc69" }' ``` The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter returned when creating the customer. Providing this value signifies that the customer was shown the terms and accepted them. **Document Types:** | **Category** | **Type** | **Description** | | :--------------------- | :-------------------------------------- | :---------------------------------------------------------- | | `formation_documents` | `REGISTRATION_DOCUMENT` | Certificate of Incorporation / Registration Certificate | | `formation_documents` | `CONSTITUTIONAL_DOCUMENT` | Articles of Incorporation, Partnership Agreement | | `formation_documents` | `FORMATION_DOCUMENT` | Trust Agreement (for Trust entities) | | `formation_documents` | `EVIDENCE_OF_DIRECTORS_AND_CONTROLLERS` | Evidence of all directors and controllers (non-US entities) | | `formation_documents` | `PROOF_OF_TAX_IDENTIFICATION` | Tax registration certificate | | `ownership_documents` | `SHAREHOLDER_REGISTER` | Shareholder registry or cap table | | `ownership_documents` | `PROOF_OF_SIGNATORY_AUTHORITY` | Power of attorney or equivalent | | `ownership_documents` | `DIRECTORS_REGISTRY` | Registry of directors and officers | | `ownership_documents` | `OWNERSHIP_CHART` | Org chart showing ownership | | `ownership_documents` | `CERT_OF_INCUMBENCY` | Certificate of incumbency | | `supporting_documents` | `PROOF_OF_ADDRESS` | Utility bill, lease agreement, or bank statement | | `supporting_documents` | `PROOF_OF_SOURCE_OF_FUNDS` | Documentation of business fund origins | | `supporting_documents` | `PROOF_OF_SOURCE_OF_WEALTH` | Supporting docs proving wealth origin | | `supporting_documents` | `AML_COMFORT_LETTER` | AML compliance letter from legal counsel | | `supporting_documents` | `FLOW_OF_FUNDS` | One-page fund flow statement or diagram | | `supporting_documents` | `MARKETING_MATERIALS` | Website, invoices, or business plan | | `supporting_documents` | `TAX_EXEMPT_ENTITY_CONFIRMATION` | Tax exemption certificate | | `supporting_documents` | `OTHER` | Any other supporting document | *** ### Step 3: Attach Associated Party Documents Attach identity and address documents for each associated party: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v2/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/associated-parties/individual/attach \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "associated_party_attachments": [ { "associated_party_id": "5a42d32b-a23f-4b7f-9daf-1a9ceef0f0ea", "identifying_documents": [ { "type": "PASSPORT", "number": "A12345678", "country": "USA", "issue_date": "2020-01-15", "expiry_date": "2030-01-15", "files": [ { "uri": "/id_john_0652746727640.pdf" } ] }, { "type": "DRIVERS_LICENSE", "number": "DL987654321", "country": "USA", "issue_date": "2019-06-01", "expiry_date": "2029-06-01", "files": [ { "side": "FRONT", "uri": "/dl_front_john_0652746727641.pdf" }, { "side": "BACK", "uri": "/dl_back_john_0652746727642.pdf" } ] } ], "address_documents": [ { "type": "BANK_STATEMENT", "files": [ { "uri": "/bank_john_0652746727643.pdf" } ] } ], "supporting_documents": [] } ] }' ``` The `associated_party_id` is returned in the [**GET /v2/customers/:customer-id**](https://developer.fin.com/api-reference/customers/get-customer-details-v2) response after creating the business customer. For `NATIONAL_ID` and `DRIVERS_LICENSE`, you **must** provide both `FRONT` and `BACK` images using the `side` field. For `PASSPORT`, the `side` field is optional. **Identity Document Types:** | **Type** | **Description** | **Side Required** | | :----------------------- | :---------------------------------------------------- | :--------------------- | | `PASSPORT` | Passport | No (optional) | | `NATIONAL_ID` | National ID card | Yes (`FRONT` + `BACK`) | | `DRIVERS_LICENSE` | Driver's license | Yes (`FRONT` + `BACK`) | | `RESIDENCE_PERMIT` | Residence permit | No (optional) | | `PERMANENT_RESIDENCY_ID` | Permanent Residency / Green Card (USA residents only) | No (optional) | **Address Document Types:** | **Type** | **Description** | | :------------------ | :----------------------------------------- | | `UTILITY_BILL` | Recent utility bill (gas, electric, water) | | `BANK_STATEMENT` | Bank statement (within last 90 days) | | `GOVERNMENT_LETTER` | Official government correspondence | | `RESIDENCE_PERMIT` | Residence permit document | | `PASSPORT` | Passport showing address | | `NATIONAL_ID` | National ID showing address | | `DRIVERS_LICENSE` | Driver's license showing address | | `COMPANY_DOC` | Company document showing address | *** ## Customer Status & Webhooks After document submission, customers go through a verification workflow: **Status Lifecycle:** ```text theme={null} INCOMPLETE → ASSOCIATED_PARTIES_REMAINING → PROCESSING → REVIEWING → APPROVED ↕ IN_COMPLIANCE / REJECTED ↕ ACTION_REQUIRED ``` **Webhook Events:** | **Event** | **Triggered When** | **Resulting Status** | | :----------------- | :---------------------------------------------- | :------------------- | | `customer.created` | Customer record is created | `INCOMPLETE` | | `customer.status` | Verification status changes | Varies | | `customer.rfi` | Compliance team requests additional information | `ACTION_REQUIRED` | Subscribe to webhooks to automate your onboarding flow. See [**Verifying Webhooks**](https://developer.fin.com/guides/webhooks/verifying-webhooks) for setup. *** ## Error Response Examples **Email validation error (not lowercase):** ```json theme={null} { "status": 400, "message": "Validation failed", "data": { "basic_info.email": "Must be a valid email address" } } ``` **RELIANCE not enabled:** ```json theme={null} { "status": 423, "message": "RELIANCE is not available for your client" } ``` **Ownership percentage validation:** ```json theme={null} { "status": 400, "message": "Validation failed", "data": { "associated_parties": "Total ownership percentages must be > 0 and < 100" } } ``` *** ## What's Next? ### 1. Monitor Verification Status * Subscribe to `customer.created`, `customer.status`, and `customer.rfi` webhooks * Handle status transitions: `INCOMPLETE` → `PROCESSING` → `REVIEWING` → `APPROVED` * For `ACTION_REQUIRED` status (triggered by `customer.rfi`), respond with the requested documents * See [**Webhook Verification**](https://developer.fin.com/guides/webhooks/verifying-webhooks) for implementation details ### 2. Test Edge Cases * ✓ Email with uppercase characters * ✓ Ownership percentages totaling > 100% * ✓ Non-Latin characters in text fields * ✓ Missing required fields * ✓ RELIANCE verification when not enabled * ✓ P.O. Box addresses ### 3. Production Checklist * Implemented webhook handling for status updates * Added proper error handling for all failure scenarios * Client-side validation for email lowercase * Fetched and cached reference data (purposes, source-of-funds, source-of-wealth) * Implemented document upload UI/flow * Reviewed [**High-Risk Business Activities**](https://developer.fin.com/guides/compliance/high-risk-businesses) * Set up monitoring for failed verifications * Tested the complete workflow end-to-end ### 4. Create Beneficiaries Once your business customer is approved, you can create beneficiaries for payouts: * See [**Beneficiary Account Validation**](https://developer.fin.com/api-reference/beneficiaries/account-info-validation) * Review [**Beneficiary Relationships**](https://developer.fin.com/api-reference/beneficiaries/relationships) *** ## Common Pitfalls & Solutions | **Pitfall** | **Solution** | | :-------------------------------- | :----------------------------------------------------------------------------------------------- | | **Email validation fails** | Must be all lowercase before sending: `contact@acme.com` ✓ not `Contact@Acme.com` ✗ | | **RELIANCE 423 error** | RELIANCE must be enabled for your client. Contact support or use `STANDARD`. | | **Ownership percentage error** | Total across all parties must be \< 100%. Individual parties may have 0% ownership. | | **Non-Latin character rejection** | Use `legal_name_en`, `first_name_en`, `street_line_1_en` etc. for non-ASCII names and addresses. | | **P.O. Box address rejected** | Use verifiable street addresses. Avoid P.O. Boxes. | | **Phone format rejected** | Use E.164 format with country code: `+14155552671`, not `(415) 555-2671`. | | **Amount rejected** | Provide amount in USD as integer (not cents): `50000` for \$50,000. | | `purpose_id`**invalid** | Fetch valid IDs from `GET /v1/purposes?type=BUSINESS`. Do not use string enums. | | `source_of_fund_ids`**invalid** | Fetch valid IDs from `GET /v1/source-of-funds?type=BUSINESS`. | | `source_of_wealth_ids`**invalid** | Fetch valid IDs from `GET /v1/source-of-wealth?type=BUSINESS`. | *** *Last updated: April 2026 — Reflects V2 API (`POST /v2/customers/business`)* ## Prerequisites Before you begin, ensure you have: * **API credentials**: Client ID and secret from the [API Keys](https://orchestration.fin.com/api-keys) section * **Access token**: Generated via [POST /v1/oauth/token](/api-reference/authentication/issue-a-token) * **Catalogue data**: Familiarity with [/v1/industries](/api-reference/catalogue/list-industries), [/v1/purposes](/api-reference/catalogue/list-account-purposes), and [/v1/source-of-funds](/api-reference/catalogue/list-source-of-funds) endpoints ## Onboarding Steps | Step | Endpoint | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | 1. Fetch Catalogue Data | [GET /v1/industries](/api-reference/catalogue/list-industries), [GET /v1/purposes?type=BUSINESS](/api-reference/catalogue/list-account-purposes), [GET /v1/source-of-funds?type=BUSINESS](/api-reference/catalogue/list-source-of-funds) | Retrieve valid IDs for industries, purposes, and fund sources | | 2. Create Customer | [POST /v1/customers/business](/api-reference/customers/create-business-customer) | Submit company details, addresses, financial profile, and associated parties (UBOs) | | 3. Upload Documents | [POST /v1/customers/upload](/api-reference/customers/upload-document) | Upload business and associated party documents | | 4. Attach Business Docs | [POST /v1/customers/business/attach](/api-reference/customers/attach-documents-to-business-customer) | Link ownership structure, company details, and legal presence documents with TOS acceptance | | 5. Attach Party Docs | [POST /v1/customers/associated-parties/individual/attach](/api-reference/customers/attach-document-to-associated-party) | Link identity and address proofs for each associated party | | 6. Monitor Status | Webhooks: `customer.status` | Track verification progress (INCOMPLETE → REVIEWING → APPROVED) | *** ## Request Body Structure #### Verification Type (Optional) > **Verification type** determines how customer identity is validated. **STANDARD** uses traditional document verification (default). **RELIANCE** leverages third-party KYC data when enabled for your client. ```json theme={null} { "verification_type": "STANDARD" } ``` The `verification_type` field is optional and defaults to `STANDARD` if omitted. **RELIANCE verification** must be explicitly enabled for your client. If not available, you'll receive a 423 error with message: `"RELIANCE is not available for your client"` #### Basic Information (Required) > Company details exactly as shown on incorporation documents. **All fields must use only English (Latin) characters**. **Fields:** | Field | Type | Description | Example | | -------------------------- | -------------- | -------------------------------------------------- | ----------------------------- | | `business_name` | string | Full legal name from Certificate of Incorporation | `"Acme Corporation"` | | `business_trade_name` | string | Brand or DBA (Doing Business As) name *(optional)* | `"Acme"` | | `description` | string | Description of the company's business activities | `"Software development"` | | `entity_type` | enum | Legal entity structure (see table below) | `"LIMITED_LIABILITY_COMPANY"` | | `website` | string (uri) | Company website URL | `"https://acmecorp.com"` | | `email` | string (email) | Business email address — **must be all lowercase** | `"contact@acmecorp.com"` | | `incorporation_date` | string (date) | Date of incorporation in YYYY-MM-DD format | `"2020-01-15"` | | `phone` | string | Business phone number in E.164 format | `"+14155552671"` | | `country_of_incorporation` | string | ISO Alpha-3 country code | `"USA"` | | `registration_number` | string | Business registration number | `"87-1234567"` | | `tax_id` | string | Tax identification number (EIN for USA businesses) | `"12-3456789"` | Email must be **all lowercase** or validation will fail. Convert to lowercase before sending: `contact@acmecorp.com` ✓ not `Contact@AcmeCorp.com` ✗ **Valid Entity Types:** | Entity Type | Description | | ---------------------------- | --------------------------------- | | `LIMITED_LIABILITY_COMPANY` | Limited Liability Company (LLC) | | `PRIVATE_LIMITED` | Private Limited Company (Pte Ltd) | | `PUBLICLY_LISTED_COMPANY` | Publicly traded corporation | | `CORPORATION` | Corporation (Inc, Corp) | | `SOLE_PROPRIETOR` | Sole proprietorship | | `PARTNERSHIP` | Partnership | | `TRUST` | Trust | | `PRIVATE_FOUNDATION` | Private foundation | | `CHARITY` | Charitable organization | | `NONPROFIT_ORGANIZATION` | Non-profit organization | | `PUBLIC_AGENCY_OR_AUTHORITY` | Government agency or authority | #### Financial Profile (Required) > Describes business purpose, industry, transaction volume, and fund sources. Use catalogue endpoints to fetch valid IDs. **Fields:** | Field | Type | Description | How to Get Value | | ------------------------ | ------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | `purpose_id` | integer | Account purpose | [GET /v1/purposes?type=BUSINESS](/api-reference/catalogue/list-account-purposes) | | `other_purpose` | string | Custom purpose (only when purpose\_id = "Other") | User input | | `business_industry_id` | integer | Industry classification | [GET /v1/industries](/api-reference/catalogue/list-industries) | | `monthly_volume` | integer | Expected monthly volume in **USD** (not cents). Accepts `0`. | User estimate: `50000` | | `source_of_fund_id` | integer | Source of funds | [GET /v1/source-of-funds?type=BUSINESS](/api-reference/catalogue/list-source-of-funds) | | `third_party_fund_usage` | boolean | Processing funds on behalf of others | User confirmation | **Third-Party Fund Usage**: Set to `true` **only if** this business will be processing, holding, or moving funds on behalf of other parties (e.g., payment processors, escrow services, money services). This triggers enhanced compliance review. See [High-Risk Business Activities](/guides/compliance/high-risk-businesses) for details. For most normal businesses (SaaS companies, import/export, consulting agencies), `third_party_fund_usage` should be `false`. Only MSBs, payment facilitators, and similar businesses should set this to `true`. **Example:** ```json theme={null} { "financial_profile": { "purpose_id": 10, "business_industry_id": 1, "monthly_volume": 50000, "source_of_fund_id": 13, "third_party_fund_usage": false } } ``` In this example: `purpose_id: 10` = Cross-border payouts, `business_industry_id: 1` = Technology, `monthly_volume: 50000` = \$50,000 USD (integer, not cents), `source_of_fund_id: 13` = Sales revenue. #### Addresses (Required) > Registered and operational addresses for the business. **Fields:** | Field | Required | Description | | ------------------------------ | ----------- | ------------------------------------------------------------------------ | | `is_incorporated_address_same` | Yes | `true` if physical and incorporated addresses are identical | | `incorporated_address` | Yes | Registered address from incorporation papers | | `physical_address` | Conditional | Operating address (required only if different from incorporated address) | **Address Object:** | Field | Type | Description | Example | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | | `street` | string | Street address | `"123 Market Street Suite 400"` | | `city` | string | City name | `"San Francisco"` | | `state` | string | State/province code from [/v1/countries/](/api-reference/catalogue/list-subdivision-codes-—-iso-3166-1-alpha-2){country_code}[/subdivisions](/api-reference/catalogue/list-subdivision-codes-—-iso-3166-1-alpha-2) | `"US-CA"` | | `postal_code` | string | Postal or ZIP code | `"94103"` | | `country` | string | ISO Alpha-3 country code | `"USA"` | **Avoid P.O. Boxes** — Use verifiable street addresses for both incorporated and physical addresses. P.O. Boxes may be rejected during verification. **Example:** ```json theme={null} { "addresses": { "is_incorporated_address_same": false, "incorporated_address": { "street": "10 Anson Road #26-04 International Plaza", "city": "Singapore", "state": "SG-01", "postal_code": "079903", "country": "SGP" }, "physical_address": { "street": "456 Market Street Floor 3", "city": "San Francisco", "state": "US-CA", "postal_code": "94103", "country": "USA" } } } ``` #### Associated Parties (Minimum 1 Required) > **UBO (Ultimate Beneficial Owner)**: Individuals with ≥10% ownership OR significant control over the entity. All must be disclosed for regulatory compliance. Each associated party must include: **basic\_info (all fields required):** | Field | Description | | ---------------------- | ---------------------------- | | `first_name` | First name | | `last_name` | Last name | | `dob` | Date of birth (YYYY-MM-DD) | | `email` | Email address | | `phone` | Phone number in E.164 format | | `country_of_residence` | ISO Alpha-3 country code | | `nationality` | ISO Alpha-3 country code | | `tin` | Tax Identification Number | **address (all fields required):** Residential address with same structure as business address (`street`, `city`, `state`, `postal_code`, `country`). **ownership\_info (all fields required):** | Field | Type | Description | | --------------------------------- | ------------- | ---------------------------------------------- | | `designation` | string | Role or position (e.g., CEO, Director, UBO) | | `percentage_of_ownership` | number | Percentage of ownership in the business | | `relationship_establishment_date` | string (date) | When relationship was established (YYYY-MM-DD) | **Ownership Validation**: Total ownership percentages across all associated parties must be **\< 100%**. Individual parties may have a `percentage_of_ownership` of 0. **Example:** ```json theme={null} { "associated_parties": [ { "basic_info": { "first_name": "John", "last_name": "Smith", "dob": "1985-03-20", "email": "john.smith@acmecorp.com", "phone": "+14155551234", "country_of_residence": "USA", "nationality": "USA", "tin": "123-45-6789" }, "address": { "street": "456 Oak Avenue", "city": "San Francisco", "state": "US-CA", "postal_code": "94102", "country": "USA" }, "ownership_info": { "designation": "CEO", "percentage_of_ownership": 75.0, "relationship_establishment_date": "2020-01-15" } }, { "basic_info": { "first_name": "Jane", "last_name": "Doe", "dob": "1988-07-12", "email": "jane.doe@acmecorp.com", "phone": "+14155555678", "country_of_residence": "USA", "nationality": "USA", "tin": "987-65-4321" }, "address": { "street": "789 Pine Street Apt 12", "city": "San Francisco", "state": "US-CA", "postal_code": "94109", "country": "USA" }, "ownership_info": { "designation": "CFO", "percentage_of_ownership": 25.0, "relationship_establishment_date": "2020-01-15" } } ] } ``` #### Metadata (Optional) Custom key-value pairs for internal tracking: ```json theme={null} { "meta_data": { "reference": "REF-20250123-ACME", "internal_notes": "Enterprise tier customer", "sales_rep": "john.sales@yourcompany.com" } } ``` ### Document Upload & Attachment After creating the business customer, you must upload and attach verification documents. #### Step 1: Upload Documents Upload files using multipart/form-data: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/customers/upload \ --header 'Authorization: Bearer ' \ --header 'Content-Type: multipart/form-data' \ --form 'customer_id=2d0a9df3-e1e5-4955-9759-ce0522e0ddc9' \ --form 'file1=@/path/to/certificate_of_incorporation.pdf' \ --form 'file2=@/path/to/shareholder_registry.pdf' ``` **Allowed file types**: PDF, JPG, JPEG, PNG **Response:** ```json theme={null} { "data": { "files": [ { "file1": "/AbAcQ4hn_0652746727637.pdf" }, { "file2": "/XyZ123mn_0652746727638.pdf" } ] } } ``` Save these URIs—you'll use them in the attachment requests. #### Step 2: Attach Business Documents Link documents to the business customer: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/customers/business/attach \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "customer_id": "2d0a9df3-e1e5-4955-9759-ce0522e0ddc9", "ownership_structure": [ { "type": "SHAREHOLDER_REGISTRY", "files": [{"uri": "/XyZ123mn_0652746727638.pdf"}] } ], "company_details": [ { "type": "CERT_OF_INCORPORATION", "files": [{"uri": "/AbAcQ4hn_0652746727637.pdf"}] } ], "legal_presence": [ { "type": "PROOF_OF_ADDRESS", "files": [{"uri": "/PoAdef45_0652746727639.pdf"}] } ], "tos_policies_value": "f11e77c6-8dc0-4d4b-a3f2-ed84c8ccfc69" }' ``` The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter returned when creating the customer. Providing this value signifies that the customer was shown the terms and accepted them. **Document Types:** | Category | Type | Description | | --------------------- | --------------------------- | ------------------------------------------------ | | `ownership_structure` | `SHAREHOLDER_REGISTRY` | Shareholder registry or cap table | | `company_details` | `CERT_OF_INCORPORATION` | Certificate of incorporation | | `company_details` | `MEMORANDUM_OF_ASSOCIATION` | Memorandum of association | | `legal_presence` | `PROOF_OF_ADDRESS` | Utility bill, lease agreement, or bank statement | #### Step 3: Attach Associated Party Documents Upload identity and address proofs for each UBO: ```bash theme={null} curl --request POST \ --url https://sandbox.api.fin.com/v1/customers/associated-parties/individual/attach \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "customer_id": "2d0a9df3-e1e5-4955-9759-ce0522e0ddc9", "associated_party_attachments": [ { "associated_party_id": "a7c3b4e2-d8f1-4a5c-9e7d-2f6b8c3a1e9f", "proof_of_identity": { "type": "NATIONAL_ID", "number": "A12345678", "country": "USA", "issue_date": "2020-01-15", "expiry_date": "2030-01-15", "files": [ {"side": "FRONT", "uri": "/id_front_john_0652746727640.pdf"}, {"side": "BACK", "uri": "/id_back_john_0652746727641.pdf"} ] }, "proof_of_address": { "type": "UTILITY_BILL", "country": "USA", "files": [ {"uri": "/utility_john_0652746727642.pdf"} ] } } ] }' ``` The `associated_party_id` is returned in the [GET /v1/customers/:customer\_id](/api-reference/customers/get-customer-details) response after creating the business customer. For `NATIONAL_ID` and `DRIVERS_LICENSE`, you **must** provide both `FRONT` and `BACK` images using the `side` field. For `PASSPORT`, the `side` field is optional. **Identity Document Types:** | Type | Description | Side Required | | ----------------- | ---------------- | ------------------ | | `PASSPORT` | Passport | No (optional) | | `NATIONAL_ID` | National ID card | Yes (FRONT + BACK) | | `DRIVERS_LICENSE` | Driver's license | Yes (FRONT + BACK) | **Address Proof Types:** | Type | Description | | ------------------- | ------------------------------------------ | | `UTILITY_BILL` | Recent utility bill (gas, electric, water) | | `BANK_STATEMENT` | Bank statement (within last 3 months) | | `GOVERNMENT_LETTER` | Official government correspondence | | `RESIDENCE_PERMIT` | Residence permit document | | `PASSPORT` | Passport showing address | | `NATIONAL_ID` | National ID showing address | | `DRIVERS_LICENSE` | Driver's license showing address | | `COMPANY_DOC` | Company document showing address | ### Customer Status & Webhooks After document submission, customers go through a verification workflow: **Status Lifecycle:** ```text theme={null} INCOMPLETE → REVIEWING → APPROVED ↓ ON_HOLD / REJECTED ``` **Special Status:** * `ASSOCIATED_PARTIES_REMAINING` — Some party documents still needed **Webhook Events:** * `customer.created` — Fired when customer is created * `customer.status` — Fired when status changes Subscribe to webhooks to automate your onboarding flow. See [Verifying Webhooks](/guides/webhooks/verifying-webhooks) for setup. ### Error Response Examples **Email validation error (not lowercase):** ```json theme={null} { "message": "Validation failed", "errors": { "basic_info.email": ["Email must be all lowercase"] } } ``` **RELIANCE not enabled:** ```json theme={null} { "message": "RELIANCE is not available for your client" } ``` **Ownership percentage validation:** ```json theme={null} { "message": "Validation failed", "errors": { "associated_parties": ["Total ownership percentages must be > 0 and < 100"] } } ``` *** ## What's Next? You've successfully created a business customer. Here's what to do next: ### 1. Monitor Verification Status Listen for webhook events to track verification progress: * Subscribe to `customer.created` and `customer.status` webhooks * Handle status transitions: `INCOMPLETE` → `REVIEWING` → `APPROVED` * For `ON_HOLD` statuses, respond to RFIs (Requests for Information) via email or Slack with additional documents * See [Webhook Verification](/guides/webhooks/verifying-webhooks) for implementation details ### 2. Test Edge Cases Validate your integration handles common errors: * ✓ Email with uppercase characters * ✓ Ownership percentages totaling > 100% * ✓ Non-Latin characters in text fields * ✓ Missing required fields * ✓ RELIANCE verification when not enabled * ✓ P.O. Box addresses ### 3. Production Checklist Before going live, ensure you have: * Implemented webhook handling for status updates * Added proper error handling for all failure scenarios * Client-side validation for email lowercase * Fetched and cached catalogue data (industries, purposes, source-of-funds) * Implemented document upload UI/flow * Reviewed [High-Risk Business Activities](/guides/compliance/high-risk-businesses) * Set up monitoring for failed verifications * Tested the complete workflow end-to-end ### 4. Create Beneficiaries Once your business customer is approved, you can create beneficiaries for payouts: * See [Beneficiary Account Validation](/api-reference/beneficiaries/account-info-validation) * Review [Beneficiary Relationships](/api-reference/beneficiaries/relationships) *** ## Common Pitfalls & Solutions | Pitfall | Solution | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Email validation fails** | Ensure email is **all lowercase** before sending: `contact@acme.com` ✓ not `Contact@Acme.com` ✗ | | **RELIANCE 423 error** | RELIANCE verification must be enabled for your client. Contact support or use `STANDARD` verification type. | | **Ownership percentage error** | Total ownership across all parties must be **\< 100%**. Individual parties may have 0% ownership. Check calculations before submitting. | | **Non-Latin character rejection** | All text fields accept only English (Latin) characters. Transliterate or romanize names (e.g., `José` → `Jose`). | | **P.O. Box address rejected** | Use verifiable street addresses for both incorporated and physical addresses. Avoid P.O. Boxes. | | **State code validation fails** | Use state codes from [/v1/countries/subdivisions](/api-reference/catalogue/list-subdivision-codes-—-iso-3166-1-alpha-2). Format: `US-CA`, not `CA`. | | **Phone format rejected** | Use E.164 format with country code: `+14155552671`, not `(415) 555-2671`. | | **Monthly volume rejected** | Provide amount in USD as integer (not cents): `50000` for \$50,000, not `5000000`. |