Organization Management API

Manage organization structure by adding directors, shareholders, and employees after initial registration.

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

Personnel Management Overview

After registering an organization, you must add personnel in the correct order: Recommended Order:

Employees (including at least one ADMIN_USER)
Directors (minimum 1 required for activation)
Shareholders (must total 100% ownership)

Dual Record Creation

When you add personnel, the system automatically creates two linked records:

Record Type	Purpose	Status
Organization Record	Links person to org with role/position	ACTIVE
Individual Customer	Creates login credentials	ACTIVE

Important: Each person gets auto-generated username and password returned in the response.

ADMIN_USER Role RequirementOrganizations of type BUSINESS_TYPE_CLIENT_TO_TENANT must have at least one employee with the ADMIN_USER role.If you attempt to add employees without this role first, you will receive a 400 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 your first employee has ADMIN_USER in their roles array.

Add Director

Add a director to an organization.

Endpoint

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

Path Parameters

organizationId

string

required

Organization UUID identifierExample: 2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4

Headers

X-Tenant-ID

string

required

Tenant identifier

Authorization

string

required

Bearer token for authentication

Content-Type

string

required

Must be application/json

Request Body

person

object

required

Director’s personal informationSee PersonDto for complete structure

Show person properties

firstName

string

required

Given name

lastName

string

required

Family name

string

required

Email address

dateOfBirth

string

required

ISO 8601 date (YYYY-MM-DD)

nationality

string

required

ISO 3166-1 alpha-2 country code

gender

integer

required

Gender code: 0 = Male, 1 = Female

placeOfBirth

string

Birth location

fullName

string

Complete name for display

role

string

required

Director role typeValid Values:

MANAGING_DIRECTOR
EXECUTIVE_DIRECTOR
NON_EXECUTIVE_DIRECTOR
BOARD_MEMBER

ownershipPercentage

number

Percentage ownership (0-100)Default: 0 if not specified

isPrimaryContact

boolean

Whether this director is the primary contactDefault: false

addresses

array

required

Array of address objectsSee AddressDto

telephoneNumbers

array

required

Array of telephone numbersSee TelephoneNumberDto

Code Example

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4/director" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person": {
      "firstName": "John",
      "lastName": "Director",
      "email": "[email protected]",
      "dateOfBirth": "1980-01-15",
      "nationality": "LT",
      "gender": 0,
      "placeOfBirth": "Vilnius",
      "fullName": "John Director"
    },
    "role": "MANAGING_DIRECTOR",
    "ownershipPercentage": 0,
    "isPrimaryContact": false,
    "addresses": [
      {
        "type": "HOME",
        "street": "123 Director Street",
        "city": "Vilnius",
        "postalCode": "12345",
        "country": "LT",
        "isPrimary": true
      }
    ],
    "telephoneNumbers": [
      {
        "number": "+37060012345",
        "country": "LT",
        "phoneType": 1,
        "operator": "Telia",
        "purpose": "personal",
        "isPrimary": true
      }
    ]
  }'

Response

{
  "code": 200,
  "message": "Success",
  "data": {
    "individual": {
      "password": "temporaryPassword123!",
      "customerId": "9620561e-a47c-419b-b0f7-ca204f827ef6",
      "tenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
      "userId": "bb9b9fee-205e-474d-8669-fd53e2189403",
      "email": "[email protected]",
      "username": "[email protected]"
    },
    "organization": {
      "individual": false,
      "organization": true,
      "adminEmployees": [],
      "organizationId": "ef4a8be6-602b-4b26-b81d-afa7d6d835fd",
      "tenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
      "shareholders": [],
      "employees": [],
      "directors": []
    }
  }
}

Important: The director is created as an individual customer linked to the organization. Save the temporary password to provide to the director for initial login.

Add Shareholders

Add one or more shareholders to an organization.

Endpoint

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

Path Parameters

organizationId

string

required

Organization UUID identifier

Request Body

The request body is an array of shareholder objects.

[n].person

object

required

Shareholder’s personal information (see PersonDto)

Ownership percentage (0-100)

Total share percentages across all shareholders should sum to 100

