Organization Registration API

Endpoint: POST /api/v2.1/customer/organization/registration

Important Registration BehaviorEmployees, directors, and shareholders included in the registration request are ignored by the API.The registration endpoint only creates:

Organization entity
Primary admin user account

You must use separate endpoints after registration:

POST /customer/organization/{id}/director - Add directors
POST /customer/organization/{id}/shareholders - Add shareholders
POST /customer/organization/{id}/employee - Add employees (requires ADMIN_USER role)

See Organization Management API for details.

Endpoint

POST /api/v2.1/customer/organization/registration

Headers

For complete details on authentication, compliance headers, and SDK implementation examples, refer to the Standard HTTP Headers reference documentation.

X-Tenant-ID

string

required

Tenant identifier for multi-tenant operationsExample: tenant_cloudvault

Authorization

string

required

Bearer token for authentication (admin privileges required)Example: Bearer eyJ0eXAiOiJKV1QiLCJh...

Content-Type

string

required

Must be application/json

X-Forwarded-For

string

required

Required for Compliance & AuditClient’s originating IP address for KYB compliance trackingExample: 192.168.1.100

User-Agent

string

required

Required for Compliance & AuditClient application identifier for security analysisExample: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36

Request Body

The request body uses a nested structure. All organization details must be inside the organizationCustomer.organization wrapper object.

Top-Level Fields

string

required

Primary admin user email address (must be unique)Example: "[email protected]"

password

string

required

Password for the admin user accountSecurity Requirements:

Minimum 8 characters
Must contain uppercase and lowercase
Must contain numbers and special characters

matchingPassword

string

required

Password confirmation (must match password)

roleIds

array

required

Array of role identifiers for the admin userStandard Roles:

ACCOUNT_OWNER: Primary account owner
ADMIN: Administrative privileges

Example: ["ACCOUNT_OWNER", "ADMIN"]

Organization Customer Object

organizationCustomer

object

required

Nested object containing all organization details

Show organizationCustomer properties

customerName

string

required

Display name for the organization customerExample: "Acme Corporation Ltd"

organization

object

required

Organization company details

Show organization properties

legalName

string

required

Full legal name of the companyExample: "Acme Corporation Limited"

tradingName

string

Trading or doing-business-as nameExample: "Acme Corp"

registrationNumber

string

required

Company registration numberExample: "REG-1234567890"

taxId

string

required

Tax identification numberExample: "TAX-1234567890"

incorporationDate

string

Date of incorporation (ISO 8601 format: YYYY-MM-DD)Example: "2015-03-20"

legalForm

string

required

Legal entity form/structureValid Values:

LIMITED_LIABILITY_COMPANY
PUBLIC_LIMITED_COMPANY
PRIVATE_LIMITED_COMPANY
PARTNERSHIP
SOLE_PROPRIETORSHIP

industry

string

required

Industry sectorCommon Values:

TECHNOLOGY
FINANCE
HEALTHCARE
RETAIL
MANUFACTURING
OTHER

businessDescription

string

Description of business activitiesExample: "Software development and consulting services"

website

string

Company website URLExample: "https://acmecorp.com"

string

required

Organization contact email

phone

string

required

Organization contact phone (E.164 format)Example: "+37060012345"

businessType

string

required

Business model typeValid Values:

B2B: Business-to-business
B2C: Business-to-consumer
B2B2C: Hybrid model

user

object

required

Admin user account information

Show user properties

username

string

required

Username for login (typically same as email)

string

required

Admin user’s email address

password

string

required

User’s password (will be hashed)

status

string

required

Initial user status (default: "PENDING_ACTIVATION")

roles

array

required

Array of role stringsExample: ["ACCOUNT_OWNER", "ADMIN"]

employees

array

Optional array of employee objects to create during registration

Employees can also be added after registration using the /customer/organization/{id}/employee endpoint.

Show employee properties

person

object

required

Employee personal information (see PersonDto in Common Types)

role

string

required

Primary role identifierValid Roles:

TRANSACTION_APPROVER
COMPLIANCE_OFFICER
ADMIN_USER
EMPLOYEE

roles

array

required

Array of role identifiers (can include multiple)

department

string

Department name (e.g., "Finance", "Compliance")

addresses

array

required

Employee addresses (see AddressDto)

telephoneNumbers

array

required

