URL: /baas/api/reference/customer-apis/organization/management

---
title: 'Organization Management API'
description: 'Manage directors, shareholders, and employees for organizations'
---

# Organization Management API

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

<Note>
  For complete details on authentication and headers, refer to the [Standard HTTP Headers](../../schemas/standard-headers) reference documentation.
</Note>

## Personnel Management Overview

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

**Recommended Order:**
1. **Employees** (including at least one ADMIN_USER)
2. **Directors** (minimum 1 required for activation)
3. **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.

<Warning>
  **ADMIN_USER Role Requirement**
  
  Organizations 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:
  ```json
  {
    "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.
</Warning>

---

## Add Director

Add a director to an organization.

### Endpoint

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

### Path Parameters

<ParamField path="organizationId" type="string" required>
  Organization UUID identifier
  
  Example: `2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4`
</ParamField>

### Headers

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Request Body

<ParamField body="person" type="object" required>
  Director's personal information
  
  See [PersonDto](../../schemas/common-types#persondto) for complete structure
  
  <Expandable title="person properties">
    <ParamField body="firstName" type="string" required>
      Given name
    </ParamField>
    
    <ParamField body="lastName" type="string" required>
      Family name
    </ParamField>
    
    <ParamField body="email" type="string" required>
      Email address
    </ParamField>
    
    <ParamField body="dateOfBirth" type="string" required>
      ISO 8601 date (YYYY-MM-DD)
    </ParamField>
    
    <ParamField body="nationality" type="string" required>
      ISO 3166-1 alpha-2 country code
    </ParamField>
    
    <ParamField body="gender" type="integer" required>
      Gender code: `0` = Male, `1` = Female
    </ParamField>
    
    <ParamField body="placeOfBirth" type="string">
      Birth location
    </ParamField>
    
    <ParamField body="fullName" type="string">
      Complete name for display
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="role" type="string" required>
  Director role type
  
  **Valid Values:**
  - `MANAGING_DIRECTOR`
  - `EXECUTIVE_DIRECTOR`
  - `NON_EXECUTIVE_DIRECTOR`
  - `BOARD_MEMBER`
</ParamField>

<ParamField body="ownershipPercentage" type="number">
  Percentage ownership (0-100)
  
  Default: `0` if not specified
</ParamField>

<ParamField body="isPrimaryContact" type="boolean">
  Whether this director is the primary contact
  
  Default: `false`
</ParamField>

<ParamField body="addresses" type="array" required>
  Array of address objects
  
  See [AddressDto](../../schemas/common-types#addressdto)
</ParamField>

<ParamField body="telephoneNumbers" type="array" required>
  Array of telephone numbers
  
  See [TelephoneNumberDto](../../schemas/common-types#telephonenumberdto)
</ParamField>

### Code Example

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4/director" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "person": {
      "firstName": "John",
      "lastName": "Director",
      "email": "director@acmecorp.com",
      "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
      }
    ]
  }'
```

```javascript JavaScript
const addDirector = async (organizationId) => {
  const response = await fetch(
    `https://sandbox.finhub.cloud/api/v2.1/customer/organization/${organizationId}/director`,
    {
      method: 'POST',
      headers: {
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'Authorization': `Bearer ${token}`,
        'X-Forwarded-From': 'e2e-test',
        'platform': 'web',
        'deviceId': '356938035643809'
      },
      body: JSON.stringify({
        person: {
          firstName: 'John',
          lastName: 'Director',
          email: 'director@acmecorp.com',
          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
        }]
      })
    }
  );

  return response.json();
};
```
</CodeGroup>

### Response

<ResponseExample>
```json 200 - Success
{
  "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": "director@acmecorp.com",
      "username": "director@acmecorp.com"
    },
    "organization": {
      "individual": false,
      "organization": true,
      "adminEmployees": [],
      "organizationId": "ef4a8be6-602b-4b26-b81d-afa7d6d835fd",
      "tenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
      "shareholders": [],
      "employees": [],
      "directors": []
    }
  }
}
```
</ResponseExample>

<Info>
  **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.
</Info>

---

## Add Shareholders

Add one or more shareholders to an organization.

### Endpoint

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

### Path Parameters

<ParamField path="organizationId" type="string" required>
  Organization UUID identifier
</ParamField>

### Request Body

The request body is an **array** of shareholder objects.

<ParamField body="[n].person" type="object" required>
  Shareholder's personal information (see PersonDto)
</ParamField>

<ParamField body="[n].sharePercentage" type="number" required>
  Ownership percentage (0-100)
  
  <Warning>Total share percentages across all shareholders should sum to 100</Warning>
</ParamField>

<ParamField body="[n].isPrimaryContact" type="boolean" required>
  Whether this shareholder is the primary contact
</ParamField>

<ParamField body="[n].addresses" type="array" required>
  Array of address objects
</ParamField>

<ParamField body="[n].telephoneNumbers" type="array" required>
  Array of telephone numbers
</ParamField>

### Code Example

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4/shareholders" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '[
    {
      "person": {
        "firstName": "Alice",
        "lastName": "Shareholder",
        "email": "shareholder1@acmecorp.com",
        "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": "shareholder2@acmecorp.com",
        "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
        }
      ]
    }
  ]'
```

