Upgrade Tier (Elevating Customer Levels)

Individual Customers Only · API v2

Once an individual customer on the Graded Onboarding (v2) scheme has been successfully onboarding and verified at their initial level, they can request an upgrade to a higher level (Level 2 or Level 3) to increase their transaction limits or unlock advanced capabilities.

1. Upgrade Endpoint

All level-elevation requests must be sent to the onboarding upgrade endpoint:

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

Required Headers

Your request must include standard API headers, including X-API-KEY, Content-Type: application/json, and an Idempotency-Key to prevent duplicate submissions.

2. Upgrading from Level 1 to Level 2

When upgrading a customer from Level 1 (Basic US-resident check) to Level 2 (Full Individual KYC), you submit only the incremental data fields needed to satisfy Level 2 requirements.

🚨 Critical Validation Rule

Because Level 1 already established the customer's country of residence and state (which must be US and a valid US state), you must not re-submit residence.country or residence.state in the upgrade payload.

Submitting country or state in the upgrade request will result in a 422 Unprocessable Entity error with code level_not_eligible_for_elevation or validation failure.

Example Payload: Level 1 ➔ Level 2

{
  "residence": {
    "street": "200 Pine St",
    "sub_street": "Apt 5",
    "city": "Seattle",
    "postal_code": "98101"
    // residence.country and residence.state are inherited; DO NOT send them!
  },
  "occupation": "legislators_and_senior_officials",
  "purpose_of_use": ["payments"],
  "ssn": "123456789",
  "identity_document": {
    "type": "PASSPORT",
    "country": "US",
    "front": "<base64_bytes>"
  }
}

Response: 202 Accepted with a status of processing. Moving from Level 1 to Level 2 pauses transacting; therefore, the customer's transfers_blocked state becomes true until the Level 2 review resolves.

3. Upgrading from Level 2 to Level 3

Level 3 represents advanced verification for high-limit users. Unlike Level 2, Level 3 does not collect standard structured KYC fields. Instead, it triggers a manual, case-by-case compliance review.

To request elevation from Level 2 to Level 3, submit a JSON payload containing only a descriptive reason for the request:

Example Payload: Level 2 ➔ Level 3

{
  "reason": "Requesting a higher monthly transaction limit for increased company payroll and contractor payout volume."
}

Response: 202 Accepted with a status of requested. The request is forwarded to Harbor's compliance team for manual review.

4. Upgrade Conflict Handling (409 Errors)

If an upgrade request cannot be processed due to the customer's current onboarding state, the API will return a 409 Conflict error. The error response includes a specific situation code:

Situation Code	Meaning	What It Means / Developer Action
`action_required`	The current onboarding level is in an `action_required` state.	You cannot upgrade. The user must first fix outstanding requirements using PATCH on the main onboarding endpoint.
`action_required_in_flight`	An in-flight upgrade request is in an `action_required` state.	An upgrade is already pending but needs correction. Fix issues by sending a PATCH request.
`processing`	The customer's initial onboarding is still being validated.	Wait for the initial onboarding to become `verified` before requesting an upgrade.
`submission_processing`	An upgrade request is already in progress and being validated.	Wait for the current upgrade request to complete processing.
`submitted`	An upgrade request is currently under manual review.	Duplicate request. Wait for the compliance team to approve or reject the pending review.
`already_active`	The target level is already active.	No action needed. The customer has already been verified at this level (or higher).
`details`	The upgrade request does not meet the eligibility prerequisites.	Read the error details. Ensure the customer has finished the prerequisites for elevation.

5. Specific Error Codes

When an upgrade request fails validation, check the error code in the response:

2303: Level already approved (use /upgrade for higher levels, or target level is already active).
2305: Cannot request upgrade while current onboarding is in processing status.
2310: Target level is not eligible for elevation (e.g., trying to upgrade to Level 3 before Level 2 is verified).
2313: Advanced-verification upgrade request cooldown is in progress.
2318: Cannot request upgrade; current onboarding has outstanding actions required.
2319: Cannot request upgrade; another upgrade is currently being processed.