Individual Customer APIs (B2C)
Complete API reference for individual customer onboarding and lifecycle management
Individual Customer APIs (B2C)
End-to-end API reference for individual customer lifecycle management — from categorization and registration through identity verification, consent collection, and account activation.
Onboarding Journey
The individual customer onboarding flow follows 5 customer API phases, plus verification and consent steps handled by the Verification & Compliance APIs:
| Phase | API Section | Endpoint | Description |
|---|---|---|---|
| 1. Categorization | Customer | GET /categorization/hierarchy/{tenantId} | Retrieve available customer categories and risk tiers |
| 2. Registration | Customer | POST /registration | Create a new individual customer with personal details |
| 3. Session | Customer | POST /{customerId}/users/{userId}/sessions | Authenticate and obtain a JWT access token |
| 4. Verification | Customer | POST /{customerId}/verification | Initiate identity verification for the customer |
| 5. KYC Documents | Verification | POST /verifications/{verificationId}/documents | Upload identity and address documents |
| 6. KYC Approval | Verification | POST /verifications/{verificationId}/approve | Admin approves the verification submission |
| 7. Consents | Verification | POST /{customerId}/consents/{consentType} | Accept terms, privacy, and data-processing consents |
| 8. Activation | Customer | POST /{customerId}/activation | Activate the customer account and wallet |
API Endpoints
Retrieve the category hierarchy to determine available customer tiers and features
Register a new individual customer with personal and contact information
Create authenticated sessions and obtain JWT tokens
Initiate identity verification (KYC) for a registered customer
Activate the customer account once all prerequisites are met
Quick Start
1. Retrieve Categories
curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/individual/categorization/hierarchy/{tenantId}" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "X-Tenant-ID: YOUR_TENANT_ID"2. Register Customer
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/registration" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "X-Tenant-ID: YOUR_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePass123!",
"customerCategory": { "id": "fs-cat-b2c-low-001" },
...
}'3. Create Session
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/{customerId}/users/{userId}/sessions" \
-H "X-Tenant-ID: YOUR_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{ "username": "user@example.com", "password": "SecurePass123!" }'4-8. Complete Verification, Consents & Activation
See the Verification & Compliance section for document upload, approval, and consent endpoints, then return to the Activation endpoint to complete onboarding.
Prerequisites
- API credentials obtained (Tenant ID, API keys, admin session token)
- Customer categorization selected from the hierarchy
- Customer personal information collected (name, email, date of birth, nationality)
- Identity documents ready (passport or national ID, proof of address)
Customer Lifecycle
stateDiagram-v2
[*] --> Categorization: Get category hierarchy
Categorization --> Registration: Select category
Registration --> Session: Customer created
Session --> Verification: JWT obtained
Verification --> Documents: KYC initiated
Documents --> Approval: Documents uploaded
Approval --> Consents: KYC approved
Consents --> Activation: All 3 consents accepted
Activation --> [*]: Account ACTIVE
note right of Verification
Uses Verification &
Compliance APIs
end note
note right of Approval
Admin review required
(1-3 business days)
end note
note right of Activation
Requires:
✓ KYC approved
✓ All consents accepted
end note