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: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd

Authorization

string

required

Bearer token for authenticationExample: Bearer eyJ0eXAiOiJKV1QiLCJh...

Content-Type

string

required

Must be application/json

string

Response format (optional — defaults to application/json)Example: application/json, text/plain, */*

X-Forwarded-From

string

required

Source identifier for request origin trackingExample: e2e-test

User-Agent

string

required

Client application identifier — required by the global request filter for security analysis and device fingerprintingExample: YourApp/1.0 or Mozilla/5.0 (Windows NT 10.0; Win64; x64)

platform

string

required

Client platform identifier. Also accepted as sec-ch-ua-platformExample: web

deviceId

string

required

Unique device identifier for session tracking. Also accepted as X-Device-Id or device-idExample: 356938035643809

sec-ch-ua-platform

string

Browser client hint for OS platform (accepted alias for platform — automatically sent by modern browsers)Example: "Windows"

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: "admin@acmecorp.com"

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

string[]

required

Array of role identifiers for the admin userStandard Roles:

ACCOUNT_OWNER: Primary account owner
ADMIN: Administrative privileges

Example: ["ACCOUNT_OWNER", "ADMIN"]

customerCategory

object

Customer category assignment (optional)

Show customerCategory properties

string

Category database IDExample: "fs-cat-b2b-small-001"

name

string

Category display nameExample: "Small Business"

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

Business model type (optional based on implementation)Valid Values:

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

addresses

array

required

Array of organization addresses

Show address properties

type

string

required

Address type: "REGISTERED", "BILLING", "SHIPPING"

street

string

required

Street address

city

string

required

City name

postalCode

string

required

Postal/ZIP code

country

string

required

ISO 3166-1 alpha-2 country code

isPrimary

boolean

required

Whether this is the primary address

representatives

array

Array of company representatives (directors, shareholders)

Show representative properties

firstName

string

required

Representative’s first name

lastName

string

required

Representative’s last name

position

string

required

Position: "MANAGING_DIRECTOR", "SHAREHOLDER", "DIRECTOR"

string

required

Representative’s email address

phone

string

required

Phone number (E.164 format)

dateOfBirth

string

required

Date of birth (YYYY-MM-DD)

nationality

string

required

ISO 3166-1 alpha-2 country code

isPrimaryOwner

boolean

Whether this is a primary owner

Ownership percentage (0-100)

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

string[]

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

Primary role identifierValid Roles:

TRANSACTION_APPROVER
COMPLIANCE_OFFICER
ADMIN_USER
EMPLOYEE

roles

string[]

required

Array of role identifiers (can include multiple)

department

string

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

addresses

array

Employee addresses (see AddressDto)

telephoneNumbers

array

Employee phone numbers (see TelephoneNumberDto)

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/registration" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "email": "admin@acmecorp.com",
    "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": "admin@acmecorp.com",
        "phone": "+37060012345",
        "addresses": [
          {
            "type": "REGISTERED",
            "street": "123 Business Avenue",
            "city": "Vilnius",
            "postalCode": "LT-01001",
            "country": "Lithuania",
            "isPrimary": true
          }
        ],
        "representatives": [
          {
            "firstName": "John",
            "lastName": "Director",
            "position": "MANAGING_DIRECTOR",
            "email": "director@acmecorp.com",
            "phone": "+37060012346",
            "dateOfBirth": "1980-01-15",
            "nationality": "Lithuania",
            "isPrimaryOwner": false,
            "ownershipShare": 0
          },
          {
            "firstName": "Alice",
            "lastName": "Shareholder",
            "position": "SHAREHOLDER",
            "email": "shareholder@acmecorp.com",
            "phone": "+37060012348",
            "dateOfBirth": "1975-05-20",
            "nationality": "Lithuania",
            "isPrimaryOwner": true,
            "ownershipShare": 60
          }
        ]
      },
      "user": {
        "username": "admin@acmecorp.com",
        "email": "admin@acmecorp.com",
        "password": "SecurePassword123!",
        "status": "PENDING_ACTIVATION",
        "roles": ["ACCOUNT_OWNER", "ADMIN"]
      },
      "employees": [
        {
          "person": {
            "firstName": "Finance",
            "lastName": "Manager",
            "email": "finance@acmecorp.com",
            "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: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{
    "email": "admin@acmecorp.com",
    "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": "admin@acmecorp.com",
        "phone": "+37060012345",
        "businessType": "B2B",
        "addresses": [
          {
            "type": "REGISTERED_OFFICE",
            "street": "456 Tech Boulevard",
            "city": "Vilnius",
            "postalCode": "01234",
            "country": "LT",
            "isPrimary": true
          }
        ],
        "contacts": [
          {
            "type": "EMAIL",
            "value": "admin@acmecorp.com",
            "isPrimary": true
          },
          {
            "type": "PHONE",
            "value": "+37060012345",
            "isPrimary": true
          }
        ],
        "representatives": [
          {
            "firstName": "John",
            "lastName": "Doe",
            "position": "CEO",
            "email": "john.doe@acmecorp.com",
            "phone": "+37060012346",
            "dateOfBirth": "1980-05-15",
            "nationality": "LT",
            "isPrimaryOwner": true,
            "ownershipShare": 51.0
          },
          {
            "firstName": "Jane",
            "lastName": "Smith",
            "position": "CFO",
            "email": "jane.smith@acmecorp.com",
            "phone": "+37060012347",
            "dateOfBirth": "1985-08-20",
            "nationality": "LT",
            "isPrimaryOwner": false,
            "ownershipShare": 49.0
          }
        ]
      },
      "user": {
        "username": "admin@acmecorp.com",
        "email": "admin@acmecorp.com",
        "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": "admin@acmecorp.com",
    "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

Headers

User-Agent

string

required

Browser user agent

Example:

"Mozilla/5.0"

X-Forwarded-For

string

required

Client/application Ip address

Example:

"192.168.0.1"

X-Forwarded-From

string

required

Client/application identifier for request source tracking

Example:

"playground"

X-Tenant-ID

string

required

Tenant identifier

Example:

"97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"

platform

string

required

Client platform identifier. Also accepted as sec-ch-ua-platform

Example:

"web"

deviceId

string

required

Device identifier

Example:

"e2e-test-device"

Authorization

string

required

Bearer token from admin or customer session creation

Example:

"Bearer <token>"

Body

application/json

string

required

Example:

"admin@acmecorp-1773494453954-tt92yp.com"

password

string

required

Example:

"SecurePass123!"

matchingPassword

string

required

Example:

"SecurePass123!"

organizationCustomer

object

required

Show child attributes

organizationId

string

roleIds

string[]

Example:

["ACCOUNT_OWNER", "ADMIN"]

customerCategory

object

Show child attributes

Response

Organization registered successfully

Standard API response wrapper used by all endpoints

code

integer

HTTP status code

Example:

200

data

object

Response from organization registration

Show child attributes

message

string

Human-readable status message

Example:

"Success"

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

Headers

Body

Response

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

Headers

Body

Response

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