Fix Onboarding Errors

This page is for onboarding through the API. If you use the hosted form, the Customer fixes their information in the form. See Onboard via Hosted Form.

What to Do First

Check what happened, then go to the matching section:

• You got a 422 when you sent the request: see Fix the Request.
• The onboarding status is action_required: see Fix After Review.
• The status is action_required and pending_requirements is empty: see No Reason Given.
• The Customer is declined: see Declined.

To check the onboarding status, see Onboarding Lifecycle.

Fix the Request

• What happened: Harbor refused the request right away. Nothing was created.
• What to do: fix each field named in errors, and send the same request again.

For example, the state was sent as a name instead of a two-letter code:

{
    "message": "The residence.state is not a state where graded individual verification is available.",
    "code": 2005,
    "error_type": "general.validation_error",
    "errors": {
        "residence.state": [
            "The residence.state is not a state where graded individual verification is available."
        ]
    }
}

Sending "WA" instead of "Washington" fixes it. Common causes:

• A state name instead of the two-letter code, such as Washington instead of WA.
• A US state Harbor doesn't serve. Get the list of served states from the endpoint below.
• A file under 10 KB.
• Level 1 for a Customer who doesn't live in the US. Level 1 is US only, so submit Level 2.

GET /api/v2/customers/individual/countries/{country}/subdivisions

Fix After Review

• What happened: Harbor accepted the request, but something failed during the review.
• What to do: read pending_requirements, fix the problem, and resend with PATCH. See How PATCH Works.

For example, the passport photo was smaller than 100 KB:

{
    "data": {
        "status": "action_required",
        "kyc_level": 1,
        "next_level": null,
        "transfers_blocked": true,
        "rfi_link": null,
        "pending_requirements": [
            {
                "source": "provider_error",
                "description": "Validation failed - {\"identity_document.front\":[\"unsupported file format or invalid file size (file size must be at least 100 KB)\"]}"
            }
        ]
    }
}

Sending a larger photo of the original passport fixes it. Common causes:

• A file under 100 KB, for example a thumbnail or a compressed copy.
• A US state Harbor doesn't serve, sent with Standard Onboarding (V1).
• For businesses, a missing company document.

No Reason Given

• What happened: the document itself was rejected, for example because it's unreadable, cropped or the wrong type. pending_requirements is empty.
• What to do: ask the Customer for a new, clear photo of their original document, and resend with PATCH.

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

The Customer's status is rejected. If the reviewer wrote instructions, they're in the Customer's review_reason.

How PATCH Works

PATCH replaces the whole request. Send every required field again, not only the one you fixed.

• Standard Onboarding (V1): PATCH /api/v1/customers/{customer_uuid}/onboarding
• Graded Onboarding (V2): PATCH /api/v2/customers/{customer_uuid}/individual/onboarding

For example, to fix a failed Level 1 to Level 2 upgrade, send the full Level 2 request, with kyc_level, nationality and the full residence. The upgrade itself didn't need them, but PATCH does:

{
    "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",
    "identity_document": {
        "type": "PASSPORT",
        "country": "US",
        "front": "{{BASE64_IMAGE}}"
    }
}

After the PATCH, the status goes back to processing, then submitted.

Declined

• What happened: the Customer is declined. This is final.
• What to do: nothing. The Customer can't be onboarded again, and any new request returns error code 2312.

A Customer is declined when the review finds they can't be onboarded under Harbor's compliance rules.

Error Codes

The onboarding endpoints can also refuse a request for these reasons. The error code is in the response's code field.

Notes

• File rules: each file must be between 100 KB and 8 MB. Identity documents must be JPG or PNG. Proof of address and company documents can also be PDF.
• In Sandbox: if a Customer gets stuck and PATCH keeps failing, create a new Customer.
• Agreement: the onboarding API can't be used before the agreement is accepted. It returns 403 with error code 2103 (customer.agreement_not_signed).