> ## 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. # Categorization Hierarchy > Smart categorization strategy for customer risk classification # Categorization Hierarchy Categorization is a feature-based system for classifying customers based on risk level and enabling appropriate monitoring and limits. ## Overview ```mermaid theme={null} flowchart TD A[Tenant] --> B[Categories] B --> C[HIGH_RISK_INDIVIDUAL] B --> D[STANDARD_INDIVIDUAL] B --> E[MEDIUM_RISK_BUSINESS] C --> F[Features] D --> F E --> F F --> G[ENHANCED_AML_MONITORING] F --> H[TRANSACTION_LIMITS] F --> I[INTERNATIONAL_PAYMENTS] ``` *** ## Get Categorization Hierarchy Before registration, retrieve available categories and features. **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 ``` ```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": [ { "databaseId": "660e8400-e29b-41d4-a716-446655440002", "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"] }, "multiValueKeys": ["pepCategory"] } ] }, "STANDARD_INDIVIDUAL": { "databaseId": "550e8400-e29b-41d4-a716-446655440010", "categoryId": "STANDARD_INDIVIDUAL", "categoryName": "Standard Individual Customer" } }, "features": { "ENHANCED_AML_MONITORING": { "databaseId": "660e8400-e29b-41d4-a716-446655440002", "featureCode": "ENHANCED_AML_MONITORING", "featureName": "Enhanced AML Monitoring", "description": "Real-time transaction monitoring and enhanced due diligence" }, "TRANSACTION_LIMITS": { "databaseId": "770e8400-e29b-41d4-a716-446655440003", "featureCode": "TRANSACTION_LIMITS", "featureName": "Transaction Limits" } } } } ``` *** ## Category Types ### Individual (B2C) Categories | Category | Description | Approval Level | | ---------------------- | ------------------------------------- | -------------- | | `HIGH_RISK_INDIVIDUAL` | PEP, high-risk countries, high volume | POWER\_TENANT | | `STANDARD_INDIVIDUAL` | Standard customers | TENANT | | `LOW_RISK_INDIVIDUAL` | Low-risk, verified customers | TENANT | ### Organization (B2B) Categories | Category | Description | Approval Level | | ---------------------- | ----------------------------------- | -------------- | | `HIGH_RISK_BUSINESS` | PEP involvement, high-risk industry | POWER\_TENANT | | `MEDIUM_RISK_BUSINESS` | Standard business operations | TENANT | | `LOW_RISK_BUSINESS` | Regulated, low-risk industry | TENANT | *** ## Feature Configuration ### ENHANCED\_AML\_MONITORING For high-risk customers requiring enhanced monitoring. | Key | Required | Allowed Values | | ----------------------- | ----------- | ------------------------------------- | | `riskLevel` | ✅ | LOW, MEDIUM, HIGH, CRITICAL | | `riskScore` | ✅ | 0-100 (numeric) | | `pep` | ✅ | true, false | | `pepCategory` | Conditional | DOMESTIC\_PEP, FOREIGN\_PEP, RCA, HIO | | `sanctionsCheck` | ✅ | STANDARD, ENHANCED, REAL\_TIME | | `monitoring` | ✅ | WEEKLY, DAILY, REAL\_TIME | | `edd` | ✅ | true, false | | `transactionMonitoring` | Optional | BATCH\_DAILY, REAL\_TIME | **Example Configuration:** ```json theme={null} { "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" }, { "name": "transactionMonitoring", "value": "REAL_TIME" } ] } ``` *** ### TRANSACTION\_LIMITS Define transaction limits for the customer. | Key | Required | Description | | ------------------------ | -------- | ---------------------------------- | | `dailyLimit` | ✅ | Maximum daily transaction amount | | `monthlyLimit` | ✅ | Maximum monthly transaction amount | | `singleTransactionLimit` | ✅ | Maximum single transaction amount | **Example Configuration:** ```json theme={null} { "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" } ] } ``` *** ### INTERNATIONAL\_PAYMENTS (B2B) Enable international payment capabilities. | Key | Required | Description | | ------------------ | -------- | ------------------------------ | | `swiftEnabled` | ✅ | Enable SWIFT transfers | | `sepaEnabled` | ✅ | Enable SEPA transfers | | `crossBorderLimit` | ✅ | Cross-border transaction limit | **Example Configuration:** ```json theme={null} { "feature": { "id": "org-feat-770e8400-e29b-41d4-a716-446655440102", "code": "INTERNATIONAL_PAYMENTS" }, "enabled": true, "parametrization": [ { "name": "swiftEnabled", "value": "true" }, { "name": "sepaEnabled", "value": "true" }, { "name": "crossBorderLimit", "value": "50000" } ] } ``` *** ## Smart Categorization Strategy ### High-Risk Customer Criteria Assign `HIGH_RISK_INDIVIDUAL` or `HIGH_RISK_BUSINESS` when: * ✅ Customer is a PEP (Politically Exposed Person) * ✅ High transaction volume expected (>€50k/month) * ✅ High-risk occupation or industry * ✅ High-risk country of residence/nationality * ✅ Sanctions list check required * ✅ Complex ownership structure (B2B) ### Standard Customer Criteria Assign `STANDARD_INDIVIDUAL` or `MEDIUM_RISK_BUSINESS` when: * ✅ No PEP involvement * ✅ Standard transaction volume * ✅ Low-risk occupation or industry * ✅ Low-risk country * ✅ Simple ownership structure (B2B) *** ## Validation Process ```mermaid theme={null} flowchart TD A[Registration Request] --> B{Categorization Provided?} B -->|No| C[Use Default Category] B -->|Yes| D[Validate Category Exists] D --> E{Valid Category?} E -->|No| F[Return 400 Error] E -->|Yes| G[Validate Features] G --> H{All Mandatory Keys?} H -->|No| F H -->|Yes| I{Valid Values?} I -->|No| F I -->|Yes| J[Store Categorization] J --> K[Registration Success] ``` ### Validation Rules 1. **Category must exist** in tenant hierarchy 2. **All mandatory keys** must be provided for each feature 3. **Values must match** allowed values 4. **Multi-value keys** can have multiple values (comma-separated) *** ## Common Validation Errors ### Missing Mandatory Key ```json theme={null} { "code": 400, "message": "Categorization validation failed", "data": { "error": "Missing mandatory key 'riskLevel'", "feature": "ENHANCED_AML_MONITORING", "missingKeys": ["riskLevel"] } } ``` ### Invalid Value ```json theme={null} { "code": 400, "message": "Categorization validation failed", "data": { "error": "Invalid value for key 'monitoring'", "feature": "ENHANCED_AML_MONITORING", "invalidValues": { "monitoring": "HOURLY is not in allowed values: [WEEKLY, DAILY, REAL_TIME]" } } } ``` *** ## Best Practices 1. **Always call hierarchy endpoint first** - Get current categories and features 2. **Don't hardcode IDs** - IDs may differ across environments 3. **Validate locally before submission** - Check mandatory keys and values 4. **Use appropriate risk levels** - Match customer profile to category 5. **Document categorization decisions** - Keep audit trail