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

> Activate verified organization accounts

export function RequiredRunnerHeadersWithUserContext() {
  return <>
      <RequiredRunnerHeaders />
      <ParamField header="X-User-ID" type="string" required>
        User executing privileged organization action
      </ParamField>
      <ParamField header="X-User-Roles" type="string" required>
        Comma-separated roles (example: `ADMIN_USER,COMPLIANCE_OFFICER`)
      </ParamField>
    </>;
}

# Organization Activation API

Activate a verified organization account to enable wallet operations and financial transactions.

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

<Warning>
  **Role Requirement:** Only users with **COMPLIANCE\_OFFICER** or **ADMIN\_USER** roles can activate an organization.
</Warning>

***

## Prerequisites Checklist (14-Step Validation)

Before attempting activation, the system validates **14 prerequisites**:

### 1. Organization Structure (4 checks)

* [ ] Organization registered and status = `PENDING_ACTIVATION`
* [ ] At least 1 director added
* [ ] At least 1 employee with **ADMIN\_USER** role
* [ ] Total shareholder ownership = **100%** exactly

### 2. Verification (3 checks)

* [ ] KYB verification completed
* [ ] Verification status = **APPROVED**
* [ ] All personnel (directors, UBOs) verified

### 3. Consents (3 checks)

* [ ] Terms and Conditions accepted
* [ ] Privacy Policy accepted
* [ ] Data Processing Agreement accepted

### 4. Documents (2 checks)

* [ ] All required corporate documents uploaded
* [ ] All documents status = **VERIFIED**

### 5. Authorization (2 checks)

* [ ] User has **COMPLIANCE\_OFFICER** or **ADMIN\_USER** role
* [ ] User is linked to the organization

<Info>
  **Check Activation Readiness:** Use `GET /{organizationId}/activation/readiness` to validate all prerequisites before attempting activation.
</Info>

***

## Endpoint

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

***

## Headers

<RequiredRunnerHeadersWithUserContext />

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

  Example: `97e7ff29-15f3-49ef-9681-3bbfcce4f6cd`
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication (admin privileges required)
</ParamField>

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

<ParamField header="Accept" type="string">
  Response format (optional — defaults to `application/json`)

  Example: `application/json, text/plain, */*`
</ParamField>

<ParamField header="X-User-ID" type="string" required>
  User ID of the admin performing activation

  Example: `e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a`
</ParamField>

<ParamField header="X-User-Roles" type="string" required>
  Comma-separated list of user roles

  Example: `ADMIN_USER,COMPLIANCE_OFFICER`
</ParamField>

<ParamField header="X-Forwarded-From" type="string" required>
  Source identifier for request origin tracking

  Example: `e2e-test`
</ParamField>

<ParamField header="User-Agent" type="string" required>
  Client application identifier — required by the global request filter

  Example: `YourApp/1.0` or `Mozilla/5.0 (Windows NT 10.0; Win64; x64)`
</ParamField>

<ParamField header="platform" type="string" required>
  Client platform identifier. Also accepted as `sec-ch-ua-platform`

  Example: `web`
</ParamField>

<ParamField header="deviceId" type="string" required>
  Unique device identifier for session tracking. Also accepted as `X-Device-Id` or `device-id`

  Example: `356938035643809`
</ParamField>

***

## Path Parameters

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

  Example: `ef4a8be6-602b-4b26-b81d-afa7d6d835fd`
</ParamField>

***

## Request Body

<ParamField body="activationReason" type="string" required>
  Reason for activation

  Example: `"Organization account activation after KYB completion"`
</ParamField>

<ParamField body="additionalInfo" type="object">
  Optional metadata about the activation

  <Expandable title="additionalInfo properties">
    <ParamField body="userId" type="string">
      User ID performing the activation

      Example: `"87b3af37-4ac1-402b-a0ea-53cfdc695e02"`
    </ParamField>

    <ParamField body="activationCode" type="string">
      Activation code for verification

      Example: `"E2E_TEST"`
    </ParamField>
  </Expandable>
</ParamField>

