Charts of accounts

Manage accounting accounts for an organization through the Findity Admin API — used for expense categorization, bookkeeping, and payroll. This guide shows you how to list, create, update, and delete accounts in an organization’s chart of accounts, and how those accounts map to expense categories and voucher rows on export.

Overview

Accounts are the rows in an organization’s chart of accounts. Each account has a number (the code your customer’s financial system uses, e.g. 5010) and a name (the human-readable label, e.g. Travel expenses). The chart-of-accounts lifecycle is:

Provision the accounts — POST one per ledger code your customer uses.
Map accounts to expense categories — done in the Findity admin UI or via the categories endpoints. The mapping decides which account number ends up on the debit, credit, or VAT row of a voucher.
Keep them in sync — list, update, or delete accounts as the customer’s chart of accounts evolves.

This guide covers steps 1 and 3 — provisioning and sync. Category mapping is summarized at the end with links to the related guides.

Prerequisites

Complete Authentication and obtain an admin-scoped bearer token.
Provision the organization first — see Admin API — Getting started. The chart-of-accounts endpoints require the organization’s internal id (32-character hex), which you can read from the response of GET /organizations/externalid/{externalId}/.

Key concepts

Concept	Description
Account	One row in the chart of accounts. Holds a `number`, a `name`, and an internal `id`.
Chart of accounts	The full set of accounts an organization uses to categorize expenses and post bookkeeping entries.
Expense category mapping	The link between a Findity expense category (e.g. Travel) and an account `number`. Determines which account appears on the debit row of the voucher.
Voucher row	One line of a generated voucher. Each expense produces at least a debit row, a credit row, and a VAT row when applicable.
Accounting recipient	An external accounting system connected to Findity. When configured, account mappings on expense categories can be synced from the external system automatically.

API endpoints

All endpoints live on the v1 admin API. Examples in this guide use the stage host — switch to the production host (api.findity.com) only when you’re ready to go live.

cURL

https://stage-api.findity.com/api/v1/admin

Operation	Method	Endpoint
List accounts	`GET`	`/organizations/{organizationId}/accounts`
Get a single account	`GET`	`/organizations/{organizationId}/accounts/{accountId}`
Create an account	`POST`	`/organizations/{organizationId}/accounts`
Update an account	`PUT`	`/organizations/{organizationId}/accounts/{accountId}`
Delete an account	`DELETE`	`/organizations/{organizationId}/accounts/{accountId}`

Required headers

Header	Value
`Content-Type`	`application/json`
`Accept`	`application/json`
`Authorization`	`Bearer {access_token}`

Step 1 — List accounts

Retrieve every account in an organization’s chart of accounts. The response is wrapped in a {meta, data} envelope. GET /organizations/{organizationId}/accounts

cURL

curl -X GET \
  "https://stage-api.findity.com/api/v1/admin/organizations/8a5c8bee9e3a4a24019e3ae1732b008e/accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Example response (status 200 OK)

JSON

{
  "meta": { "total": 3, "count": 3 },
  "data": [
    { "id": "8a5c8bee9e3a4a24019e3ae175000090", "meta": {}, "name": "Expenses", "number": "100" },
    { "id": "8a5c8bee9e3a4a24019e3ae175000091", "meta": {}, "name": "VAT", "number": "999" },
    { "id": "8a5c88f89e4f3dd1019e4f725ab40010", "meta": {}, "name": "Office Supplies", "number": "6300" }
  ]
}

meta.total is the total number of accounts; meta.count is the number of items returned in this response.

Step 2 — Create an account

Add a new account to the chart of accounts. Returns 201 Created with the new account’s id. POST /organizations/{organizationId}/accounts

Request body fields

Field	Type	Required	Description
`name`	string	Yes	Display name of the account (e.g. `Travel expenses`).
`number`	string	Yes	The account number used in your customer’s financial system (e.g. `5010`).

Only name and number are accepted on the request body. The backend explicitly rejects unknown fields with 400 NO_KNOWN_JSON_PROPERTIES.

cURL

curl -X POST \
  "https://stage-api.findity.com/api/v1/admin/organizations/8a5c8bee9e3a4a24019e3ae1732b008e/accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Travel expenses",
    "number": "5010"
  }'

Example response (status 201 Created)

JSON

{
  "id": "8a5c89929e4f9c08019e4fb9b90b007d",
  "meta": null,
  "name": "Travel expenses",
  "number": "5010"
}

meta is null on a freshly created account and may be populated by Findity later with auxiliary attributes (currently abbreviation and capabilities).

Step 3 — Get a single account

Retrieve one account by its internal id. GET /organizations/{organizationId}/accounts/{accountId}

cURL

curl -X GET \
  "https://stage-api.findity.com/api/v1/admin/organizations/8a5c8bee9e3a4a24019e3ae1732b008e/accounts/8a5c89929e4f9c08019e4fb9b90b007d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Example response (status 200 OK)

JSON

{
  "id": "8a5c89929e4f9c08019e4fb9b90b007d",
  "meta": { "abbreviation": null, "capabilities": null },
  "name": "Travel expenses",
  "number": "5010"
}

Step 4 — Update an account

Modify an existing account. The request body must include the account’s id, and it must match the accountId in the URL — otherwise the call returns 400 INVALID_ID. PUT /organizations/{organizationId}/accounts/{accountId}

Request body fields

Field	Type	Required	Description
`id`	string	Yes	The account’s internal id. Must match the `{accountId}` in the URL.
`name`	string	Yes	The updated display name.
`number`	string	Yes	The updated account number.

cURL