Employee phone numbers (see TelephoneNumberDto)

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/registration" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-For: 192.168.1.100" \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePassword123!",
    "matchingPassword": "SecurePassword123!",
    "roleIds": ["ACCOUNT_OWNER", "ADMIN"],
    "organizationCustomer": {
      "customerName": "Acme Corporation Ltd",
      "organization": {
        "legalName": "Acme Corporation Limited",
        "tradingName": "Acme Corp",
        "registrationNumber": "REG-1234567890",
        "taxId": "TAX-1234567890",
        "incorporationDate": "2015-03-20",
        "legalForm": "LIMITED_LIABILITY_COMPANY",
        "industry": "TECHNOLOGY",
        "businessDescription": "Software development and consulting services",
        "website": "https://acmecorp.com",
        "email": "[email protected]",
        "phone": "+37060012345",
        "businessType": "B2B"
      },
      "user": {
        "username": "[email protected]",
        "email": "[email protected]",
        "password": "SecurePassword123!",
        "status": "PENDING_ACTIVATION",
        "roles": ["ACCOUNT_OWNER", "ADMIN"]
      },
      "employees": [
        {
          "person": {
            "firstName": "Finance",
            "lastName": "Manager",
            "email": "[email protected]",
            "dateOfBirth": "1988-03-10",
            "nationality": "LT",
            "gender": 0,
            "placeOfBirth": "Kaunas",
            "fullName": "Finance Manager"
          },
          "role": "TRANSACTION_APPROVER",
          "roles": ["TRANSACTION_APPROVER", "EMPLOYEE"],
          "department": "Finance",
          "addresses": [
            {
              "type": "HOME",
              "street": "789 Finance Street",
              "city": "Vilnius",
              "postalCode": "01236",
              "country": "LT",
              "isPrimary": true
            }
          ],
          "telephoneNumbers": [
            {
              "number": "+37067890124",
              "country": "LT",
              "phoneType": 1,
              "operator": "Telia",
              "purpose": "personal",
              "isPrimary": true
            }
          ]
        }
      ]
    }
  }'

Advanced: Registration with Categorization

For medium or high-risk business customers, you can include categorization with feature parametrization to define appropriate risk controls during registration. This enables automated compliance and transaction monitoring from day one.

How It Works

Get Categorization Hierarchy - Call GET /customer/individual/categorization/hierarchy/ (use individual endpoint for organizations too)
Filter Business Categories - Client-side filter for categories with “BUSINESS”, “ORGANIZATION”, “B2B”
Build Feature Relations - Map features with business-appropriate values
Include in Registration - Add categorization object to organizationCustomer