***

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/ef4a8be6-602b-4b26-b81d-afa7d6d835fd/activation" \
    -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-User-ID: e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a" \
    -H "X-User-Roles: ADMIN_USER,COMPLIANCE_OFFICER" \
    -H "X-Forwarded-From: e2e-test" \
    -H "platform: web" \
    -H "deviceId: 356938035643809" \
    -d '{
      "activationReason": "E2E Test Activation",
      "additionalInfo": {
        "userId": "87b3af37-4ac1-402b-a0ea-53cfdc695e02",
        "activationCode": "E2E_TEST"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const activateOrganization = async (organizationId, userId, userRoles) => {
    const response = await fetch(
      `https://sandbox.finhub.cloud/api/v2.1/customer/organization/${organizationId}/activation`,
      {
        method: 'POST',
        headers: {
          'Accept': 'application/json, text/plain, */*',
          'Content-Type': 'application/json',
          'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
          'Authorization': `Bearer ${accessToken}`,
          'X-User-ID': userId,
          'X-User-Roles': userRoles,
          'X-Forwarded-From': 'e2e-test',
          'platform': 'web',
          'deviceId': '356938035643809'
        },
        body: JSON.stringify({
          activationReason: 'E2E Test Activation',
          additionalInfo: {
            userId: userId,
            activationCode: 'E2E_TEST'
          }
        })
      }
    );

    return response.json();
  };
  ```

  ```python Python theme={null}
  import requests

  def activate_organization(organization_id, user_id, user_roles):
      url = f'https://sandbox.finhub.cloud/api/v2.1/customer/organization/{organization_id}/activation'
      
      headers = {
          'Accept': 'application/json, text/plain, */*',
          'Content-Type': 'application/json',
          'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
          'Authorization': f'Bearer {access_token}',
          'X-User-ID': user_id,
          'X-User-Roles': user_roles,
          'X-Forwarded-From': 'e2e-test',
          'platform': 'web',
          'deviceId': '356938035643809'
      }
      
      payload = {
          'activationReason': 'Organization account activation after KYB completion',
          'additionalInfo': {
              'testRun': False,
              'activatedBy': 'Admin User'
          }
      }
      
      response = requests.post(url, headers=headers, json=payload)
      return response.json()
  ```
</CodeGroup>

***

## Response

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "code": 200,
    "message": "Organization activated successfully",
    "data": {
      "wallet": {
        "walletId": "49a2fe3a-a9df-48dc-9da3-e9dff8eb4968",
        "balance": "0.00",
        "currency": "EUR",
        "id": "49a2fe3a-a9df-48dc-9da3-e9dff8eb4968",
        "status": "ACTIVE"
      },
      "iban": "LT963500070344952515",
      "activation": {
        "message": "Organization activated successfully",
        "status": "ACTIVE",
        "activatedAt": "2026-01-13T10:04:12.830711352",
        "warnings": [
          "No employees found - consider adding employees with required roles"
        ]
      }
    }
  }
  ```

  ```json 400 - Missing Prerequisites theme={null}
  {
    "code": 400,
    "message": "Organization verification not completed"
  }
  ```

  ```json 400 - Missing Consents theme={null}
  {
    "code": 400,
    "message": "Required consents not accepted. Please accept Terms, Privacy, and Data Processing consents."
  }
  ```
</ResponseExample>

***

## Response Fields

<ResponseField name="code" type="integer">
  HTTP status code
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

<ResponseField name="data" type="object">
  Activation result data

  <Expandable title="data properties">
    <ResponseField name="wallet" type="object">
      Created wallet information

      <Expandable title="wallet properties">
        <ResponseField name="walletId" type="string">
          Unique wallet identifier
        </ResponseField>

        <ResponseField name="balance" type="string">
          Initial balance (formatted)
        </ResponseField>

        <ResponseField name="currency" type="string">
          Wallet currency (typically EUR)
        </ResponseField>

        <ResponseField name="status" type="string">
          Wallet status: `ACTIVE`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="iban" type="string">
      Generated IBAN for the organization

      Example: `LT963500070344952515`
    </ResponseField>

    <ResponseField name="activation" type="object">
      Activation details

      <Expandable title="activation properties">
        <ResponseField name="status" type="string">
          Activation status: `ACTIVE`
        </ResponseField>

        <ResponseField name="activatedAt" type="string">
          ISO 8601 timestamp of activation
        </ResponseField>

        <ResponseField name="message" type="string">
          Activation message
        </ResponseField>

        <ResponseField name="warnings" type="array">
          Array of warning messages (if any)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Common Activation Warnings

The API may return warnings in the activation response. These warnings do not prevent activation but indicate configuration issues that should be addressed:

| Warning                                                              | Meaning                           | Action Required                                |
| -------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------- |
| `No employees found - consider adding employees with required roles` | Organization has no employees     | Add employees for production use               |
| `Missing ADMIN_USER role employee`                                   | No employee with ADMIN\_USER role | Add employee with ADMIN\_USER role immediately |
| `No directors found`                                                 | Organization has no directors     | Add at least one director                      |
| `Shareholder ownership does not sum to 100%`                         | Incomplete ownership structure    | Review shareholder percentages                 |

<Warning>
  **Production Readiness**

  While warnings do not prevent activation, organizations should address all warnings before production use to ensure proper governance and compliance.
</Warning>

***

## Organization vs Individual Activation

Key differences between organization and individual activation:

| Aspect              | Individual              | Organization                         |
| ------------------- | ----------------------- | ------------------------------------ |
| Request Body        | `code`, `userId`        | `activationReason`, `additionalInfo` |
| Verification Method | Email verification code | Admin-initiated after KYB            |
| Response Warnings   | No warnings             | May include structural warnings      |
| Required Headers    | Standard auth           | `X-User-ID`, `X-User-Roles` required |
| Prerequisites       | KYC, Consents           | KYB, Consents, Team Structure        |

***

## Post-Activation Operations

After successful activation, the organization can:

1. **Check Balance**
   ```
   GET /api/v2.1/fintrans/{walletId}/balance
   ```

2. **Add Beneficiaries**
   ```
   POST /api/v2.1/fintrans/{walletId}/beneficiaries
   ```

3. **Prepare Transactions**
   ```
   POST /api/v2.1/fintrans/{walletId}/types/topup/prepare
   POST /api/v2.1/transfers/{walletId}/prepare
   ```

4. **Execute Transactions**
   ```
   POST /api/v2.1/fintrans/{walletId}/types/topup/execute
   ```

See [Financial Operations](../../financial-operations/account-operations) for complete transaction workflows.

***

## Troubleshooting

### Verification Not Completed

**Error:**

```json theme={null}
{
  "code": 400,
  "message": "Organization verification not completed"
}
```

**Solution:** Ensure KYB verification is completed and approved before activation.

### Missing Consents

**Error:**

```json theme={null}
{
  "code": 400,
  "message": "Required consents not accepted"
}
```

**Solution:** Accept all three required consents:

* Terms and Conditions: `POST /consents/terms`
* Privacy Policy: `POST /consents/privacy`
* Data Processing: `POST /consents/data-processing`

### Missing ADMIN\_USER Role

**Error:**

```json theme={null}
{
  "code": 400,
  "message": "Organization must have at least one employee with ADMIN_USER role"
}
```

**Solution:** Add an employee with `ADMIN_USER` role before activation.

***

## What Happens During Activation

When activation is successful, the system performs these **6 automatic actions**:

| Step | Action                      | Details                                                              |
| ---- | --------------------------- | -------------------------------------------------------------------- |
| 1    | **Status Update**           | Organization status changes from `PENDING_ACTIVATION` → `ACTIVE`     |
| 2    | **Wallet Activation**       | Default EUR wallet created and activated                             |
| 3    | **IBAN/BIC Assignment**     | Unique IBAN and BIC assigned to organization account                 |
| 4    | **Category Limits Applied** | Transaction limits based on categorization (daily, monthly, per-txn) |
| 5    | **Features Enabled**        | Category features activated (transfers, payments, topups)            |
| 6    | **Audit Trail**             | Complete activation log created with timestamps and user info        |

***

## What Happens After Activation

Once activated, the organization can:

✅ **Financial Operations:**

* Check wallet balance
* Add beneficiaries
* Create payment consents
* Execute transfers (SEPA, SWIFT)
* Top up wallet

✅ **Account Management:**

* Add more employees/directors
* Update organization details
* Upload additional documents

***

## Wallet Information

After activation, the organization receives a **default EUR wallet**:

| Attribute        | Value                  | Description            |
| ---------------- | ---------------------- | ---------------------- |
| **Currency**     | EUR                    | Default currency       |
| **Status**       | ACTIVE                 | Ready for transactions |
| **Balance**      | 0.00                   | Initial balance        |
| **IBAN**         | DE89370400440532013000 | Unique account number  |
| **BIC**          | COBADEFFXXX            | Bank identifier code   |
| **Account Type** | BUSINESS               | Business account       |

***

## API Schema Reference

For the complete OpenAPI schema specification, see the [API Schema Mapping](../../../../doc/mint/API_SCHEMA_MAPPING#organization-activation) document.

***

## 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">
    Register new organizations
  </Card>

  <Card title="Personnel Management" icon="users-gear" href="./management">
    Manage directors, shareholders, employees
  </Card>

  <Card title="Verification" icon="shield-check" href="./verification">
    Complete KYB verification
  </Card>

  <Card title="Consents" icon="clipboard-check" href="./consents">
    Accept required consents
  </Card>

  <Card title="Wallet Operations" icon="wallet" href="../../financial-operations/wallet">
    Post-activation financial operations
  </Card>
</CardGroup>

***

## Changelog

| Version | Date       | Changes                                             |
| ------- | ---------- | --------------------------------------------------- |
| v1.0    | 2026-01-13 | Comprehensive organization activation documentation |


## OpenAPI

````yaml fincheck.yaml POST /api/v2.1/customer/organization/{organizationId}/activation
openapi: 3.0.3
info:
  title: Fincheck Endpoint Set
  version: 1.1.0
  description: |
    Focused API spec for Customer APIs and Verification & Compliance endpoints,
    aligned to business-bff B2C/B2B runners and dump payloads.
servers:
  - url: https://sandbox.finhub.cloud
security: []
paths:
  /api/v2.1/customer/organization/{organizationId}/activation:
    post:
      operationId: activateOrganization
      parameters:
        - $ref: '#/components/parameters/XForwardedFor'
        - $ref: '#/components/parameters/XTenantId'
        - $ref: '#/components/parameters/XForwardedFrom'
        - $ref: '#/components/parameters/Platform'
        - $ref: '#/components/parameters/DeviceId'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/XUserId'
        - $ref: '#/components/parameters/XUserRoles'
        - in: path
          name: organizationId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationActivation'
      responses:
        '200':
          description: Activated
components:
  parameters:
    XForwardedFor:
      in: header
      name: X-Forwarded-For
      required: true
      schema:
        type: string
      example: 127.0.0.1
    XTenantId:
      in: header
      name: X-Tenant-ID
      required: true
      schema:
        type: string
      example: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd
    XForwardedFrom:
      in: header
      name: X-Forwarded-From
      required: true
      schema:
        type: string
      example: integration-client
    Platform:
      in: header
      name: platform
      required: true
      schema:
        type: string
      example: web
    DeviceId:
      in: header
      name: deviceId
      required: true
      schema:
        type: string
      example: integration-device
    Authorization:
      in: header
      name: Authorization
      required: true
      schema:
        type: string
      example: Bearer YOUR_ACCESS_TOKEN
    XUserId:
      in: header
      name: X-User-ID
      required: true
      schema:
        type: string
      example: da9a15d2-1eb9-4804-a812-b58b03f33018
    XUserRoles:
      in: header
      name: X-User-Roles
      required: true
      schema:
        type: string
      example: ADMIN_USER,COMPLIANCE_OFFICER
  schemas:
    OrganizationActivation:
      type: object
      required:
        - activationReason
      properties:
        activationReason:
          type: string
          example: All requirements met
        additionalInfo:
          type: object
          required:
            - userId
            - activationCode
          properties:
            userId:
              type: string
              example: da9a15d2-1eb9-4804-a812-b58b03f33018
            activationCode:
              type: string
              example: '123456'
          example:
            userId: da9a15d2-1eb9-4804-a812-b58b03f33018
            activationCode: '123456'
      example:
        activationReason: All requirements met
        additionalInfo:
          userId: da9a15d2-1eb9-4804-a812-b58b03f33018
          activationCode: '123456'

````