Onboard an Individual

This guide uses Graded Onboarding (V2). You choose the level to start at: Level 1 for a quick start in the US, or Level 2 for full verification.

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 occupation, residence.state and the identity document types. See Onboarding Lookups.
Use a supported country, and not a prohibited one. See Onboarding Fixed Lists.
Don't send the Customer the verification_link from the Customer response. It opens the Standard Onboarding (V1) form. If the Customer completes it, they can't use Graded Onboarding anymore, and the V2 endpoints return error code 2309.

Level 1

For US residents only. Send the nationality and the state, as a two-letter code:

POST /api/v2/customers/{customer_uuid}/individual/onboarding

{
    "kyc_level": 1,
    "nationality": "US",
    "residence": {
        "country": "US",
        "state": "WA"
    }
}

The response is 202, and the status is processing. The Customer is usually at Level 1 within a few seconds:

{
    "data": {
        "status": "verified",
        "kyc_level": 1,
        "next_level": 2,
        "transfers_blocked": false,
        "rfi_link": null,
        "pending_requirements": []
    }
}

Don't send any other field with Level 1. Level 2 fields, such as the address or an identity document, are refused.

Level 2

For any Customer, in or outside the US. Send the full address, occupation, purpose of use, a tax number and an identity document. For example, a US resident:

POST /api/v2/customers/{customer_uuid}/individual/onboarding

{
    "kyc_level": 2,
    "nationality": "US",
    "residence": {
        "country": "US",
        "state": "WA",
        "street": "200 Pine St",
        "sub_street": "Apt 5",
        "city": "Seattle",
        "postal_code": "98101"
    },
    "occupation": "legislators_and_senior_officials",
    "purpose_of_use": ["payments"],
    "ssn": "123456789",
    "phone_country_code": "US",
    "phone_number": "+14045550101",
    "identity_document": {
        "type": "PASSPORT",
        "country": "US",
        "front": "{{BASE64_IMAGE}}"
    }
}

For a Customer outside the US:

Leave out residence.state and ssn.
Send tax_id with the Customer's local tax number.

The response is 202, and the status is processing. The review usually takes from a few minutes to a day.

Fields to Watch

residence.state: US only, as a two-letter code from a state Harbor serves.
ssn: US residents only, 9 digits. Customers outside the US send tax_id instead.
phone_country_code and phone_number: required at Level 2, in and outside the US, unless the Customer already has one.
residence.sub_street: required at Level 2. An empty string isn't accepted.
identity_document: a JPG or PNG between 100 KB and 8 MB. Add back for document types that have two sides.

Graded Onboarding doesn't use the Standard Onboarding fields, such as the individual object, source_of_wealth or proof_of_address. Sending them returns an error.

What Happens Next

To move the Customer to a higher level, see Upgrade a Level.
To follow the status, see Onboarding Lifecycle.
If it's action_required, see Fix Onboarding Errors.

Notes

Graded Onboarding doesn't accept the Standard Onboarding fields. If the request includes individual, applicant, level, tier, verification_tier, source_of_wealth, source_of_wealth_other, proof_of_address, bank_statement or has_us_bank_account, it returns 422. The error message for each field says what to send instead, for example kyc_level instead of level.
Level 3 can't be submitted directly. A Customer reaches it by upgrading from Level 2.
In Sandbox, start at Level 1 and upgrade to Level 2. A Level 2 submitted directly doesn't get a level. See Test in Sandbox.