```javascript JavaScript
const addShareholders = async (organizationId, shareholders) => {
  const response = await fetch(
    `https://sandbox.finhub.cloud/api/v2.1/customer/organization/${organizationId}/shareholders`,
    {
      method: 'POST',
      headers: {
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'Authorization': `Bearer ${token}`,
        'X-Forwarded-From': 'e2e-test',
        'platform': 'web',
        'deviceId': '356938035643809'
      },
      body: JSON.stringify(shareholders)
    }
  );

  return response.json();
};
```
</CodeGroup>

### Response

<ResponseExample>
```json 200 - Success
{
  "code": 200,
  "message": "Success",
  "data": {
    "count": 2
  }
}
```
</ResponseExample>

---

## Add Employee

Add an employee to an organization.

### Endpoint

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

### Path Parameters

<ParamField path="organizationId" type="string" required>
  Organization UUID identifier
</ParamField>

### Request Body

<ParamField body="person" type="object" required>
  Employee's personal information (see PersonDto)
</ParamField>

<ParamField body="role" type="string" required>
  Primary role identifier
  
  **Valid Roles:**
  - `ADMIN_USER` (Required for at least one employee)
  - `TRANSACTION_APPROVER`
  - `COMPLIANCE_OFFICER`
  - `EMPLOYEE`
</ParamField>

<ParamField body="roles" type="string[]" required>
  Array of role identifiers (can include multiple roles)
  
  Example: `["COMPLIANCE_OFFICER", "TRANSACTION_APPROVER", "EMPLOYEE"]`
</ParamField>

<ParamField body="department" type="string">
  Department name
  
  Examples: `"Finance"`, `"Compliance"`, `"Management"`
</ParamField>

<ParamField body="addresses" type="array" required>
  Array of address objects
</ParamField>

<ParamField body="telephoneNumbers" type="array" required>
  Array of telephone numbers
</ParamField>

### Code Example

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4/employee" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "person": {
      "firstName": "Jane",
      "lastName": "Compliance",
      "email": "compliance@acmecorp.com",
      "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
      }
    ]
  }'
```
</CodeGroup>

### Response

<ResponseExample>
```json 200 - Success
{
  "code": 200,
  "message": "Success",
  "data": {
    "employeeId": "emp_123456",
    "userId": "user_789012",
    "email": "compliance@acmecorp.com",
    "status": "ACTIVE"
  }
}
```

```json 400 - Missing ADMIN_USER Role
{
  "code": 400,
  "message": "Missing required role 'ADMIN_USER' for BUSINESS_TYPE_CLIENT_TO_TENANT organization. At least one employee must have this role."
}
```
</ResponseExample>

<Info>
  **Adding First Employee**
  
  Your first employee **must** include the `ADMIN_USER` role. After adding an employee with ADMIN_USER, you can add other employees with different roles.
</Info>

---

## 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

1. **Register Organization** → Creates basic structure
2. **Add Director(s)** → Legal representatives
3. **Add Shareholder(s)** → Ownership structure
4. **Add Employees** → Must include ADMIN_USER
5. **Verify Organization** → KYB process
6. **Accept Consents** → Legal agreements
7. **Activate Organization** → Enable operations

---

## Common Validation Errors

### Missing ADMIN_USER Role

**Problem:** Cannot complete setup without ADMIN_USER

**Error:**
```json
{
  "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:
```json
{
  "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.

### Invalid Share Percentage

**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:

- [Add Organization Employee](../../../../doc/mint/API_SCHEMA_MAPPING#add-organization-employee)
- [Add Organization Director](../../../../doc/mint/API_SCHEMA_MAPPING#add-organization-director)
- [Add Organization Shareholders](../../../../doc/mint/API_SCHEMA_MAPPING#add-organization-shareholders)

---

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Standard Headers" icon="list" href="../../schemas/standard-headers">
    Complete HTTP headers reference
  </Card>
  
  <Card title="Organization Registration" icon="building" href="./registration">
    Initial organization registration
  </Card>
  
  <Card title="Employees" icon="users" href="./employees">
    Employee management operations
  </Card>
  
  <Card title="Directors" icon="user-tie" href="./directors">
    Director management operations
  </Card>
  
  <Card title="Shareholders" icon="users-viewfinder" href="./shareholders">
    Shareholder management operations
  </Card>
  
  <Card title="Organization Activation" icon="check-circle" href="./activation">
    Activate organization after setup
  </Card>
</CardGroup>

---

## Changelog

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