Onboard an Individual

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 individual. See Customers.
• The Customer accepts the agreement through agreement_link. Until then, the request returns error code 2103.
• Get the allowed values for fields such as occupation and residence.state. See Onboarding Lookups.
• Use a supported country, and not a prohibited one. See Onboarding Fixed Lists.

Send the Information

Send the Customer's information in an individual object. For example, a US resident:

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

{
    "individual": {
        "first_name": "Jordan",
        "last_name": "Sample",
        "email": "[email protected]",
        "nationality": "US",
        "birthday": "1985-08-12",
        "residence": {
            "street": "200 Pine St",
            "sub_street": "Apt 2",
            "city": "Richmond",
            "state": "VA",
            "postal_code": "23219",
            "country": "US"
        },
        "occupation": "legislators_and_senior_officials",
        "source_of_wealth": ["salaryBusinessIncome"],
        "purpose_of_use": ["payments"],
        "ssn": "123456789",
        "phone_country_code": "US",
        "phone_number": "+14045550101",
        "proof_of_address": {
            "country": "US",
            "files": ["{{BASE64_FILE}}"]
        },
        "identity_document": {
            "type": "DRIVER_LICENCE",
            "country": "US",
            "front": "{{BASE64_IMAGE}}",
            "back": "{{BASE64_IMAGE}}"
        }
    }
}

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

{
    "data": {
        "id": "onb_FFFBubk55R1Myruer83Mah0i8yTBLft6tyP0u1WT",
        "customer_id": "cus_5N12uO7wjwKewJB82WBNPKs3ZaWxqQFn1jnOSVqm",
        "applicant": "individual",
        "status": "processing",
        "submitted_at": null,
        "created_at": "2026-10-12T05:47:11.000000Z",
        "updated_at": "2026-10-12T05:47:11.000000Z"
    }
}

For a Customer who lives outside the US, leave out ssn, phone_country_code, phone_number and proof_of_address. Send has_us_bank_account instead. If it's true, also send a bank_statement:

{
    "has_us_bank_account": true,
    "bank_statement": {
        "country": "GB",
        "files": ["{{BASE64_FILE}}"]
    }
}

Fields to Watch

These fields cause most of the errors:

• residence.state: the two-letter code, such as VA, not the full name. For US residents, use a state Harbor serves.
• identity_document: a JPG or PNG between 100 KB and 8 MB. ID cards and driver's licenses need front and back. Passports only need front.
• proof_of_address: US residents only. 1 to 5 files, dated within the last 90 days.
• phone_number: required for US residents, in international format, such as +14045550101.
• birthday: the Customer must be 18 or older.

For every field, see Send the information in the API reference.

What Happens Next

The onboarding moves from processing to submitted while Harbor reviews it, usually within a few minutes. Then it's verified or action_required.

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

Notes

• Harbor serves 41 US states for individuals. With Standard Onboarding, a state that isn't served is accepted at first, and the onboarding then moves to action_required. Get the list of served states from Onboarding Lookups.
• A review usually takes about 1 business day.