Organization Activation API

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

For complete details on authentication and headers, refer to the Standard HTTP Headers reference documentation.

Role Requirement: Only users with COMPLIANCE_OFFICER or ADMIN_USER roles can activate an organization.

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

Check Activation Readiness: Use GET /{organizationId}/activation/readiness to validate all prerequisites before attempting activation.

Endpoint

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

Headers

X-Tenant-ID

string

required

Tenant identifierExample: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd

Authorization

string

required

Bearer token for authentication (admin privileges required)

Content-Type

string

required

Must be application/json

string

Response format (optional — defaults to application/json)Example: application/json, text/plain, */*

X-User-ID

string

required

User ID of the admin performing activationExample: e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a

X-User-Roles

string

required

Comma-separated list of user rolesExample: ADMIN_USER,COMPLIANCE_OFFICER

X-Forwarded-From

string

required

Source identifier for request origin trackingExample: e2e-test

User-Agent

string

required

Client application identifier — required by the global request filterExample: YourApp/1.0 or Mozilla/5.0 (Windows NT 10.0; Win64; x64)

platform

string

required

Client platform identifier. Also accepted as sec-ch-ua-platformExample: web

deviceId

string

required

Unique device identifier for session tracking. Also accepted as X-Device-Id or device-idExample: 356938035643809

Path Parameters

organizationId

string

required

Organization UUID identifierExample: ef4a8be6-602b-4b26-b81d-afa7d6d835fd

Request Body

activationReason

string

required

Reason for activationExample: "Organization account activation after KYB completion"

additionalInfo

object

Optional metadata about the activation

Show additionalInfo properties

userId

string

User ID performing the activationExample: "87b3af37-4ac1-402b-a0ea-53cfdc695e02"

activationCode

string

Activation code for verificationExample: "E2E_TEST"

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

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

Response Fields

code

integer

HTTP status code

message

string

Human-readable status message

data

object

Activation result data

Show data properties

wallet

object

Created wallet information

Show wallet properties

walletId

string

Unique wallet identifier

balance

string

Initial balance (formatted)

currency

string

Wallet currency (typically EUR)

status

string

Wallet status: ACTIVE

iban

string

Generated IBAN for the organizationExample: LT963500070344952515

activation

object

Activation details

Show activation properties

status

string

Activation status: ACTIVE

activatedAt

string

ISO 8601 timestamp of activation

message

string

Activation message

warnings

array

Array of warning messages (if any)

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

Production ReadinessWhile warnings do not prevent activation, organizations should address all warnings before production use to ensure proper governance and compliance.

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:

Check Balance

GET /api/v2.1/fintrans/{walletId}/balance

Add Beneficiaries

POST /api/v2.1/fintrans/{walletId}/beneficiaries

Prepare Transactions

POST /api/v2.1/fintrans/{walletId}/types/topup/prepare
POST /api/v2.1/transfers/{walletId}/prepare

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:

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

Standard Headers

Complete HTTP headers reference

Organization Registration

Personnel Management

Manage directors, shareholders, employees

Verification

Complete KYB verification

Consents

Accept required consents

Wallet Operations

Post-activation financial operations

Changelog

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

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

Organization Activation API

Organization Activation API

Prerequisites Checklist (14-Step Validation)

1. Organization Structure (4 checks)

2. Verification (3 checks)

3. Consents (3 checks)

4. Documents (2 checks)

5. Authorization (2 checks)

Endpoint

Headers

Path Parameters

Request Body

Code Examples

Response

Response Fields

Common Activation Warnings

Organization vs Individual Activation

Post-Activation Operations

Troubleshooting

Verification Not Completed

Missing Consents

Missing ADMIN_USER Role

What Happens During Activation

What Happens After Activation

Wallet Information

API Schema Reference

Standard Headers

Organization Registration

Personnel Management

Verification

Consents

Wallet Operations

Changelog

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Organization Activation API

​Prerequisites Checklist (14-Step Validation)

​1. Organization Structure (4 checks)

​2. Verification (3 checks)

​3. Consents (3 checks)

​4. Documents (2 checks)

​5. Authorization (2 checks)

​Endpoint

​Headers

​Path Parameters

​Request Body

​Code Examples

​Response

​Response Fields

​Common Activation Warnings

​Organization vs Individual Activation

​Post-Activation Operations

​Troubleshooting

​Verification Not Completed

​Missing Consents

​Missing ADMIN_USER Role

​What Happens During Activation

​What Happens After Activation

​Wallet Information

​API Schema Reference

​Related Endpoints

Standard Headers

Organization Registration

Personnel Management

Verification

Consents

Wallet Operations

​Changelog

Organization Activation API

Prerequisites Checklist (14-Step Validation)

1. Organization Structure (4 checks)

2. Verification (3 checks)

3. Consents (3 checks)

4. Documents (2 checks)

5. Authorization (2 checks)

Endpoint

Headers

Path Parameters

Request Body

Code Examples

Response

Response Fields

Common Activation Warnings

Organization vs Individual Activation

Post-Activation Operations

Troubleshooting

Verification Not Completed

Missing Consents

Missing ADMIN_USER Role

What Happens During Activation

What Happens After Activation

Wallet Information

API Schema Reference

Related Endpoints

Changelog