Organization Activation API

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

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

Endpoint

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

Headers

Path Parameters

Request Body

Code Examples

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"
    }
  }'

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();
};

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()

Response

{
  "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"
      ]
    }
  }
}

{
  "code": 400,
  "message": "Organization verification not completed"
}

{
  "code": 400,
  "message": "Required consents not accepted. Please accept Terms, Privacy, and Data Processing consents."
}

Response Fields

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:

Organization vs Individual Activation

Key differences between organization and individual activation:

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 for complete transaction workflows.

Troubleshooting

Verification Not Completed

Error:

{
  "code": 400,
  "message": "Organization verification not completed"
}

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

Missing Consents

Error:

{
  "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:

{
  "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:

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:

API Schema Reference

For the complete OpenAPI schema specification, see the API Schema Mapping document.

Related Endpoints

Changelog