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

---
title: 'Organization Activation API'
description: 'Activate verified organization accounts'
---

import { RequiredRunnerHeadersWithUserContext } from '../../schemas/required-headers-snippet.mdx';

# 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
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
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
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
{
  "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
{
  "code": 400,
  "message": "Organization verification not completed"
}
```

```json 400 - Missing Consents
{
  "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](/baas/api/reference/financial-operations) for complete transaction workflows.

---

## Troubleshooting

### Verification Not Completed

**Error:**
```json
{
  "code": 400,
  "message": "Organization verification not completed"
}
```

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

### Missing Consents

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