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

# Organization Management API

> 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 theme={null}
  {
    "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 theme={null}
  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 theme={null}
  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 theme={null}
  {
    "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 theme={null}
  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 theme={null}
  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 theme={null}
  {
    "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 theme={null}
  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 theme={null}
  {
    "code": 200,
    "message": "Success",
    "data": {
      "employeeId": "emp_123456",
      "userId": "user_789012",
      "email": "compliance@acmecorp.com",
      "status": "ACTIVE"
    }
  }
  ```

  ```json 400 - Missing ADMIN_USER Role theme={null}
  {
    "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 theme={null}
{
  "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 theme={null}
{
  "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 |