Accounts

Manage your chart of accounts with hierarchical structure, multiple currencies, and business-specific templates. Perfect for building compliant financial applications with proper double-entry accounting foundation.

The account model

The account model represents individual accounts in your chart of accounts, supporting hierarchical relationships, multiple currencies, and rich metadata for various business types.

Properties

Name
id
Type
string
Description
Unique identifier for the account.
Name
code
Type
string
Description
Account code (e.g., "1101", "2001") - must be unique within tenant.
Name
name
Type
string
Description
Display name for the account.
Name
account_type
Type
string
Description
Account type: asset, liability, equity, revenue, or expense.
Name
parent_id
Type
string
Description
ID of the parent account for hierarchical structure.
Name
parent_code
Type
string
Description
Code of the parent account.
Name
currency
Type
string
Description
Primary currency for the account (ISO 4217 code).
Name
metadata
Type
object
Description
Additional account metadata (bank details, categories, etc.).
Name
level
Type
integer
Description
Hierarchy level (0 for top-level accounts).
Name
path
Type
string
Description
Full hierarchy path (e.g., "1000.1100.1101").
Name
is_active
Type
boolean
Description
Whether the account is currently active.
Name
created_at
Type
timestamp
Description
Timestamp of when the account was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the account was last updated.

POST/v1/tenants/:slug/accounts/setup

Setup chart of accounts

Quickly setup a complete chart of accounts using business-specific templates. Perfect for getting started with proper accounting structure in minutes.

Required attributes

Name
business_type
Type
string
Description
Business type: wallet, payments, lending, trading, or basic.

Request

POST

/v1/tenants/acme-fintech/accounts/setup

curl https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/setup \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "business_type": "wallet"
  }'

Response

{
  "success": true,
  "data": {
    "stats": {
      "total_accounts": 25,
      "by_type": {
        "asset": 12,
        "liability": 6,
        "equity": 2,
        "revenue": 3,
        "expense": 2
      },
      "by_currency": {
        "NGN": 20,
        "USD": 4,
        "GBP": 1
      },
      "active_accounts": 24,
      "inactive_accounts": 1,
      "max_hierarchy_level": 3
    }
  }
}

GET/v1/tenants/:slug/accounts

List all accounts

Retrieve a list of all accounts for the tenant with optional filtering and pagination.

Optional attributes

Name
account_type
Type
string
Description
Filter by account type: asset, liability, equity, revenue, or expense.
Name
currency
Type
string
Description
Filter by currency code.
Name
active_only
Type
boolean
Description
Show only active accounts (default: true).
Name
limit
Type
integer
Description
Number of results to return (default: 50, max: 100).
Name
offset
Type
integer
Description
Number of results to skip for pagination.

Request

GET

/v1/tenants/acme-fintech/accounts

curl -G https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts \
  -H "Authorization: Bearer {api_key}" \
  -d account_type=asset \
  -d currency=NGN \
  -d limit=20

Response

{
  "success": true,
  "data": {
    "accounts": [
      {
        "id": "acc_01JB2M3N4P5Q6R7S8T9U0V",
        "code": "1000",
        "name": "Assets",
        "account_type": "asset",
        "parent_id": null,
        "currency": "NGN",
        "metadata": {},
        "is_active": true,
        "created_at": "2025-01-15T10:30:00Z",
        "updated_at": "2025-01-15T10:30:00Z"
      },
      {
        "id": "acc_02KC3M4N5P6Q7R8S9T0U1W",
        "code": "1101",
        "name": "Settlement Account - NGN",
        "account_type": "asset",
        "parent_id": "acc_01JB2M3N4P5Q6R7S8T9U0V",
        "currency": "NGN",
        "metadata": {
          "bank_name": "GTBank",
          "account_number": "0123456789"
        },
        "is_active": true,
        "created_at": "2025-01-15T10:30:00Z",
        "updated_at": "2025-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "total": 25,
      "limit": 20,
      "offset": 0,
      "has_more": true
    }
  }
}

POST/v1/tenants/:slug/accounts

Create an account

Create a new account in your chart of accounts with hierarchical relationships and rich metadata support.

Required attributes

Name
code
Type
string
Description
Unique account code (e.g., "1101", "CASH-USD").
Name
name
Type
string
Description
Display name for the account.
Name
account_type
Type
string
Description
Account type: asset, liability, equity, revenue, or expense.
Name
currency
Type
string
Description
Primary currency for the account (ISO 4217 code).

Optional attributes

Name
parent_code
Type
string
Description
Code of the parent account for hierarchical structure.
Name
metadata
Type
object
Description
Additional account metadata.

Request

POST

/v1/tenants/acme-fintech/accounts

curl https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "1103",
    "name": "Settlement Account - Access Bank",
    "account_type": "asset",
    "parent_code": "1100",
    "currency": "NGN",
    "metadata": {
      "bank_name": "Access Bank",
      "account_number": "9876543210",
      "branch": "Victoria Island"
    }
  }'