curl -X PUT \
  "https://stage-api.findity.com/api/v1/admin/organizations/8a5c8bee9e3a4a24019e3ae1732b008e/accounts/8a5c89929e4f9c08019e4fb9b90b007d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id":     "8a5c89929e4f9c08019e4fb9b90b007d",
    "name":   "Travel and accommodation expenses",
    "number": "5010"
  }'

Example response (status 200 OK)

JSON

{
  "id": "8a5c89929e4f9c08019e4fb9b90b007d",
  "meta": null,
  "name": "Travel and accommodation expenses",
  "number": "5010"
}

Step 5 — Delete an account

Remove an account from the chart of accounts. Returns 204 No Content with an empty response body on success. DELETE /organizations/{organizationId}/accounts/{accountId}

Deleting an account that is currently mapped to one or more expense categories will break the accounting flow for those categories — voucher generation will fail until the categories are remapped. Verify no active categories reference the account before deleting.

cURL

curl -X DELETE \
  "https://stage-api.findity.com/api/v1/admin/organizations/8a5c8bee9e3a4a24019e3ae1732b008e/accounts/8a5c89929e4f9c08019e4fb9b90b007d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response (status 204 No Content) The response body is empty.

Mapping accounts to expense categories

After creating accounts, map them to expense categories so Findity can generate the correct voucher rows on export. The mapping decides which account number appears in the debit, credit, or VAT row of the voucher output. Administrators can configure these mappings through:

Admin web client — Settings → Expense management → Expense categories, select the account for each category.
Admin API — Use the categories endpoints to update account mappings programmatically (see the Expense API guide).

Each expense category can be linked to:

A debit account — the accounting account the expense is recorded against.
A salary type — for payroll integration, if applicable.

If the organization uses an accounting recipient connected through the API, account mappings on expense categories can be synced from the external system automatically. For manual recipients, administrators manage these mappings through the admin interface.

Relationship to vouchers

When expense reports are exported through the Connect API, Findity uses the chart of accounts to generate structured voucher data. Each expense produces voucher rows like:

Voucher row	Account source	Description
Debit row	Expense category’s mapped account	Records the expense in the general ledger.
Credit row	Payment method’s mapped account	Records the payment source (e.g. corporate card, employee reimbursement).
VAT row	VAT account	Records the tax amount separately when `vatType` is `SEPARATELY`.

For details on how vouchers are structured and grouped, see Voucher structure.

Common integration patterns

Sync from an ERP or accounting system. Keep the chart of accounts in sync with your ERP on a schedule (e.g. nightly):

Export the current account list from your financial system.
Call GET /organizations/{organizationId}/accounts to retrieve existing accounts in Findity.
Diff the two lists and call POST for new accounts, PUT for changed accounts, and DELETE for removed accounts.

Initial organization setup. When onboarding a new organization:

Create the organization. If you use a template org with pre-configured accounts, accounts are inherited and you can skip the next step.
Otherwise, call POST /organizations/{organizationId}/accounts for each account in the customer’s chart of accounts.
Map accounts to expense categories through the admin UI or the categories API.
Configure salary types if the organization integrates with a payroll system.
Set up the accounting recipient to enable voucher export.

Migrating account numbers. When an organization changes its accounting system or restructures its chart of accounts:

GET /organizations/{organizationId}/accounts to list all current accounts.
POST to create the new accounts.
Update expense-category mappings to point to the new account numbers.
Deactivate or delete the old accounts once all active expense reports have been exported.
Verify the migration by exporting a test voucher and confirming the new account numbers appear in the voucher rows.

Error handling

Errors return a JSON envelope:

JSON

{ "result": "error", "requestId": "<uuid>", "description": "<human-readable message>", "code": "<machine-readable code>" }

The requestId value is useful to include when reporting a problem to Findity support.

Status	`code`	Description
`400`	`NO_KNOWN_JSON_PROPERTIES`	The request body contains no fields the backend recognizes (e.g. you sent `accountNumber`/`accountName` instead of `number`/`name`). Use the field names documented in this guide.
`400`	`INVALID_ID`	On `PUT`, the `id` in the request body doesn’t match the `accountId` in the URL. Include `id` in the body and make sure both match.
`401`	—	Access token is missing, expired, or invalid. Refresh and retry.
`403`	—	The token does not have admin scope for this organization.
`404`	—	The organization or account isn’t found. Confirm the `organizationId` and `accountId`.
`429`	—	Rate limit exceeded. Apply exponential backoff.
`500`	—	Server error. Safe to retry with backoff; if it persists, contact support with the `requestId` from the response.

Home

MCP Server

API Basics

Guides

Overview

Prerequisites

Key concepts

API endpoints

Required headers

Step 1 — List accounts

Step 2 — Create an account

Request body fields

Step 3 — Get a single account

Step 4 — Update an account

Request body fields

Step 5 — Delete an account

Mapping accounts to expense categories

Relationship to vouchers

Common integration patterns

Error handling

Next steps

​Overview

​Prerequisites

​Key concepts

​API endpoints

​Required headers

​Step 1 — List accounts

​Step 2 — Create an account

​Request body fields

​Step 3 — Get a single account

​Step 4 — Update an account

​Request body fields

​Step 5 — Delete an account

​Mapping accounts to expense categories

​Relationship to vouchers

​Common integration patterns

​Error handling

​Next steps

Overview

Prerequisites

Key concepts

API endpoints

Required headers

Step 1 — List accounts

Step 2 — Create an account

Request body fields

Step 3 — Get a single account

Step 4 — Update an account

Request body fields

Step 5 — Delete an account

Mapping accounts to expense categories

Relationship to vouchers

Common integration patterns

Error handling

Next steps