> ## 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: Organization Registration
> Register organization with legal information and representatives
# Phase 1: Organization Registration
Organization registration creates the foundation for all B2B operations including the organization entity, legal information, addresses, and default admin user.
## What Gets Created
| Component | Status | Description |
| ------------------- | ---------------------- | ------------------------------------ |
| Organization Record | `PENDING_VERIFICATION` | Core organization entity |
| Default Admin User | `PENDING_ACTIVATION` | Created via Kafka event |
| Wallet | `INACTIVE` | Default wallet (activated later) |
| Categorization | Assigned | Feature-based category (if provided) |
**Important:** Employees, directors, and shareholders arrays in the registration request are **ignored**. Use separate endpoints to add these entities.
***
## Register Organization
**Endpoint:** `POST /api/v2.1/customer/organization/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",
"legalName": "Acme Corporation Limited",
"tradingName": "Acme Corp",
"businessType": "B2B",
"registrationNumber": "REG123456789",
"taxId": "TAX987654321",
"vatNumber": "GB123456789",
"incorporationDate": "2010-05-20",
"legalForm": "LIMITED_LIABILITY_COMPANY",
"industry": "TECHNOLOGY",
"sector": "SOFTWARE_DEVELOPMENT",
"numberOfEmployees": 50,
"annualRevenue": "5000000",
"website": "https://www.acme-corp.com",
"description": "Leading provider of enterprise software solutions",
"registeredAddress": {
"street": "456 Business Avenue",
"streetNumber": "456",
"building": "Tech Tower",
"floor": "5th Floor",
"city": "London",
"state": "Greater London",
"postalCode": "EC1A 1BB",
"country": "GB",
"addressType": "REGISTERED_OFFICE"
},
"tradingAddress": {
"street": "456 Business Avenue",
"city": "London",
"postalCode": "EC1A 1BB",
"country": "GB",
"addressType": "TRADING_ADDRESS"
},
"contactEmail": "contact@acme-corp.com",
"contactPhone": "+442071234567",
"contactPerson": {
"firstName": "Jane",
"lastName": "Smith",
"position": "CEO",
"email": "jane.smith@acme-corp.com",
"phone": "+442071234569"
},
"representatives": [
{
"firstName": "Jane",
"lastName": "Smith",
"role": "CEO",
"email": "jane.smith@acme-corp.com",
"ownershipPercentage": 60.0,
"nationality": "GB",
"dateOfBirth": "1975-03-15",
"isPEP": false
},
{
"firstName": "John",
"lastName": "Doe",
"role": "CFO",
"email": "john.doe@acme-corp.com",
"ownershipPercentage": 40.0,
"nationality": "GB",
"dateOfBirth": "1978-07-22",
"isPEP": false
}
],
"categorization": {
"id": "org-cat-550e8400-e29b-41d4-a716-446655440100",
"name": "MEDIUM_RISK_BUSINESS",
"isActive": true,
"categoryFeatureRelations": [
{
"feature": {
"id": "org-feat-660e8400-e29b-41d4-a716-446655440101",
"code": "BUSINESS_TRANSACTION_LIMITS"
},
"enabled": true,
"parametrization": [
{ "name": "riskLevel", "value": "MEDIUM" },
{ "name": "riskScore", "value": "55" },
{ "name": "monthlyLimit", "value": "500000" },
{ "name": "transactionLimit", "value": "100000" },
{ "name": "dailyLimit", "value": "200000" }
]
},
{
"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" }
]
}
]
}
}
```
**Status:** `201 Created`
```json theme={null}
{
"code": 201,
"message": "Organization registered successfully. Default admin will be created automatically. Use separate endpoints to add employees, directors, and shareholders.",
"data": {
"id": "org-880e8400-e29b-41d4-a716-446655440110",
"legalName": "Acme Corporation Limited",
"tradingName": "Acme Corp",
"businessType": "B2B",
"status": "PENDING_VERIFICATION",
"registrationNumber": "REG123456789",
"taxId": "TAX987654321",
"incorporationDate": "2010-05-20",
"industry": "TECHNOLOGY",
"categorization": {
"id": "org-cat-550e8400-e29b-41d4-a716-446655440100",
"name": "MEDIUM_RISK_BUSINESS"
},
"addresses": {
"registered": {...},
"trading": {...}
},
"contacts": {
"email": "contact@acme-corp.com",
"phone": "+442071234567"
},
"representatives": [...],
"employees": [],
"directors": [],
"shareholders": [],
"createdAt": "2026-01-13T10:00:00.000Z"
}
}
```
**Key ID to Store:**
* `id` → Organization ID (for all subsequent calls)
**400 - Missing Required Fields:**
```json theme={null}
{
"code": 400,
"message": "Validation failed",
"data": {
"errors": [
{
"field": "registrationNumber",
"message": "Registration number is required"
},
{
"field": "taxId",
"message": "Tax ID is required"
}
]
}
}
```
**409 - Organization Already Exists:**
```json theme={null}
{
"code": 409,
"message": "Organization already exists",
"data": {
"error": "Duplicate organization",
"registrationNumber": "REG123456789",
"existingOrganizationId": "org-880e8400..."
}
}
```
***
## Required Fields
| Field | Required | Description |
| -------------------- | ----------- | --------------------------- |
| `legalName` | ✅ | Official legal name |
| `businessType` | ✅ | B2B, B2C, etc. |
| `registrationNumber` | ✅ | Company registration number |
| `taxId` | ✅ | Tax identification number |
| `incorporationDate` | ✅ | Date of incorporation |
| `registeredAddress` | ✅ | Official registered address |
| `contactEmail` | ✅ | Primary contact email |
| `vatNumber` | Conditional | Required if VAT registered |
***
## Ownership Validation
Representatives' ownership must total 100%:
```javascript theme={null}
function validateOwnership(representatives) {
const totalOwnership = representatives.reduce(
(sum, rep) => sum + rep.ownershipPercentage, 0
);
if (totalOwnership !== 100) {
throw new ValidationError(
`Total ownership must equal 100%. Current: ${totalOwnership}%`
);
}
}
```
***
## Default Admin Creation
After organization creation, a Kafka event triggers automatic admin user creation:
```
OrganizationCreatedEvent → Create Admin User
→ Send Activation Email
```
The default admin receives:
* Email: `contactEmail` from registration
* Roles: `ADMIN`, `ADMIN_USER`
* Status: `PENDING_ACTIVATION`
***
## Get Organization Details
**Endpoint:** `GET /api/v2.1/customer/organization/{organizationId}`
**Headers:**
```http theme={null}
Authorization: Bearer {jwt-token}
```
**Status:** `200 OK`
```json theme={null}
{
"code": 200,
"message": "Organization retrieved successfully",
"data": {
"id": "org-880e8400-e29b-41d4-a716-446655440110",
"legalName": "Acme Corporation Limited",
"status": "PENDING_VERIFICATION",
"employees": [],
"directors": [],
"shareholders": [],
"verificationStatus": null,
"activationStatus": null,
"wallet": {
"id": "wallet-aa0e8400...",
"status": "INACTIVE",
"iban": null
},
"metadata": {
"personnelCount": {
"employees": 0,
"directors": 0,
"shareholders": 0
},
"complianceStatus": {
"verification": "NOT_STARTED",
"consents": "NOT_STARTED",
"activation": "NOT_ELIGIBLE"
}
}
}
}
```
***
## Next Step
After registration, proceed to **Phase 2: Personnel Management** to add directors, shareholders, and employees.
Add directors, shareholders, and employees