Response

{
  "success": true,
  "data": {
    "account": {
      "id": "acc_03LD4N5O6P7Q8R9S0T1U2V",
      "code": "1103",
      "name": "Settlement Account - Access Bank",
      "account_type": "asset",
      "parent_id": "acc_02KC3M4N5P6Q7R8S9T0U1W",
      "parent_code": "1100",
      "currency": "NGN",
      "metadata": {
        "bank_name": "Access Bank",
        "account_number": "9876543210",
        "branch": "Victoria Island"
      },
      "level": 2,
      "path": "1000.1100.1103",
      "is_active": true,
      "created_at": "2025-01-15T11:00:00Z",
      "updated_at": "2025-01-15T11:00:00Z"
    }
  },
  "message": "Account created successfully"
}

GET/v1/tenants/:slug/accounts/:id

Retrieve an account

Retrieve detailed information about a specific account by its ID.

Request

GET

/v1/tenants/acme-fintech/accounts/acc_01JB2M3N4P5Q6R7S8T9U0V

curl https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/acc_01JB2M3N4P5Q6R7S8T9U0V \
  -H "Authorization: Bearer {api_key}"

Response

{
  "success": true,
  "data": {
    "account": {
      "id": "acc_01JB2M3N4P5Q6R7S8T9U0V",
      "code": "1000",
      "name": "Assets",
      "account_type": "asset",
      "parent_id": null,
      "parent_code": null,
      "currency": "NGN",
      "metadata": {},
      "level": 0,
      "path": "1000",
      "is_active": true,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  }
}

GET/v1/tenants/:slug/accounts/code/:code

Get account by code

Retrieve an account by its unique code. Useful for integration scenarios where you reference accounts by their business codes.

Request

GET

/v1/tenants/acme-fintech/accounts/code/1101

curl https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/code/1101 \
  -H "Authorization: Bearer {api_key}"

Response

{
  "success": true,
  "data": {
    "account": {
      "id": "acc_02KC3M4N5P6Q7R8S9T0U1W",
      "code": "1101",
      "name": "Settlement Account - NGN",
      "account_type": "asset",
      "parent_id": "acc_01JB2M3N4P5Q6R7S8T9U0V",
      "parent_code": "1100",
      "currency": "NGN",
      "metadata": {
        "bank_name": "GTBank",
        "account_number": "0123456789"
      },
      "level": 2,
      "path": "1000.1100.1101",
      "is_active": true,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  }
}

GET/v1/tenants/:slug/accounts/hierarchy

Get account hierarchy

Retrieve the complete chart of accounts in hierarchical tree structure, perfect for displaying account relationships and building UI components.

Request

GET

/v1/tenants/acme-fintech/accounts/hierarchy

curl https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/hierarchy \
  -H "Authorization: Bearer {api_key}"

Response

{
  "success": true,
  "data": {
    "accounts": [
      {
        "id": "acc_01JB2M3N4P5Q6R7S8T9U0V",
        "code": "1000",
        "name": "Assets",
        "account_type": "asset",
        "level": 0,
        "path": "1000",
        "currency": "NGN",
        "is_active": true,
        "children": [
          {
            "id": "acc_02KC3M4N5P6Q7R8S9T0U1W",
            "code": "1100",
            "name": "Cash and Bank Accounts",
            "account_type": "asset",
            "level": 1,
            "path": "1000.1100",
            "currency": "NGN",
            "is_active": true,
            "children": [
              {
                "id": "acc_03LD4N5O6P7Q8R9S0T1U2V",
                "code": "1101",
                "name": "Settlement Account - NGN",
                "account_type": "asset",
                "level": 2,
                "path": "1000.1100.1101",
                "currency": "NGN",
                "is_active": true,
                "children": []
              }
            ]
          }
        ]
      }
    ],
    "total_accounts": 25
  }
}

GET/v1/tenants/:slug/accounts/:id/balance

Get account balance

Retrieve the current balance for a specific account in the specified currency.

Optional attributes

Name
currency
Type
string
Description
Currency code for balance query (defaults to account's primary currency).

Request

GET

/v1/tenants/acme-fintech/accounts/acc_02KC3M4N5P6Q7R8S9T0U1W/balance

curl -G https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/acc_02KC3M4N5P6Q7R8S9T0U1W/balance \
  -H "Authorization: Bearer {api_key}" \
  -d currency=NGN

Response

{
  "success": true,
  "data": {
    "balance": {
      "account_id": "acc_02KC3M4N5P6Q7R8S9T0U1W",
      "currency": "NGN",
      "balance": "1500000.00",
      "version": 5,
      "updated_at": "2025-01-15T14:30:00Z"
    }
  }
}

PUT/v1/tenants/:slug/accounts/:id

Update an account

Update an existing account's information. Account codes and types cannot be changed after creation.

Optional attributes

Name
name
Type
string
Description
Updated display name for the account.
Name
metadata
Type
object
Description
Updated account metadata.
Name
is_active
Type
boolean
Description
Whether the account should be active.

Request

PUT

/v1/tenants/acme-fintech/accounts/acc_03LD4N5O6P7Q8R9S0T1U2V

curl -X PUT https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/acc_03LD4N5O6P7Q8R9S0T1U2V \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Settlement Account - Access Bank (Primary)",
    "metadata": {
      "bank_name": "Access Bank",
      "account_number": "9876543210",
      "branch": "Victoria Island",
      "is_primary": true
    }
  }'

Response

{
  "success": true,
  "data": {
    "account": {
      "id": "acc_03LD4N5O6P7Q8R9S0T1U2V",
      "code": "1103",
      "name": "Settlement Account - Access Bank (Primary)",
      "account_type": "asset",
      "parent_id": "acc_02KC3M4N5P6Q7R8S9T0U1W",
      "parent_code": "1100",
      "currency": "NGN",
      "metadata": {
        "bank_name": "Access Bank",
        "account_number": "9876543210",
        "branch": "Victoria Island",
        "is_primary": true
      },
      "level": 2,
      "path": "1000.1100.1103",
      "is_active": true,
      "created_at": "2025-01-15T11:00:00Z",
      "updated_at": "2025-01-15T12:00:00Z"
    }
  },
  "message": "Account updated successfully"
}

DELETE/v1/tenants/:slug/accounts/:id

Delete an account

Delete an account from the chart of accounts. Accounts with child accounts or transaction history cannot be deleted.

Request

DELETE

/v1/tenants/acme-fintech/accounts/acc_03LD4N5O6P7Q8R9S0T1U2V

curl -X DELETE https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/acc_03LD4N5O6P7Q8R9S0T1U2V \
  -H "Authorization: Bearer {api_key}"

Response

{
  "success": true,
  "message": "Account deleted successfully"
}

GET/v1/tenants/:slug/accounts/stats

Get account statistics

Retrieve comprehensive statistics about your chart of accounts, including account counts by type and currency distribution. Useful for dashboards and compliance reporting.

Response statistics

Name
total_accounts
Type
integer
Description
Total number of accounts in the chart.
Name
by_type
Type
object
Description
Account count breakdown by type (asset, liability, equity, revenue, expense).
Name
by_currency
Type
object
Description
Account count breakdown by currency code.
Name
active_accounts
Type
integer
Description
Number of currently active accounts.
Name
inactive_accounts
Type
integer
Description
Number of inactive accounts.
Name
max_hierarchy_level
Type
integer
Description
Maximum depth of the account hierarchy.

Request

GET

/v1/tenants/acme-fintech/accounts/stats

curl https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/stats \
  -H "Authorization: Bearer {api_key}"

Response

{
  "success": true,
  "data": {
    "stats": {
      "total_accounts": 25,
      "by_type": {
        "asset": 12,
        "liability": 6,
        "equity": 2,
        "revenue": 3,
        "expense": 2
      },
      "by_currency": {
        "NGN": 20,
        "USD": 4,
        "GBP": 1
      },
      "active_accounts": 24,
      "inactive_accounts": 1,
      "max_hierarchy_level": 3
    }
  }
}

GET/v1/tenants/:slug/accounts/:id/balance

Get account balance

Retrieve the current balance for a specific account in the specified currency. Returns real-time balance with version for optimistic concurrency control.

Optional attributes

Name
currency
Type
string
Description
Currency code for balance query (default: "NGN").

Request

GET

/v1/tenants/:slug/accounts/:id/balance

curl https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/acc_01JB2M3N4P5Q6R7S8T9U0V/balance?currency=NGN \
  -H "Authorization: Bearer {api_key}"

Response

{
  "success": true,
  "data": {
    "currency": "NGN",
    "balance": "125000.50",
    "version": 47
  }
}

GET/v1/tenants/:slug/accounts/:id/balance/history

Get account balance history

Retrieve balance history for a specific account over a specified time period. Useful for balance reconciliation and trend analysis.

Optional attributes

Name
currency
Type
string
Description
Currency code for balance history (default: "NGN").
Name
days
Type
integer
Description
Number of days of history to retrieve (default: 30, max: 365).

Request

GET

/v1/tenants/:slug/accounts/:id/balance/history

curl -G https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/acc_01JB2M3N4P5Q6R7S8T9U0V/balance/history \
  -H "Authorization: Bearer {api_key}" \
  -d currency=NGN \
  -d days=7

Response

{
  "success": true,
  "data": {
    "account_id": "acc_01JB2M3N4P5Q6R7S8T9U0V",
    "currency": "NGN",
    "days": 7,
    "history": [
      {
        "balance": "125000.50",
        "version": 47,
        "updated_at": "2025-09-26T14:30:00Z"
      },
      {
        "balance": "120000.00",
        "version": 46,
        "updated_at": "2025-09-26T10:15:00Z"
      },
      {
        "balance": "115000.00",
        "version": 45,
        "updated_at": "2025-09-25T16:45:00Z"
      }
    ]
  }
}

GET/v1/tenants/:slug/accounts/balances/summary

Get balance summary

Retrieve a comprehensive balance summary across all accounts with breakdown by account type. Includes financial statement totals and analytics.

Optional attributes

Name
currency
Type
string
Description
Filter summary by specific currency (omit for all currencies).

Request

GET

/v1/tenants/:slug/accounts/balances/summary

curl -G https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/balances/summary \
  -H "Authorization: Bearer {api_key}" \
  -d currency=NGN

Response

{
  "success": true,
  "data": {
    "currency": "NGN",
    "total_accounts": 25,
    "total_assets": "2500000.00",
    "total_liabilities": "1800000.00",
    "total_equity": "700000.00",
    "total_revenue": "450000.00",
    "total_expenses": "180000.00",
    "net_worth": "700000.00",
    "breakdown": [
      {
        "account_type": "asset",
        "currency": "NGN",
        "account_count": 8,
        "total_balance": "2500000.00",
        "average_balance": "312500.00",
        "minimum_balance": "0.00",
        "maximum_balance": "1200000.00"
      },
      {
        "account_type": "liability",
        "currency": "NGN",
        "account_count": 6,
        "total_balance": "1800000.00",
        "average_balance": "300000.00",
        "minimum_balance": "50000.00",
        "maximum_balance": "800000.00"
      },
      {
        "account_type": "equity",
        "currency": "NGN",
        "account_count": 3,
        "total_balance": "700000.00",
        "average_balance": "233333.33",
        "minimum_balance": "100000.00",
        "maximum_balance": "400000.00"
      },
      {
        "account_type": "revenue",
        "currency": "NGN",
        "account_count": 5,
        "total_balance": "450000.00",
        "average_balance": "90000.00",
        "minimum_balance": "25000.00",
        "maximum_balance": "180000.00"
      },
      {
        "account_type": "expense",
        "currency": "NGN",
        "account_count": 3,
        "total_balance": "180000.00",
        "average_balance": "60000.00",
        "minimum_balance": "30000.00",
        "maximum_balance": "80000.00"
      }
    ],
    "generated_at": "2025-09-26T15:00:00Z"
  }
}

Balance query examples

# Get current balance for customer deposit account
curl https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/acc_customer_deposits/balance?currency=NGN \
  -H "Authorization: Bearer {api_key}"

# Returns: {"currency": "NGN", "balance": "1250000.50", "version": 156}

Balance error responses

Account not found

{
  "success": false,
  "error": "Account not found"
}

Invalid account ID

{
  "success": false,
  "error": "Invalid account ID"
}

Invalid days parameter

{
  "success": false,
  "error": "Days parameter must be between 1 and 365"
}