Onboard via API (Direct Integration)

This guide introduces the direct API onboarding integration. Collect your customers' profiles and documents directly in your application and submit them to Harbor — either as a complete, single-call payload, or incrementally through a progressive level-based flow.

Based on the customer's type and your preferred integration path, select the appropriate guide below:

---

1. Shared Infrastructure & Common Parts

Regardless of whether you are onboarding a business or an individual, the core infrastructure, endpoints, lifecycle, headers, and error handling remain identical.

1.1 Environments & Base URLs

The endpoints use standard authentication with your application's API key.

1.2 Authentication & Headers

1.3 Core Endpoints

---

2. Meta APIs (Reference-Data Lookups)

Dynamic lookup endpoints must be called in real-time to display correct dropdown values in your user interface. Some are shared, while others are specific to the onboarding type:

2.1 Shared Meta APIs

• Address Subdivisions (state):
  GET /api/v1/countries/{country}/subdivisions
  Used to obtain ISO 3166-2 state/subdivision codes (e.g. VA for Virginia, ENG for England). Submit the subdivision code in address payloads. Omit state for countries with no subdivisions.

2.2 Business-Specific (KYB) Meta APIs

• Job Titles / Positions:
  GET /api/v1/job-titles
  Returns allowed roles for directors, UBOs, and representatives (associated_persons[].position).
• Industry Classifications:
  GET /api/v1/countries/{country}/industries
  Returns allowed industry slugs for the company's country of incorporation (company.industry).

2.3 Individual-Specific (KYC) Meta APIs

• Occupations:
  GET /api/v1/occupations
  Returns allowed occupation values for individuals (individual.occupation).

---

3. Onboarding Status & Lifecycle

Every onboarding process proceeds through the same state machine:

graph TD
    POST --> processing
    processing --> submitted
    processing --> action_required
    action_required -->|you PATCH| processing
    submitted --> verified
    submitted --> declined

    classDef terminal fill:#f9f,stroke:#333,stroke-width:2px;
    class verified,declined terminal;

📘

Onboarding Lifecycle & Exceptions Playbook

For a highly detailed guide on how to programmatically detect and resolve action_required states, handle final declined conditions, or manage customer-level Requests for Information (RFIs), please refer directly to the Onboarding & RFI Guide.

---

4. Tracking Progress

Option A — Status Polling (GET)

Call GET /api/v1/customers/{{customer_uuid}}/onboarding periodically. When the status is action_required, inspect the pending_requirements array.

Option B — Webhooks (Recommended)

Subscribe to the following webhook events to receive real-time updates:

• customer_onboarding.submitted — accepted for verification
• customer_onboarding.action_required — requires data correction
• customer_onboarding.verified — verification passed
• customer_onboarding.declined — verification failed (terminal)

---

5. Size Limits

To prevent upload timeouts, adhere strictly to the following size limits across all files (passports, corporate certificates, proof of address, etc.):

• Per File: ≤ 8 MB (after base64 decoding).
• Whole Request: ≤ 50 MB (total decoded size of all files in the request body).

---

6. Global Error Code Reference

When validation or business rules are violated, Harbor returns standard validation error arrays (422), state conflicts (409), or explicit custom numeric error codes.

📘

Consolidated Error Code Reference

For a comprehensive table of all onboarding, validation, upgrade conflict, and gateway middleware error codes, please refer directly to the Error Codes guide.