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 thecategories: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 itsaccountId. 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
PUTrequest to the category with a newaccountId. In the legacy API, an account belonged to one group through itsaccountCategoryId, and you changed that value to move the account to another group. The new category keeps the group incategoryGroupIdand the account inaccountId. - The legacy
typeKeyis nowtype. The values are the same but in capitals, for exampletravelisTRAVEL. - The legacy
hiddenfield is nowarchived. 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
archivedandname. A group update also needstype, and a category update also needscategoryGroupId. 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:company_id query parameter.
- OAuth 2.0
- API Key
FAQs
Which API replaces the legacy Accounts API?
Two APIs replace it.
- The Chart of Accounts API replaces
/accounts, for example withPOST /v1/chart-of-accounts. - The Bookkeeping Categories API replaces
/account-groups, for example withPOST /v1/bookkeeping-category-groups.
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 incategoryGroupIdand the account inaccountId. - The update request needs
archived,nameandcategoryGroupId, 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.