Skip to main content

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.

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 fieldBefore you begin, ensure you have:

​
Onboarding Steps

StepEndpointDescription
1. Fetch Reference DataGET /v1/purposes?type=BUSINESS, GET /v1/source-of-funds?type=BUSINESS, GET /v1/source-of-wealth?type=BUSINESSRetrieve valid integer IDs for purpose, source of funds, and source of wealth
2. Create CustomerPOST /v2/customers/businessSubmit company details, addresses, financial profile, and associated parties
3. Upload DocumentsPOST /v1/customers/uploadUpload business and associated party documents
4. Attach Business DocsPOST /v2/customers/:customer-id/business/attachLink formation, ownership, and supporting documents with TOS acceptance
5. Attach Party DocsPOST /v2/customers/:customer-id/associated-parties/individual/attachLink identity and address proofs for each associated party
6. Monitor StatusWebhooks: customer.status, customer.rfiTrack 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.
{
  "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.
{
  "industry_codes": ["541513", "541519"]
}
FieldTypeDescription
industry_codes*string[]NAICS 2022 6-digit codes. Min 1 item.
Get the full list of industry codes here.

​
Basic Information (Required)

Company details exactly as shown on incorporation documents. All fields must use only English (Latin) characters.
FieldTypeDescription
legal_name*stringOfficial registered business name. Max 255 chars.
legal_name_enstringEnglish translation of the legal name. Required if non-ASCII.
trade_namestringCommon/operating name (DBA).
trade_name_enstringEnglish translation of trade name.
description*stringBusiness purpose and activities. Max 500 chars.
entity_type*stringLegal entity type. See entity types table below.
email*stringBusiness email address — must be all lowercase.
phone*stringBusiness phone in E.164 format.
incorporation_date*stringDate of incorporation in YYYY-MM-DD format. Cannot be a future date.
country_of_incorporation*stringISO Alpha-3 country code.
registration_number*stringBusiness registration / company number.
legal_entity_identifierstringLEI code (20-character alphanumeric).
is_daobooleanWhether 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[]):
FieldTypeDescription
country_code*stringISO Alpha-3 issuing country.
document_type*stringDocument type code, validated per country.
document_id*stringThe tax ID or registration number.
Valid Entity Types:
Entity TypeDescription
LLCLimited Liability Company
PUBLICLY_LISTEDPublicly traded company
CORPORATIONCorporation (Inc, Corp)
SOLE_PROPRIETORSHIPSole Proprietorship
PARTNERSHIPPartnership
TRUSTTrust
PRIVATE_FOUNDATIONPrivate Foundation
CHARITYCharitable Organization
NON_PROFITNon-profit Organization
GOVERNMENT_AGENCYGovernment Agency or Authority
Email must be all lowercase or validation will fail: contact@acmecorp.com ✓ not Contact@AcmeCorp.com ✗
Example:
{
  "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.
FieldTypeDescriptionHow to Get Value
purpose_id*integerAccount purpose.GET /v1/purposes?type=BUSINESS
purpose_remarksstringAdditional 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_descriptionstringAdditional 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*integerEstimated annual revenue in USD. Must be >= 0.User estimate: 5000000
expected_monthly_deposits_usd*integerExpected monthly inflow in USD. Must be >= 0.User estimate: 400000
expected_monthly_withdrawals_usd*integerExpected monthly outflow in USD. Must be >= 0.User estimate: 350000
expected_transaction_value_usdintegerTypical single transaction value in USD.User estimate: 50000
expected_monthly_transaction_countintegerExpected number of transactions per month.User estimate: 20
third_party_fund_usagebooleanWhether 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:
{
  "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.
FieldDescription
is_incorporated_address_same*true if physical and incorporated addresses are identical
incorporated_address*Registered address from incorporation documents
physical_addressOperating address — required only if different from incorporated address
Address object:
FieldTypeDescription
street_line_1*stringPrimary street address. P.O. Boxes not accepted.
street_line_2stringSecondary address (suite, floor, etc.).
street_line_1_enstringEnglish translation. Required if non-ASCII.
street_line_2_enstringEnglish translation of street line 2.
city*stringCity name. Max 100 chars.
state*stringState/province code from /v1/countries/subdivisions.
subdivision_code*stringState/province code from /v1/countries/subdivisions.
postal_code*stringZIP or postal code.
country*stringISO 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:
{
  "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:
FieldTypeDescription
first_name*stringFirst name. Max 50 chars.
middle_namestringMiddle name(s).
last_name*stringLast/family name. Max 50 chars.
first_name_enstringEnglish transliteration. Required if non-ASCII.
middle_name_enstringEnglish transliteration of middle name.
last_name_enstringEnglish transliteration. Required if non-ASCII.
dob*stringDate of birth YYYY-MM-DD. Party must be at least 18 years old.
email*stringPersonal email. Must be unique across all parties in the request.
phone*stringPhone in E.164 format.
country_of_residence*stringISO Alpha-3 country code.
primary_nationality*stringISO Alpha-3 country code.
secondary_nationalitystringISO Alpha-3 for dual citizens.
tax_infoobject[]Tax/ID documents. Same structure as business tax_info.
address: Residential address using the same Address object structure as business addresses.roles (required):
ValueDescription
shareholderHas a shareholding stake in the business
uboUltimate 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):
FieldTypeDescription
designation*stringTitle or position. Max 100 chars.
percentage_of_ownership*floatOwnership stake as a percentage (0–100).
relationship_establishment_date*stringWhen relationship with the business began. YYYY-MM-DD.
has_control*booleanWhether this party has significant control.
is_signer*booleanWhether this party is an authorized signatory.
is_director*booleanWhether 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:
{
  "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.
FieldTypeDescription
has_material_intermediary_ownershipbooleanWhether any intermediary holds a material ownership stake.
corporate_shareholdersobject[]List of corporate shareholders. See below.
foreign_branchesobject[]List of foreign branch registrations. See below.
Corporate Shareholder object:
FieldTypeDescription
entity_name*stringCorporate shareholder’s legal name.
entity_name_enstringEnglish translation. Required if non-ASCII.
registration_country_code*stringISO Alpha-3 country of registration.
ownership_percentage*floatOwnership stake (0–100).
registration_numberstringEntity registration number.
entity_typestringType of entity.
incorporation_datestringIncorporation date YYYY-MM-DD.
Foreign Branch object:
FieldTypeDescription
registration_country_code*stringISO Alpha-3 country where the branch is registered.
namestringBranch name.
registration_numberstringBranch registration number.
Example:
{
  "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.
FieldTypeDescription
micstringISO 10383 Market Identifier Code.
isinstringInternational Securities Identification Number (12 chars).
ticker_symbolstringStock exchange ticker.
Example:
{
  "public_listings": [
    {
      "mic": "XNAS",
      "isin": "US0231351067",
      "ticker_symbol": "ACME"
    }
  ]
}

​
Compliance (Optional)

For regulated businesses, MSBs, and high-risk industries.
FieldTypeDescription
operates_in_prohibited_countriesbooleanWhether the business operates in OFAC/sanctioned countries.
additional_description_for_compliance_screeningstringFree-text compliance notes for manual review.
risk_profileobjectRisk classification details. See Risk Profile below.
regulated_activityobjectRegulatory licensing details. See Regulated Activity below.
amlobjectAML/CFT program details. See AML below.
Risk Profile (risk_profile):
FieldTypeDescription
high_risk_activitiesstring[]High-risk activities the business engages in.
high_risk_activities_explanationstringExplanation of declared activities. Required if array is non-empty.
conducts_money_servicesbooleanWhether the business provides money services.
conducts_money_services_via_finbooleanWhether money services are provided via financial intermediaries.
conducts_money_services_descriptionstringDetails about the money services offered.
Valid high_risk_activities values: adult_entertainment, crypto_exchange, gambling, cannabis, weapons, money_services, cross_border_paymentsRegulated Activity (regulated_activity):
FieldTypeDescription
description*stringDescription of the regulated activity.
primary_authority_country_code*stringISO Alpha-3 country of the regulatory authority.
primary_authority_name*stringName of the primary regulatory authority.
license_number*stringRegulatory license or registration number.
AML (aml):
FieldTypeDescription
supervisory_authority_namestringName of the AML supervisory authority.
license_numberstringAML license number.
has_appointed_mlrobooleanWhether a Money Laundering Reporting Officer has been appointed.
customer_risk_splitobjectBreakdown of customer risk percentages. Must sum to 100. See below.
prohibits_anonymous_or_fictitious_accountsbooleanPolicy on anonymous or fictitious accounts.
prohibits_accounts_for_unlicensed_or_shell_customersbooleanPolicy on unlicensed or shell customers.
customer_identity_verificationobjectCDD verification method and system. See Verification Method below.
pep_and_sanctions_screeningobjectPEP/sanctions screening method and system.
sanction_listsstring[]Sanction lists screened against.
customer_risk_classification_from_due_diligencebooleanWhether risk classification is based on due diligence.
enhanced_due_diligence_processbooleanWhether enhanced due diligence is in place.
transaction_monitoringobjectTransaction monitoring method and system.
procedures_for_transaction_monitoringbooleanWhether formal TM procedures are documented.
subject_to_ml_or_tf_investigationstringCurrent ML/TF investigation status.
subject_to_regulatory_enforcement_past_2_yearsstringRegulatory enforcement history (last 2 years).
confirms_no_service_to_sanctioned_countriesbooleanConfirmation of no services to sanctioned jurisdictions.
client_funds_accessibilitystringClient fund accessibility policy.
aml_ctf_audit_completedbooleanWhether an AML/CTF audit has been completed.
planned_audit_datestringPlanned 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.
FieldTypeDescription
low_risk*integerPercentage of customers classified as low risk.
medium_risk*integerPercentage of customers classified as medium risk.
high_risk*integerPercentage 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):
FieldTypeDescription
method*enumHow the verification is performed. One of: automated, manual, hybrid.
system*stringThe vendor or system used. Required when method is automated.
method valueDescription
automatedFully system-driven verification with no manual review
manualHuman-reviewed verification process
hybridCombination of automated screening and manual review
Example:
{
  "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:
{
  "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:
curl --request POST \
  --url https://sandbox.api.fin.com/v1/customers/upload \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --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, PNGResponse:
{
  "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:
curl --request POST \
  --url https://sandbox.api.fin.com/v2/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/business/attach \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --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:
CategoryTypeDescription
formation_documentsREGISTRATION_DOCUMENTCertificate of Incorporation / Registration Certificate
formation_documentsCONSTITUTIONAL_DOCUMENTArticles of Incorporation, Partnership Agreement
formation_documentsFORMATION_DOCUMENTTrust Agreement (for Trust entities)
formation_documentsEVIDENCE_OF_DIRECTORS_AND_CONTROLLERSEvidence of all directors and controllers (non-US entities)
formation_documentsPROOF_OF_TAX_IDENTIFICATIONTax registration certificate
ownership_documentsSHAREHOLDER_REGISTERShareholder registry or cap table
ownership_documentsPROOF_OF_SIGNATORY_AUTHORITYPower of attorney or equivalent
ownership_documentsDIRECTORS_REGISTRYRegistry of directors and officers
ownership_documentsOWNERSHIP_CHARTOrg chart showing ownership
ownership_documentsCERT_OF_INCUMBENCYCertificate of incumbency
supporting_documentsPROOF_OF_ADDRESSUtility bill, lease agreement, or bank statement
supporting_documentsPROOF_OF_SOURCE_OF_FUNDSDocumentation of business fund origins
supporting_documentsPROOF_OF_SOURCE_OF_WEALTHSupporting docs proving wealth origin
supporting_documentsAML_COMFORT_LETTERAML compliance letter from legal counsel
supporting_documentsFLOW_OF_FUNDSOne-page fund flow statement or diagram
supporting_documentsMARKETING_MATERIALSWebsite, invoices, or business plan
supporting_documentsTAX_EXEMPT_ENTITY_CONFIRMATIONTax exemption certificate
supporting_documentsOTHERAny other supporting document

​
Step 3: Attach Associated Party Documents

Attach identity and address documents for each associated party:
curl --request POST \
  --url https://sandbox.api.fin.com/v2/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/associated-parties/individual/attach \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --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 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:
TypeDescriptionSide Required
PASSPORTPassportNo (optional)
NATIONAL_IDNational ID cardYes (FRONT + BACK)
DRIVERS_LICENSEDriver’s licenseYes (FRONT + BACK)
RESIDENCE_PERMITResidence permitNo (optional)
PERMANENT_RESIDENCY_IDPermanent Residency / Green Card (USA residents only)No (optional)
Address Document Types:
TypeDescription
UTILITY_BILLRecent utility bill (gas, electric, water)
BANK_STATEMENTBank statement (within last 90 days)
GOVERNMENT_LETTEROfficial government correspondence
RESIDENCE_PERMITResidence permit document
PASSPORTPassport showing address
NATIONAL_IDNational ID showing address
DRIVERS_LICENSEDriver’s license showing address
COMPANY_DOCCompany document showing address

​
Customer Status & Webhooks

After document submission, customers go through a verification workflow:Status Lifecycle:
INCOMPLETE → ASSOCIATED_PARTIES_REMAINING → PROCESSING → REVIEWING → APPROVED
                                                                     ↕
                                                              IN_COMPLIANCE / REJECTED
                                                                     ↕
                                                              ACTION_REQUIRED
Webhook Events:
EventTriggered WhenResulting Status
customer.createdCustomer record is createdINCOMPLETE
customer.statusVerification status changesVaries
customer.rfiCompliance team requests additional informationACTION_REQUIRED
Subscribe to webhooks to automate your onboarding flow. See Verifying Webhooks for setup.

​
Error Response Examples

Email validation error (not lowercase):
{
  "status": 400,
  "message": "Validation failed",
  "data": {
    "basic_info.email": "Must be a valid email address"
  }
}
RELIANCE not enabled:
{
  "status": 423,
  "message": "RELIANCE is not available for your client"
}
Ownership percentage validation:
{
  "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 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
  • 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:

​
Common Pitfalls & Solutions

PitfallSolution
Email validation failsMust be all lowercase before sending: contact@acme.com ✓ not Contact@Acme.com ✗
RELIANCE 423 errorRELIANCE must be enabled for your client. Contact support or use STANDARD.
Ownership percentage errorTotal across all parties must be < 100%. Individual parties may have 0% ownership.
Non-Latin character rejectionUse legal_name_en, first_name_en, street_line_1_en etc. for non-ASCII names and addresses.
P.O. Box address rejectedUse verifiable street addresses. Avoid P.O. Boxes.
Phone format rejectedUse E.164 format with country code: +14155552671, not (415) 555-2671.
Amount rejectedProvide amount in USD as integer (not cents): 50000 for $50,000.
purpose_idinvalidFetch valid IDs from GET /v1/purposes?type=BUSINESS. Do not use string enums.
source_of_fund_idsinvalidFetch valid IDs from GET /v1/source-of-funds?type=BUSINESS.
source_of_wealth_idsinvalidFetch valid IDs from GET /v1/source-of-wealth?type=BUSINESS.
Last updated: April 2026 — Reflects V2 API (POST /v2/customers/business)