[n].isPrimaryContact

boolean

required

Whether this shareholder is the primary contact

[n].addresses

array

required

Array of address objects

[n].telephoneNumbers

array

required

Array of telephone numbers

Code Example

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4/shareholders" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "person": {
        "firstName": "Alice",
        "lastName": "Shareholder",
        "email": "[email protected]",
        "dateOfBirth": "1975-05-20",
        "nationality": "LT",
        "gender": 1,
        "placeOfBirth": "Kaunas",
        "fullName": "Alice Shareholder"
      },
      "sharePercentage": 60,
      "isPrimaryContact": true,
      "addresses": [
        {
          "type": "HOME",
          "street": "456 Shareholder Ave",
          "city": "Kaunas",
          "postalCode": "54321",
          "country": "LT",
          "isPrimary": true
        }
      ],
      "telephoneNumbers": [
        {
          "number": "+37060054321",
          "country": "LT",
          "phoneType": 1,
          "operator": "Tele2",
          "purpose": "personal",
          "isPrimary": true
        }
      ]
    },
    {
      "person": {
        "firstName": "Bob",
        "lastName": "Shareholder",
        "email": "[email protected]",
        "dateOfBirth": "1978-08-10",
        "nationality": "LT",
        "gender": 0,
        "placeOfBirth": "Klaipeda",
        "fullName": "Bob Shareholder"
      },
      "sharePercentage": 40,
      "isPrimaryContact": false,
      "addresses": [
        {
          "type": "HOME",
          "street": "789 Owner Street",
          "city": "Klaipeda",
          "postalCode": "98765",
          "country": "LT",
          "isPrimary": true
        }
      ],
      "telephoneNumbers": [
        {
          "number": "+37060098765",
          "country": "LT",
          "phoneType": 1,
          "operator": "Bite",
          "purpose": "personal",
          "isPrimary": true
        }
      ]
    }
  ]'

Response

{
  "code": 200,
  "message": "Success",
  "data": {
    "count": 2
  }
}

Add Employee

Add an employee to an organization.

Endpoint

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

Path Parameters

organizationId

string

required

Organization UUID identifier

Request Body

person

object

required

Employee’s personal information (see PersonDto)

role

string

required

Primary role identifierValid Roles:

ADMIN_USER (Required for at least one employee)
TRANSACTION_APPROVER
COMPLIANCE_OFFICER
EMPLOYEE

roles

array

required

Array of role identifiers (can include multiple roles)Example: ["COMPLIANCE_OFFICER", "TRANSACTION_APPROVER", "EMPLOYEE"]

department

string

Department nameExamples: "Finance", "Compliance", "Management"

addresses

array

required

Array of address objects

telephoneNumbers

array

required

Array of telephone numbers

Code Example

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4/employee" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person": {
      "firstName": "Jane",
      "lastName": "Compliance",
      "email": "[email protected]",
      "dateOfBirth": "1990-03-25",
      "nationality": "LT",
      "gender": 1,
      "placeOfBirth": "Vilnius",
      "fullName": "Jane Compliance"
    },
    "role": "ADMIN_USER",
    "roles": ["ADMIN_USER", "COMPLIANCE_OFFICER", "EMPLOYEE"],
    "department": "Compliance",
    "addresses": [
      {
        "type": "HOME",
        "street": "321 Employee Road",
        "city": "Vilnius",
        "postalCode": "11111",
        "country": "LT",
        "isPrimary": true
      }
    ],
    "telephoneNumbers": [
      {
        "number": "+37060011111",
        "country": "LT",
        "phoneType": 1,
        "operator": "Telia",
        "purpose": "personal",
        "isPrimary": true
      }
    ]
  }'

Response

{
  "code": 200,
  "message": "Success",
  "data": {
    "employeeId": "emp_123456",
    "userId": "user_789012",
    "email": "[email protected]",
    "status": "ACTIVE"
  }
}

Adding First EmployeeYour first employee must include the ADMIN_USER role. After adding an employee with ADMIN_USER, you can add other employees with different roles.

Organization Structure Best Practices

