Onboard a Business

This guide uses Standard Onboarding (V1). If you don't want to build your own form, use the Hosted Form instead.

Before You Start

Create the Customer with type set to business. See Customers.
The Customer accepts the agreement through agreement_link. Until then, the request returns error code 2103.
Gather the six required company documents. Companies often take a few days to collect them.
Get the allowed values for company.industry and associated_persons[].position. See Onboarding Lookups.
Check the fixed values for company.type and company.source_of_funds. See Onboarding Fixed Lists.
Use a supported country, and not a prohibited one. See Onboarding Fixed Lists.

Send the Information

The request has three parts:

company: the company's details.
associated_persons: the people linked to the company, each with an identity document.
company_files: the company documents.

For example, a US corporation with a legal representative and an applicant:

POST /api/v1/customers/{customer_uuid}/onboarding

{
    "company": {
        "name": "Acme US Inc",
        "business_name": "Acme",
        "registration_number": "REG123456",
        "country": "US",
        "incorporation_date": "2020-01-01",
        "type": "corporation",
        "description": "Software publishers",
        "industry": "software_publishers",
        "register_address": { "street": "100 Main St", "city": "Richmond", "state": "VA", "postal_code": "23218" },
        "business_address": { "street": "100 Main St", "city": "Richmond", "state": "VA", "country": "US", "postal_code": "23218" },
        "phone_country_code": "US",
        "phone_number": "2025550100",
        "email": "[email protected]",
        "url": "https://acme.us",
        "has_bearer_shares": false,
        "purpose_of_registration": "receiptAndPayment",
        "estimated_number_of_transactions": 100,
        "estimated_amount_of_transactions": 50000,
        "country_of_operation": ["US"],
        "has_vasp_relationship": false,
        "source_of_funds": "BUSINESS_INCOME",
        "transfers_funds_for_clients": false,
        "tax_id": "123456789"
    },
    "associated_persons": [
        {
            "type": "representative",
            "first_name": "Ada",
            "last_name": "Smith",
            "id_type": "PASSPORT",
            "id_number": "A1234567",
            "birthday": "1990-01-01",
            "gender": "F",
            "nationality": "US",
            "position": "director",
            "residential_address": { "street": "200 Pine St", "city": "Richmond", "state": "VA", "country": "US", "postal_code": "23219" },
            "permanent_address": { "street": "200 Pine St", "city": "Richmond", "state": "VA", "country": "US", "postal_code": "23219" },
            "phone": { "country": "US", "number": "4045550101" },
            "identity_files": [
                { "file_type": "PASSPORT", "part": "FRONT", "country": "US", "file": "{{BASE64_IMAGE}}" }
            ]
        },
        {
            "type": "applicant",
            "first_name": "Ben",
            "last_name": "Jones",
            "id_type": "PASSPORT",
            "id_number": "B7654321",
            "birthday": "1988-03-03",
            "gender": "M",
            "nationality": "US",
            "email": "[email protected]",
            "residential_address": { "street": "200 Pine St", "city": "Richmond", "state": "VA", "country": "US", "postal_code": "23219" },
            "identity_files": [
                { "file_type": "PASSPORT", "part": "FRONT", "country": "US", "file": "{{BASE64_IMAGE}}" }
            ]
        }
    ],
    "company_files": [
        { "file_type": "corporate_registration_documents", "files": ["{{BASE64_FILE}}"] },
        { "file_type": "documents_of_corporate_governance_and_amendment", "files": ["{{BASE64_FILE}}"] },
        { "file_type": "certificate_of_incumbency", "files": ["{{BASE64_FILE}}"] },
        { "file_type": "proof_of_residential_address_of_the_ubo", "files": ["{{BASE64_FILE}}"] },
        { "file_type": "proof_of_business_operating_address", "files": ["{{BASE64_FILE}}"] },
        { "file_type": "organization_chart", "files": ["{{BASE64_FILE}}"] }
    ]
}

The response is 202, and the onboarding starts in processing:

{
    "data": {
        "id": "onb_1FiP9xeK4tZbHAlu4r5kZeZolMgBpKBZ1Qgt8t6r",
        "customer_id": "cus_Xhxz2faYDQnFxqPmJ4H0m54RdmPTx8DphhYPbZnX",
        "applicant": "company",
        "status": "processing",
        "submitted_at": null,
        "created_at": "2026-10-12T08:29:03.000000Z",
        "updated_at": "2026-10-12T08:29:03.000000Z"
    }
}

People to Include

Each person in associated_persons has a type:

representative: the company's legal representative. Exactly one.
applicant: the person applying for the account. At least one.
equity_holder: anyone who owns more than 20% of the company. If no one does, add the person who controls the company.
controller: a senior manager. Needed when the company is public, non-profit or state-owned, or when no one owns more than 20%.

Every person needs a name, date of birth, nationality, address and an identity document. Some types need more fields, such as position or email. See Send the information in the API reference.

Company Documents

Send each document type once in company_files, with one or more files. These six are required:

corporate_registration_documents: official registration documents from the government.
documents_of_corporate_governance_and_amendment: articles of incorporation, bylaws and their changes.
certificate_of_incumbency: the current directors and officers.
proof_of_residential_address_of_the_ubo: proof of address of the owners over 20%.
proof_of_business_operating_address: proof of the company's operating address.
organization_chart: the ownership structure.

You can also send initial_capital, income_source, business_license, executive_documents, financial_documents, compliance_documents and other_documentation.

What Happens Next

The onboarding moves from processing to submitted while Harbor reviews it, usually within a few minutes. The review then takes about 5 business days, and longer for complex company structures.

To follow the status, see Onboarding Lifecycle.
If it's action_required, see Fix Onboarding Errors.

Notes

Files: each file must be between 100 KB and 8 MB, or up to 10 MB for company documents. Identity documents must be JPG or PNG. Company documents can also be PDF. The whole request can be up to 50 MB.
Common reasons for a rejection: the company is registered in a country or US state Harbor doesn't serve, documents are screenshots or edited files instead of the originals, owners over 20% are missing, or the registration documents aren't official government documents.