Example: Business Registration with Categorization

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/registration" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-For: 192.168.1.100" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePassword123!",
    "matchingPassword": "SecurePassword123!",
    "roleIds": ["ACCOUNT_OWNER", "ADMIN"],
    "customerCategory": {
      "id": "business-medium-risk-7f9a",
      "name": "BUSINESS_MEDIUM_RISK"
    },
    "organizationCustomer": {
      "customerName": "Acme Corporation Ltd",
      "organization": {
        "legalName": "Acme Corporation Limited",
        "tradingName": "Acme Corp",
        "registrationNumber": "REG-1234567890",
        "taxId": "TAX-1234567890",
        "incorporationDate": "2015-03-20",
        "legalForm": "LIMITED_LIABILITY_COMPANY",
        "industry": "TECHNOLOGY",
        "businessDescription": "Software development and consulting services",
        "website": "https://acmecorp.com",
        "email": "[email protected]",
        "phone": "+37060012345",
        "businessType": "B2B",
        "addresses": [
          {
            "type": "REGISTERED_OFFICE",
            "street": "456 Tech Boulevard",
            "city": "Vilnius",
            "postalCode": "01234",
            "country": "LT",
            "isPrimary": true
          }
        ],
        "contacts": [
          {
            "type": "EMAIL",
            "value": "[email protected]",
            "isPrimary": true
          },
          {
            "type": "PHONE",
            "value": "+37060012345",
            "isPrimary": true
          }
        ],
        "representatives": [
          {
            "firstName": "John",
            "lastName": "Doe",
            "position": "CEO",
            "email": "[email protected]",
            "phone": "+37060012346",
            "dateOfBirth": "1980-05-15",
            "nationality": "LT",
            "isPrimaryOwner": true,
            "ownershipShare": 51.0
          },
          {
            "firstName": "Jane",
            "lastName": "Smith",
            "position": "CFO",
            "email": "[email protected]",
            "phone": "+37060012347",
            "dateOfBirth": "1985-08-20",
            "nationality": "LT",
            "isPrimaryOwner": false,
            "ownershipShare": 49.0
          }
        ]
      },
      "user": {
        "username": "[email protected]",
        "email": "[email protected]",
        "password": "SecurePassword123!",
        "status": "PENDING_ACTIVATION",
        "roles": ["ACCOUNT_OWNER", "ADMIN"]
      },
      "categorization": {
        "id": "business-medium-risk-7f9a",
        "name": "BUSINESS_MEDIUM_RISK",
        "description": "Medium risk business customer",
        "isActive": true,
        "categoryFeatureRelations": [
          {
            "feature": {
              "id": "business-risk-assessment-3c4d",
              "code": "BUSINESS_RISK_ASSESSMENT"
            },
            "enabled": true,
            "parametrization": [
              {
                "name": "BUSINESS_RISK_LEVEL",
                "value": "MEDIUM"
              },
              {
                "name": "BUSINESS_RISK_SCORE",
                "value": "60"
              },
              {
                "name": "ANNUAL_REVENUE",
                "value": "1000000"
              },
              {
                "name": "EMPLOYEE_COUNT",
                "value": "25"
              },
              {
                "name": "SANCTIONS_CHECK",
                "value": "STANDARD"
              }
            ]
          },
          {
            "feature": {
              "id": "business-transaction-limits-7e2f",
              "code": "BUSINESS_TRANSACTION_LIMITS"
            },
            "enabled": true,
            "parametrization": [
              {
                "name": "MONTHLY_LIMIT",
                "value": "50000"
              },
              {
                "name": "DAILY_LIMIT",
                "value": "10000"
              },
              {
                "name": "PER_TRANSACTION_LIMIT",
                "value": "5000"
              }
            ]
          },
          {
            "feature": {
              "id": "business-verification-requirements-9a1b",
              "code": "BUSINESS_VERIFICATION_REQUIREMENTS"
            },
            "enabled": true,
            "parametrization": [
              {
                "name": "BUSINESS_VERIFICATION",
                "value": "REQUIRED"
              },
              {
                "name": "BENEFICIAL_OWNER_VERIFICATION",
                "value": "REQUIRED"
              },
              {
                "name": "DOCUMENT_VERIFICATION",
                "value": "REQUIRED"
              }
            ]
          }
        ]
      }
    }
  }'

Categorization Benefits for Business Customers

Why Use Categorization During Organization Registration?

Business Risk Assessment - Define risk profile based on annual revenue, employee count, industry
Transaction Limits - Set appropriate limits for business operations (typically higher than individual)
Verification Requirements - Specify KYB checks (business verification, UBO verification, document verification)
Compliance Automation - Ensure AML/CTF requirements are met from day one
Monitoring Frequency - Schedule transaction monitoring appropriate for business risk level

Smart Value Selection for Business

Production-proven patterns for business categorization:

Parameter	Smart Selection Logic	Typical Values
BUSINESS_RISK_LEVEL	Match “MEDIUM”, “STANDARD”	MEDIUM, STANDARD, VERIFIED
BUSINESS_RISK_SCORE	Match 50-70 range for medium risk	60, 55, 65
ANNUAL_REVENUE	Match 500K-2M range	1000000, 500000, 2000000
EMPLOYEE_COUNT	Match 10-50 range	25, 20, 30
MONTHLY_LIMIT	Match 40K-60K for medium risk	50000, 40000, 60000
DAILY_LIMIT	Match 8K-12K for medium risk	10000, 8000, 12000
SANCTIONS_CHECK	Match “STANDARD” or “PERIODIC”	STANDARD, PERIODIC, ENHANCED

Production Pattern: Use the individual categorization endpoint (GET /customer/individual/categorization/hierarchy/{tenantId}) and filter client-side for business categories. The organization-specific endpoint returns 404 in production.

UBO Ownership Validation: If including representatives with ownershipShare, ensure the total adds up to 100%. The API may validate this during verification.

Response

