API Reference/Ledger

Ledger

Retrieve accounts, view ledger overviews, and fetch immutable transaction histories. These endpoints power your dashboards and financial statements.

All endpoints in this section require a valid x-api-key and x-company-id header.

Accounts & Overviews

GET

/v1/ledger/user/:userId/accounts

Retrieves all accounts (USD, ZIG, etc.) associated with a specific user's ledger.

Auth

Field	Type	Required	Description
userId	string (path)	Yes	UUID of the user.

curl -X GET "https://api.switchlock.co.zw/v1/ledger/user/value/accounts" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

Response Example

[
  {
    "id": "acc_01HABC...",
    "ledgerId": "ldg_01HABC...",
    "type": "USER",
    "currency": "USD",
    "balance": "15000",
    "is_frozen": false,
    "created_at": "2026-06-20T10:00:00.000Z",
    "updated_at": "2026-06-23T14:00:00.000Z"
  }
]

GET

/v1/ledger/company/accounts

Retrieves internal accounts used for fees, taxes, and system operations under your company tenant.

Auth

curl -X GET "https://api.switchlock.co.zw/v1/ledger/company/accounts" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

GET

/v1/ledger/accounts/:accountId

Retrieves current balance and info for a specific account.

Auth

Field	Type	Required	Description
accountId	string (path)	Yes	UUID of the account.

curl -X GET "https://api.switchlock.co.zw/v1/ledger/accounts/value" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

Response Example

{
  "id": "acc_01HABC...",
  "type": "USER",
  "currency": "USD",
  "balance": "15000",
  "ledger": {
    "id": "ldg_01HABC...",
    "name": "User Ledger - Jackson",
    "user": {
      "first_name": "Jackson",
      "last_name": "Doe"
    }
  }
}

GET

/v1/ledger/overview/:ledgerId

Retrieves a consolidated view of accounts for a specific ledger.

Auth

Field	Type	Required	Description
ledgerId	string (path)	Yes	UUID of the ledger.

curl -X GET "https://api.switchlock.co.zw/v1/ledger/overview/value" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

Transactions & Statements

GET

/v1/ledger/:ledgerId/transactions

Retrieves all transactions recorded against any account within a specific ledger.

Auth

Field	Type	Required	Description
ledgerId	string (path)	Yes	UUID of the ledger.

curl -X GET "https://api.switchlock.co.zw/v1/ledger/value/transactions" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

GET

/v1/ledger/accounts/:accountId/statement

Retrieves a list of transactions for a specific account within an optional date range.

Auth

Field	Type	Required	Description
accountId	string (path)	Yes	UUID of the account.
startDate	string (query)	No	ISO date string (defaults to 30 days ago).
endDate	string (query)	No	ISO date string (defaults to now).

curl -X GET "https://api.switchlock.co.zw/v1/ledger/accounts/value/statement" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

GET

/v1/ledger/escrow/history

Retrieves all escrow-related transactions across the company, calculating realized company_revenue and system_revenue.

Auth

Field	Type	Required	Description
startDate	string (query)	No	ISO date string.
endDate	string (query)	No	ISO date string.

curl -X GET "https://api.switchlock.co.zw/v1/ledger/escrow/history" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

Response Example

[
  {
    "id": "txn_01HXYZ...",
    "status": "COMPLETED",
    "type": "PAYMENT",
    "amount": "1500",
    "company_revenue": "1500",
    "system_revenue": "500",
    "total_amount": "50000",
    "created_at": "2026-06-23T11:00:00.000Z",
    "buyer": { "first_name": "Alice" },
    "seller": { "first_name": "Bob" }
  }
]

Ledger Management

PATCH

/v1/ledger/:ledgerId/bank-details

Updates the default payout bank details for a ledger.

Auth

Field	Type	Required	Description
ledgerId	string (path)	Yes	UUID of the ledger.
bank_name	string (body)	Yes	Name of the recipient institution.
branch_code	string (body)	Yes	Branch code of the recipient institution.
account_number	string (body)	Yes	Account number of the recipient.
account_name	string (body)	Yes	Name on the recipient account.

curl -X PATCH "https://api.switchlock.co.zw/v1/ledger/value/bank-details" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "ledgerId": "string",
  "bank_name": "string",
  "branch_code": "string",
  "account_number": "string",
  "account_name": "string"
}'

Stats & System

GET

/v1/ledger/stats/system

Retrieves overall performance metrics and system health for your tenant.

Auth

curl -X GET "https://api.switchlock.co.zw/v1/ledger/stats/system" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

GET

/v1/ledger/stats/cashflow

Retrieves inflow/outflow metrics over time.

Auth

curl -X GET "https://api.switchlock.co.zw/v1/ledger/stats/cashflow" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

GET

/v1/ledger/verify-ledger-integrity

Internal utility to trigger an immediate mathematical audit across all ledgers.

Auth

curl -X GET "https://api.switchlock.co.zw/v1/ledger/verify-ledger-integrity" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

Next steps

Treasury API

Withdrawals and fund transfers.

Ledger Concepts

Understand double-entry ledgers.