> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Phase 1: Registration & Onboarding
> Individual customer registration with categorization and validation
# Phase 1: Registration & Onboarding
Registration is the entry point for all individual customers. This phase creates the customer record, user credentials, and default inactive wallet.
## What Gets Created
| Component | Status | Description |
| ---------------- | ---------------------- | ------------------------------------ |
| Customer Record | `PENDING_VERIFICATION` | Core customer entity |
| User Credentials | Active | Login credentials (hashed) |
| Wallet | `INACTIVE` | Default wallet (activated later) |
| Categorization | Assigned | Feature-based category (if provided) |
***
## Step 1: Get Categorization Hierarchy
Before registration, retrieve available categories and features for smart categorization.
**Endpoint:** `GET /api/v2.1/customer/individual/categorization/hierarchy/{tenantId}`
**Headers:**
```http theme={null}
Authorization: Bearer {admin-jwt-token}
X-Tenant-ID: fh_api_finsei_ltd_7f957f77
```
**Status:** `200 OK`
```json theme={null}
{
"code": 200,
"message": "Hierarchy retrieved successfully",
"data": {
"tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
"tenantName": "Finsei Ltd",
"complianceLevel": "ENHANCED",
"categories": {
"HIGH_RISK_INDIVIDUAL": {
"databaseId": "550e8400-e29b-41d4-a716-446655440001",
"categoryId": "HIGH_RISK_INDIVIDUAL",
"categoryName": "High Risk Individual Customer",
"description": "High-risk customers requiring enhanced monitoring",
"availableFeatures": [
{
"featureCode": "ENHANCED_AML_MONITORING",
"featureName": "Enhanced AML Monitoring",
"mandatoryKeys": [
"riskLevel", "riskScore", "pep",
"sanctionsCheck", "monitoring", "edd"
],
"allowedValues": {
"riskLevel": ["LOW", "MEDIUM", "HIGH", "CRITICAL"],
"riskScore": ["0-100"],
"pep": ["true", "false"],
"pepCategory": ["DOMESTIC_PEP", "FOREIGN_PEP", "RCA", "HIO"],
"sanctionsCheck": ["STANDARD", "ENHANCED", "REAL_TIME"],
"monitoring": ["WEEKLY", "DAILY", "REAL_TIME"],
"edd": ["true", "false"]
}
}
]
},
"STANDARD_INDIVIDUAL": {
"databaseId": "550e8400-e29b-41d4-a716-446655440010",
"categoryId": "STANDARD_INDIVIDUAL",
"categoryName": "Standard Individual Customer"
}
}
}
}
```
***
## Step 2: Register Individual Customer
**Endpoint:** `POST /api/v2.1/customer/individual/registration`
**Headers:**
```http theme={null}
X-Tenant-ID: fh_api_finsei_ltd_7f957f77
Authorization: Bearer {admin-jwt-token}
Content-Type: application/json
```
**Request Body:**
```json theme={null}
{
"tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
"email": "john.doe@example.com",
"password": "SecurePass123!@#",
"matchingPassword": "SecurePass123!@#",
"firstName": "John",
"lastName": "Doe",
"individualCustomer": {
"tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
"email": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe",
"middleName": "Robert",
"dateOfBirth": "1990-05-15",
"placeOfBirth": "New York",
"nationality": "US",
"phoneNumber": "+12125551234",
"alternatePhoneNumber": "+12125559876",
"address": {
"street": "123 Main Street",
"streetNumber": "123",
"apartment": "Apt 4B",
"city": "New York",
"state": "NY",
"postalCode": "10001",
"country": "US",
"addressType": "RESIDENTIAL"
},
"occupation": "Software Engineer",
"employerName": "Tech Corp Inc",
"annualIncome": "150000",
"sourceOfFunds": "SALARY",
"categorization": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "HIGH_RISK_INDIVIDUAL",
"isActive": true,
"categoryFeatureRelations": [
{
"feature": {
"id": "660e8400-e29b-41d4-a716-446655440002",
"code": "ENHANCED_AML_MONITORING"
},
"enabled": true,
"parametrization": [
{ "name": "riskLevel", "value": "HIGH" },
{ "name": "riskScore", "value": "85" },
{ "name": "pep", "value": "true" },
{ "name": "pepCategory", "value": "DOMESTIC_PEP" },
{ "name": "sanctionsCheck", "value": "ENHANCED" },
{ "name": "monitoring", "value": "DAILY" },
{ "name": "edd", "value": "true" }
]
},
{
"feature": {
"id": "770e8400-e29b-41d4-a716-446655440003",
"code": "TRANSACTION_LIMITS"
},
"enabled": true,
"parametrization": [
{ "name": "dailyLimit", "value": "5000" },
{ "name": "monthlyLimit", "value": "50000" },
{ "name": "singleTransactionLimit", "value": "2000" }
]
}
]
}
}
}
```
**Status:** `201 Created`
```json theme={null}
{
"code": 201,
"message": "Account created successfully",
"data": {
"id": "cust-550e8400-e29b-41d4-a716-446655440010",
"userId": "user-660e8400-e29b-41d4-a716-446655440011",
"email": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe",
"status": "PENDING_VERIFICATION",
"categorization": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "HIGH_RISK_INDIVIDUAL",
"categoryFeatureRelations": [...]
},
"createdAt": "2026-01-13T10:30:00.000Z",
"updatedAt": "2026-01-13T10:30:00.000Z"
}
}
```
**Key IDs to Store:**
* `id` → Customer ID (for all subsequent calls)
* `userId` → User ID (for session creation)
**400 - Password Mismatch:**
```json theme={null}
{
"code": 400,
"message": "Request validation failed",
"data": {
"errors": [
{
"field": "matchingPassword",
"message": "Password and matching password must be identical"
}
]
}
}
```
**400 - Invalid Categorization:**
```json theme={null}
{
"code": 400,
"message": "Categorization validation failed",
"data": {
"error": "Invalid categorization",
"details": "Feature 'ENHANCED_AML_MONITORING' requires mandatory key 'riskLevel'",
"missingKeys": ["riskLevel"],
"invalidValues": {
"monitoring": "HOURLY is not in allowed values: [WEEKLY, DAILY, REAL_TIME]"
}
}
}
```
**403 - Tenant Access Denied:**
```json theme={null}
{
"code": 403,
"message": "Tenant access denied or categorization not available",
"data": {
"error": "Tenant access denied",
"tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"
}
}
```
***
## Business Logic
### Tenant ID Resolution
The system resolves tenant ID from the header:
```
1. Extract X-Tenant-ID header (e.g., "fh_api_finsei_ltd_7f957f77")
2. Resolve to UUID (e.g., "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd")
3. Override tenant ID in request body
```
### Password Validation Rules
| Rule | Requirement |
| ------------------ | ------------------------ |
| Minimum Length | 8 characters |
| Uppercase | At least 1 |
| Lowercase | At least 1 |
| Numbers | At least 1 |
| Special Characters | At least 1 |
| Must Match | `matchingPassword` field |
| Cannot Contain | Username or email |
### Categorization Validation
```
1. Check if categorization provided
2. Validate category exists in tenant hierarchy
3. For each feature:
a. Validate feature exists for tenant
b. Check all mandatory keys provided
c. Validate values against allowedValues
4. Store validated categorization
```
### Auto-Generated Components
| Component | Format |
| ------------------------ | ------------------ |
| Customer ID | UUID v4 |
| User ID | UUID v4 |
| Wallet ID | UUID v4 (inactive) |
| Email Verification Token | 64-char hex string |
***
## Smart Categorization Examples
### High-Risk Customer
**Selection Criteria:**
* PEP (Politically Exposed Person)
* High transaction volume expected
* High-risk occupation or industry
* High-risk country
**Configuration:**
```json theme={null}
{
"riskLevel": "HIGH",
"riskScore": "85",
"pep": "true",
"pepCategory": "DOMESTIC_PEP",
"sanctionsCheck": "ENHANCED",
"monitoring": "DAILY",
"edd": "true",
"transactionMonitoring": "REAL_TIME"
}
```
### Standard Customer
**Configuration:**
```json theme={null}
{
"riskLevel": "MEDIUM",
"riskScore": "45",
"pep": "false",
"sanctionsCheck": "STANDARD",
"monitoring": "WEEKLY",
"edd": "false",
"transactionMonitoring": "BATCH_DAILY"
}
```
***
## Next Step
After successful registration, proceed to **Phase 2: Session Management** to authenticate the customer.
Create customer session and obtain JWT token