{
  "code": 200,
  "message": "Organization registered successfully. Default admin will be created automatically. Use separate endpoints to add employees, directors, and shareholders.",
  "data": {
    "individual": false,
    "organization": true,
    "adminEmployees": [],
    "id": "ef4a8be6-602b-4b26-b81d-afa7d6d835fd",
    "organizationId": "ef4a8be6-602b-4b26-b81d-afa7d6d835fd",
    "tenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
    "email": "[email protected]",
    "shareholders": [],
    "employees": [],
    "directors": []
  }
}

Why are the arrays empty?Even if you send employees, directors, or shareholders in the registration request, they will not be processed. The API intentionally returns empty arrays to indicate you must use the dedicated management endpoints.This design ensures proper validation and role requirements for each organizational role type.

Next Steps After Registration

1. Add Directors

POST /api/v2.1/customer/organization/{organizationId}/director

See Add Director for details.

2. Add Shareholders

POST /api/v2.1/customer/organization/{organizationId}/shareholders

See Add Shareholders for details.

3. Add Additional Employees

POST /api/v2.1/customer/organization/{organizationId}/employee

Important: At least one employee must have the ADMIN_USER role.

4. Complete Verification

POST /api/v2.1/customer/organization/{organizationId}/verify

See Business Verification for details.

5. Accept Consents

Required consents:

Terms and Conditions
Privacy Policy
Data Processing

See Consent Management for details.

6. Activate Organization

POST /api/v2.1/customer/organization/{organizationId}/activation

See Organization Activation for details.

Common Validation Errors

Missing ADMIN_USER Role

Error:

{
  "code": 400,
  "message": "Missing required role 'ADMIN_USER' for BUSINESS_TYPE_CLIENT_TO_TENANT organization. At least one employee must have this role."
}

Solution: Ensure at least one employee has the ADMIN_USER role.

Duplicate Registration Number

Error:

{
  "code": 409,
  "message": "Organization with registration number 'REG-123' already exists"
}

Solution: Registration numbers must be unique within the tenant.

Invalid Nested Structure

Error:

{
  "code": 400,
  "message": "organizationCustomer is required"
}

Solution: Use the nested structure with organizationCustomer.organization.*

API Schema Reference

For the complete OpenAPI schema specification of this endpoint, including all request and response structures, see the API Schema Mapping document.

Standard Headers

Complete HTTP headers reference for compliance

Organization Management

Add directors, shareholders, and employees

Organization Activation

Activate organization after verification

Business Verification

Complete KYC/KYB verification

Changelog

Version	Date	Changes
v2.1	2026-01-13	Initial release

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

Organization Registration API

Organization Registration API

Endpoint

Headers

Request Body

Top-Level Fields

Organization Customer Object

Code Examples

Advanced: Registration with Categorization

How It Works

Example: Business Registration with Categorization

Categorization Benefits for Business Customers

Smart Value Selection for Business

Response

Next Steps After Registration

1. Add Directors

2. Add Shareholders

3. Add Additional Employees

4. Complete Verification

5. Accept Consents

6. Activate Organization

Common Validation Errors

Missing ADMIN_USER Role

Duplicate Registration Number

Invalid Nested Structure

API Schema Reference

Standard Headers

Organization Management

Organization Activation

Business Verification

Changelog

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Organization Registration API

​Endpoint

​Headers

​Request Body

​Top-Level Fields

​Organization Customer Object

​Code Examples

​Advanced: Registration with Categorization

​How It Works

​Example: Business Registration with Categorization

​Categorization Benefits for Business Customers

​Smart Value Selection for Business

​Response

​Next Steps After Registration

​1. Add Directors

​2. Add Shareholders

​3. Add Additional Employees

​4. Complete Verification

​5. Accept Consents

​6. Activate Organization

​Common Validation Errors

​Missing ADMIN_USER Role

​Duplicate Registration Number

​Invalid Nested Structure

​API Schema Reference

​Related Endpoints

Standard Headers

Organization Management

Organization Activation

Business Verification

​Changelog

Organization Registration API

Endpoint

Headers

Request Body

Top-Level Fields

Organization Customer Object

Code Examples

Advanced: Registration with Categorization

How It Works

Example: Business Registration with Categorization

Categorization Benefits for Business Customers

Smart Value Selection for Business

Response

Next Steps After Registration

1. Add Directors

2. Add Shareholders

3. Add Additional Employees

4. Complete Verification

5. Accept Consents

6. Activate Organization

Common Validation Errors

Missing ADMIN_USER Role

Duplicate Registration Number

Invalid Nested Structure

API Schema Reference

Related Endpoints

Changelog