Required Roles

Role	Minimum Count	Purpose
`ADMIN_USER`	1+	System administration and user management
`COMPLIANCE_OFFICER`	1+ (recommended)	KYC/AML compliance management
`TRANSACTION_APPROVER`	1+ (recommended)	Financial transaction approvals

Typical Organization Structure

Organization
├── Directors (1-5)
│   └── MANAGING_DIRECTOR (primary)
├── Shareholders (1-10)
│   └── Share percentages sum to 100%
└── Employees (1-50)
    ├── ADMIN_USER (required, 1+)
    ├── COMPLIANCE_OFFICER (recommended)
    ├── TRANSACTION_APPROVER (recommended)
    └── EMPLOYEE (general staff)

Setup Workflow

Register Organization → Creates basic structure
Add Director(s) → Legal representatives
Add Shareholder(s) → Ownership structure
Add Employees → Must include ADMIN_USER
Verify Organization → KYB process
Accept Consents → Legal agreements
Activate Organization → Enable operations

Common Validation Errors

Missing ADMIN_USER Role

Problem: Cannot complete setup without ADMIN_USER Error:

{
  "code": 400,
  "message": "Missing required role 'ADMIN_USER' for BUSINESS_TYPE_CLIENT_TO_TENANT organization"
}

Solution: Ensure at least one employee has ADMIN_USER in their roles array:

{
  "role": "ADMIN_USER",
  "roles": ["ADMIN_USER", "EMPLOYEE"]
}

Duplicate Email

Problem: Email already exists in system Solution: Each person (director, shareholder, employee) must have a unique email address within the tenant. Problem: Shareholder percentages don’t sum to 100 Recommendation: While not strictly enforced, share percentages should typically sum to 100% for accurate ownership representation.

Role Hierarchy and Permissions

Employee Roles

Role	Permissions	Required for Activation
ADMIN_USER	Full organization access, can activate account	✅ Yes (minimum 1)
COMPLIANCE_OFFICER	Can approve verifications, activate organization	✅ Recommended
TRANSACTION_APPROVER	Can approve high-value transactions	No
EMPLOYEE	Basic access, transaction operations	No

Director Types

Type	Description	Authority Level
EXECUTIVE	Executive director with operational control	High
NON_EXECUTIVE	Advisory role, no day-to-day operations	Medium
INDEPENDENT	Independent oversight	Medium

API Schema References

For complete OpenAPI schema specifications:

Standard Headers

Complete HTTP headers reference

Organization Registration

Initial organization registration

Employees

Employee management operations

Directors

Director management operations

Shareholders

Shareholder management operations

Organization Activation

Activate organization after setup

Changelog

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

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Organization Management API

​Personnel Management Overview

​Dual Record Creation

​Add Director

​Endpoint

​Path Parameters

​Headers

​Request Body

​Code Example

​Response

​Add Shareholders

​Endpoint

​Path Parameters

​Request Body

​Code Example

​Response

​Add Employee

​Endpoint

​Path Parameters

​Request Body

​Code Example

​Response

​Organization Structure Best Practices

​Required Roles

​Typical Organization Structure

​Setup Workflow

​Common Validation Errors

​Missing ADMIN_USER Role

​Duplicate Email

​Invalid Share Percentage

​Role Hierarchy and Permissions

​Employee Roles

​Director Types

​API Schema References

​Related Endpoints

Standard Headers

Organization Registration

Employees

Directors

Shareholders

Organization Activation

​Changelog

Organization Management API

Personnel Management Overview

Dual Record Creation

Add Director

Endpoint

Path Parameters

Headers

Request Body

Code Example

Response

Add Shareholders

Endpoint

Path Parameters

Request Body

Code Example

Response

Add Employee

Endpoint

Path Parameters

Request Body

Code Example

Response

Organization Structure Best Practices

Required Roles

Typical Organization Structure

Setup Workflow

Common Validation Errors

Missing ADMIN_USER Role

Duplicate Email

Invalid Share Percentage

Role Hierarchy and Permissions

Employee Roles

Director Types

API Schema References

Related Endpoints

Changelog