Upgrade a Level

A Customer moves up one level at a time, from Level 1 to Level 2, then from Level 2 to Level 3. You don't choose the level. The upgrade always goes to the next one, shown in next_level.

Level 1 to Level 2

Send only the Level 2 information that Level 1 didn't collect. Don't send kyc_level, residence.country or residence.state. They come from Level 1.

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

{
    "residence": {
        "street": "200 Pine St",
        "sub_street": "Apt 5",
        "city": "Seattle",
        "postal_code": "98101"
    },
    "occupation": "legislators_and_senior_officials",
    "purpose_of_use": ["payments"],
    "ssn": "123456789",
    "identity_document": {
        "type": "PASSPORT",
        "country": "US",
        "front": "{{BASE64_IMAGE}}"
    }
}

The response is 202. While Level 2 is reviewed, the Customer can't transfer, and transfers_blocked is true:

{
    "data": {
        "status": "processing",
        "kyc_level": 1,
        "next_level": null,
        "transfers_blocked": true,
        "rfi_link": null,
        "pending_requirements": []
    }
}

When Level 2 is approved, kyc_level is 2 and transfers_blocked is false again.

Level 2 to Level 3

Send a short reason, up to 500 characters. Harbor's compliance team reviews it and contacts the Customer.

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

{
    "reason": "Requesting a higher monthly limit for increased contractor payouts."
}

The response is 202, with the status requested. Unlike Level 2, the Customer can keep transferring at Level 2 during the review:

{
    "data": {
        "status": "requested",
        "requested_at": "2026-09-09T07:40:00+00:00",
        "kyc_level": 2,
        "next_level": null,
        "transfers_blocked": false,
        "rfi_link": null,
        "pending_requirements": []
    }
}

The review usually takes 1 to 3 business days.

Errors

Code	Meaning	What to do
`2005`	A field is missing, or a field was sent that this upgrade doesn't take.	Check `errors`, and fix the request.
`2310`	The Customer has no approved level yet, or is already at Level 3.	Complete Level 1 or Level 2 first.
`2313`	A Level 3 request was already sent in the last 7 days.	Wait. The message says when you can send again.
`2312`	The Customer is declined.	No upgrade is possible.
`2302`, `2318`, `2319`	A submission is still open for the Customer.	Wait for the review, retry if it is processing, or send corrections with `PATCH`. These return `409`.

Notes

If the Level 2 upgrade goes to action_required, fix it with PATCH and the full Level 2 request. See Fix Onboarding Errors.
In Sandbox, any identity image between 100 KB and 8 MB gets the Customer to Level 2 within about a minute. Level 3 isn't available for testing.