Accounts API

The Accounts API provides endpoints for managing the Chart of Accounts (COA). Accounts support hierarchical structures with parent-child relationships and multiple account types per US GAAP.

Base Path

/api/v1/accounts

All endpoints require authentication with a valid session token.

List Accounts

Retrieve a paginated list of accounts for a company with filtering options.

GET /api/v1/accounts

curl -X GET "https://your-instance.accountability.app/api/v1/accounts?organizationId={orgId}&companyId={companyId}&limit=50&offset=0" \
  -H "Authorization: Bearer your-session-token"

organizationId

string

required

Organization UUID

companyId

string

required

Company UUID

accountType

enum

Filter by account type: Asset, Liability, Equity, Revenue, Expense

accountCategory

enum

Filter by detailed category (e.g., CurrentAssets, NonCurrentAssets, CurrentLiabilities, Equity, OperatingRevenue, OperatingExpense)

isActive

boolean

Filter by active status

isPostable

boolean

Filter by whether accounts accept journal entry postings

parentAccountId

string

Filter by parent account UUID (for hierarchical filtering)

limit

integer

default:"50"

Maximum items per page (max: 100)

offset

integer

default:"0"

Number of items to skip

{
  "accounts": [
    {
      "id": "acc_123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "org_123e4567-e89b-12d3-a456-426614174000",
      "companyId": "comp_123e4567-e89b-12d3-a456-426614174000",
      "accountNumber": "1000",
      "name": "Cash - Operating",
      "description": "Primary operating cash account",
      "accountType": "Asset",
      "accountCategory": "CurrentAssets",
      "normalBalance": "Debit",
      "parentAccountId": null,
      "isPostable": true,
      "isCashFlowRelevant": true,
      "cashFlowCategory": "OperatingActivities",
      "isIntercompany": false,
      "intercompanyPartnerId": null,
      "currencyRestriction": null,
      "isActive": true,
      "isRetainedEarnings": false,
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 150,
  "limit": 50,
  "offset": 0
}

Get Account

Retrieve a single account by ID.

GET /api/v1/accounts/organizations/{organizationId}/accounts/{id}

curl -X GET "https://your-instance.accountability.app/api/v1/accounts/organizations/{organizationId}/accounts/{accountId}" \
  -H "Authorization: Bearer your-session-token"

organizationId

string

required

Organization UUID

string

required

Account UUID

{
  "id": "acc_123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_123e4567-e89b-12d3-a456-426614174000",
  "companyId": "comp_123e4567-e89b-12d3-a456-426614174000",
  "accountNumber": "1000",
  "name": "Cash - Operating",
  "description": "Primary operating cash account",
  "accountType": "Asset",
  "accountCategory": "CurrentAssets",
  "normalBalance": "Debit",
  "parentAccountId": null,
  "isPostable": true,
  "isCashFlowRelevant": true,
  "cashFlowCategory": "OperatingActivities",
  "isIntercompany": false,
  "intercompanyPartnerId": null,
  "currencyRestriction": null,
  "isActive": true,
  "isRetainedEarnings": false,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

Create Account

Create a new account in the Chart of Accounts.

POST /api/v1/accounts

curl -X POST "https://your-instance.accountability.app/api/v1/accounts" \
  -H "Authorization: Bearer your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_123e4567-e89b-12d3-a456-426614174000",
    "companyId": "comp_123e4567-e89b-12d3-a456-426614174000",
    "accountNumber": "1010",
    "name": "Petty Cash",
    "description": "Small cash fund for minor expenses",
    "accountType": "Asset",
    "accountCategory": "CurrentAssets",
    "normalBalance": "Debit",
    "parentAccountId": "acc_123e4567-e89b-12d3-a456-426614174000",
    "isPostable": true,
    "isCashFlowRelevant": true,
    "cashFlowCategory": "OperatingActivities",
    "isIntercompany": false,
    "intercompanyPartnerId": null,
    "currencyRestriction": null,
    "isRetainedEarnings": false
  }'

organizationId

string

required

Organization UUID

companyId

string

required

Company UUID

accountNumber

string

required

Unique account number within the company (e.g., “1000”, “4010”)

name

string

required

Account display name

description

string

Optional account description

accountType

enum

required

Account type: Asset, Liability, Equity, Revenue, Expense

accountCategory

enum

required

Detailed category for classification. Examples:

Assets: CurrentAssets, NonCurrentAssets, FixedAssets
Liabilities: CurrentLiabilities, NonCurrentLiabilities, LongTermDebt
Equity: Equity, RetainedEarnings, OtherComprehensiveIncome
Revenue: OperatingRevenue, NonOperatingRevenue
Expense: OperatingExpense, CostOfSales, NonOperatingExpense

normalBalance

enum

required

Normal balance side: Debit or Credit

parentAccountId

string

Parent account UUID for hierarchical structure (null for root accounts)

isPostable

boolean

required

Whether journal entries can be posted to this account

isCashFlowRelevant

boolean

required

Whether this account should appear in cash flow statement

cashFlowCategory

enum

Cash flow classification: OperatingActivities, InvestingActivities, FinancingActivities

isIntercompany

boolean

required

Whether this is an intercompany account

intercompanyPartnerId

string

Related company UUID for intercompany accounts

currencyRestriction

string

ISO 4217 currency code if account is restricted to a specific currency

isRetainedEarnings

boolean

default:"false"

Whether this is the retained earnings account (only one per company)

Update Account

Update an existing account. Only provided fields are updated.

PUT /api/v1/accounts/organizations/{organizationId}/accounts/{id}

curl -X PUT "https://your-instance.accountability.app/api/v1/accounts/organizations/{organizationId}/accounts/{accountId}" \
  -H "Authorization: Bearer your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Account Name",
    "description": "Updated description",
    "isActive": true
  }'

organizationId

string

required

Organization UUID

string

required

Account UUID

name

string

Updated account name

description

string

Updated description (set to null to clear)

parentAccountId

string

Update parent account (null to make root account)

isPostable

boolean

Update postable status

isCashFlowRelevant

boolean

Update cash flow relevance

cashFlowCategory

enum

Update cash flow category

isIntercompany

boolean

Update intercompany status

intercompanyPartnerId

string

Update related company

currencyRestriction

string

Update currency restriction (null to remove restriction)

isActive

boolean

Activate or deactivate account

isRetainedEarnings

boolean

Designate as retained earnings account

Account type (accountType) and category (accountCategory) cannot be changed after creation.

Deactivate Account

Deactivate an account (soft delete). Accounts with posted transactions or active child accounts cannot be deactivated.

DELETE /api/v1/accounts/organizations/{organizationId}/accounts/{id}

curl -X DELETE "https://your-instance.accountability.app/api/v1/accounts/organizations/{organizationId}/accounts/{accountId}" \
  -H "Authorization: Bearer your-session-token"

organizationId

string

required

Organization UUID

string

required

Account UUID

Accounts with posted transactions or active child accounts cannot be deactivated. You must first deactivate all child accounts.

Error Responses

Account Not Found (404)

{
  "_tag": "AccountNotFoundError",
  "accountId": "acc_123e4567-e89b-12d3-a456-426614174000",
  "message": "Account not found"
}

Account Number Already Exists (409)

{
  "_tag": "AccountNumberAlreadyExistsError",
  "accountNumber": "1000",
  "companyId": "comp_123e4567-e89b-12d3-a456-426614174000",
  "message": "Account number '1000' already exists for this company"
}

Parent Account Not Found (404)

{
  "_tag": "ParentAccountNotFoundError",
  "parentAccountId": "acc_123e4567-e89b-12d3-a456-426614174000",
  "message": "Parent account not found"
}

Circular Reference (400)

{
  "_tag": "CircularAccountReferenceError",
  "accountId": "acc_123e4567-e89b-12d3-a456-426614174000",
  "parentAccountId": "acc_987e6543-e21b-12d3-a456-426614174000",
  "message": "Setting this parent would create a circular reference"
}

Has Active Child Accounts (409)

{
  "_tag": "HasActiveChildAccountsError",
  "accountId": "acc_123e4567-e89b-12d3-a456-426614174000",
  "activeChildCount": 5,
  "message": "Cannot deactivate account with 5 active child accounts"
}

Account Types Reference

Asset

Resources owned by the company:

Current Assets (cash, receivables)
Non-Current Assets (equipment, investments)
Fixed Assets (property, equipment)

Liability

Obligations owed by the company:

Current Liabilities (payables, short-term debt)
Non-Current Liabilities (long-term debt)

Equity

Owner’s residual interest:

Common Stock
Retained Earnings
Other Comprehensive Income

Revenue

Income from operations:

Operating Revenue (sales)
Non-Operating Revenue (interest, gains)

Expense

Costs of operations:

Cost of Sales
Operating Expenses
Non-Operating Expenses

Overview

Core Endpoints

Consolidation

Reporting

Currency

Accounts API

Accounts API

Base Path

List Accounts

Get Account

Create Account

Update Account

Deactivate Account

Error Responses

Account Types Reference

Asset

Liability

Equity

Revenue

Expense

Build docs developers (and LLMs) love

Overview

Core Endpoints

Consolidation

Reporting

Currency

​Accounts API

​Base Path

​List Accounts

​Get Account

​Create Account

​Update Account

​Deactivate Account

​Error Responses

​Account Types Reference

Asset

Liability

Equity

Revenue

Expense

Build docs developers (and LLMs) love

Accounts API

Base Path

List Accounts

Get Account

Create Account

Update Account

Deactivate Account

Error Responses

Account Types Reference