Skip to main content
The legacy Accounts API has been deprecated. This guide covers how to migrate the account groups of a company to the new Bookkeeping Categories API. If you also manage accounts, see Migrate to the New Chart of Accounts API. The new Bookkeeping Categories API covers category groups and categories. A bookkeeping category describes the purpose of an expense, such as travel or software. Each category belongs to a category group and can link to an account and to a Tax Code.

New to the Bookkeeping Categories API?

API Overview

What bookkeeping categories and category groups are, and how the new API is structured.

API Scopes

Required scopes: categories:read and categories:write.

Chart of Accounts API

The API for the accounts that a category links to.

OAuth 2.0 Guide

End-to-end OAuth 2.0 workflow guide for Pleo integrations.

Standalone API Key Guide

End-to-end guide for authenticating with standalone API keys.

Getting Started

You need API credentials with the categories:read scope to read category groups and categories. You also need the categories:write scope to create, update or delete them. The create and search requests take the company as the companyId field. The aggregation request takes it as the company_id query parameter. If you manage more than one company, handle each company on its own. For more information, see Multi-Entity and API Scope. A category links to an account through the accountId field. Create or sync the accounts with the new Chart of Accounts API first.

Endpoint Mapping

The table below maps the group endpoints of the legacy Accounts API to the endpoints of the new Bookkeeping Categories API.
  • — : endpoint is not available in the legacy Accounts API
The legacy /account-categories endpoints are duplicates of the /account-groups endpoints. Use the same mapping for them.

Key Differences

  • The new API has two resources: category groups and categories. Each category belongs to a category group through its categoryGroupId.
  • The legacy account group listed its accounts in accounts. In the new API, a category links to one account through its accountId. To read the groups with their categories and accounts in one request, use the category aggregations endpoint.
  • To change the account that a category uses, send a PUT request to the category with a new accountId. In the legacy API, an account belonged to one group through its accountCategoryId, and you changed that value to move the account to another group. The new category keeps the group in categoryGroupId and the account in accountId.
  • The legacy typeKey is now type. The values are the same but in capitals, for example travel is TRAVEL.
  • The legacy hidden field is now archived. When you archive or unarchive a category group, Pleo applies the same status to every category in the group.
  • A category that is linked to accounts cannot be deleted. Pleo returns 409. Archive the category instead if it must stay available for historical bookkeeping data.
  • The new create request needs the companyId. The legacy API had no company in the request.
  • The new update requests need archived and name. A group update also needs type, and a category update also needs categoryGroupId. Send the full resource when you update it.
  • The new category can link to a Tax Code through taxCodeId. This is the Pleo ID of the Tax Code. See the new Tax Code API.
  • The rate limit is 600 requests per minute.

Field Mapping

Account group and category group

The table below maps the fields of the legacy account group to the fields of the new category group.
  • — : field is not available on the legacy model
  • * : data is the same but represented differently

Category

The new category has no legacy model. The table below shows its fields.

Example

The legacy request returns the account groups of the company:
The new request returns the category groups with their categories and linked accounts. It needs the company_id query parameter.

FAQs

Which API replaces the legacy Accounts API?

Two APIs replace it.
  • The Chart of Accounts API replaces /accounts, for example with POST /v1/chart-of-accounts.
  • The Bookkeeping Categories API replaces /account-groups, for example with POST /v1/bookkeeping-category-groups.
If an integration does both, create the accounts first. A category links to an account through its accountId. To choose, see the Legacy Accounts API Overview.

How do I change the account that a category uses?

Send a PUT request to /v1/bookkeeping-categories/{categoryId} with the new accountId.
  • In the legacy API, an account belonged to one group through its accountCategoryId. The new category keeps the group in categoryGroupId and the account in accountId.
  • The update request needs archived, name and categoryGroupId, so send the full category.

Can I delete a category that is linked to accounts?

No. Pleo returns 409. Archive the category instead with "archived": true if it must stay available for historical bookkeeping data. When you archive a category group, Pleo archives every category in the group.