> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to the New Bookkeeping Categories API

> Migration guide from the legacy Accounts API to the Bookkeeping Categories API. Use it if your integration manages category groups and categories (legacy /account-groups). To sync accounts, see Migrate to the New Chart of Accounts API.

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](https://developers.pleo.io/reference/categories/bookkeeping-categories-api-overview.md). If you also manage accounts, see [Migrate to the New Chart of Accounts API](https://developers.pleo.io/deprecation/legacy-accounts-api/migrate-to-chart-of-accounts-api.md).

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.

> **Use this page to answer:**

### 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](https://developers.pleo.io/deprecation/legacy-accounts-api/overview.md).

### 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.

> **Sources for the Bookkeeping Categories API:**
>
> * OpenAPI reference: the endpoint pages under the [Bookkeeping Categories API Overview](https://developers.pleo.io/reference/categories/bookkeeping-categories-api-overview.md). This covers categories and category groups. Use them for paths, parameters and required fields.
> * How-tos: none yet.

> This page is the canonical source for migrating *category groups and categories* from the legacy Accounts API (`/account-groups`) to the Bookkeeping Categories API. Related pages cover different concerns:
>
> * [Migrate to the New Chart of Accounts API](https://developers.pleo.io/deprecation/legacy-accounts-api/migrate-to-chart-of-accounts-api.md): the accounts of a company (`/accounts`), not category groups.
> * [Legacy Accounts API Overview](https://developers.pleo.io/deprecation/legacy-accounts-api/overview.md): helps you choose between the two replacement APIs.

Terminology: Legacy and New

This guide calls the deprecated API the **legacy Accounts API** and its replacement the **new Bookkeeping Categories API**.

The legacy Accounts API is under `https://openapi.pleo.io/v1/`. The new Bookkeeping Categories API is under `https://external.pleo.io`, and its endpoints start with `/v1/`.

The legacy API calls a group of accounts an **account group** or an **account category**. The new API calls it a **bookkeeping category group**.

## New to the Bookkeeping Categories API?

> [card] [API Overview](https://developers.pleo.io/reference/categories/bookkeeping-categories-api-overview.md)
>
> What bookkeeping categories and category groups are, and how the new API is structured.

> [card] [API Scopes](https://developers.pleo.io/reference/categories/bookkeeping-categories-api-scopes.md)
>
> Required scopes: `categories:read` and `categories:write`.

> [card] [Chart of Accounts API](https://developers.pleo.io/reference/accounts/chart-of-accounts-api-overview.md)
>
> The API for the accounts that a category links to.

> [card] [OAuth 2.0 Guide](https://developers.pleo.io/docs/current/guides/oauth-workflow-guide.md)
>
> End-to-end OAuth 2.0 workflow guide for Pleo integrations.

> [card] [Standalone API Key Guide](https://developers.pleo.io/docs/current/guides/standalone-api-keys-workflow-guide.md)
>
> End-to-end guide for authenticating with standalone API keys.

## Getting Started

You need API credentials with the [`categories:read`](https://developers.pleo.io/reference/categories/bookkeeping-categories-api-scopes) 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](https://developers.pleo.io/docs/current/platform/multi-entity/multi-entity-and-api-scope.md).

A category links to an account through the `accountId` field. Create or sync the accounts with the [new Chart of Accounts API](https://developers.pleo.io/deprecation/legacy-accounts-api/migrate-to-chart-of-accounts-api.md) 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

| Legacy Accounts API | New Bookkeeping Categories API | Description |
| :- | :- | :- |
| [`GET /account-groups`](https://developers.pleo.io/reference/pleo-deprecated/accounts/get-all-company-account-groups) | [`POST /v1/bookkeeping-category-groups:search`](https://developers.pleo.io/reference/bookkeeping-category-groups/fetch-a-list-of-bookkeeping-category-groups) | Returns the category groups of a company. The new endpoint takes a search body. |
| [`POST /account-groups`](https://developers.pleo.io/reference/pleo-deprecated/accounts/create-an-account-group-for-a-company) | [`POST /v1/bookkeeping-category-groups`](https://developers.pleo.io/reference/bookkeeping-category-groups/create-a-new-bookkeeping-category-group) | Creates a category group. |
| [`GET /account-groups/{accountCategoryId}`](https://developers.pleo.io/reference/pleo-deprecated/accounts/get-an-account-group-for-a-company) | [`GET /v1/bookkeeping-category-groups/{categoryGroupId}`](https://developers.pleo.io/reference/bookkeeping-category-groups/retrieve-a-bookkeeping-category-group-by-its-id) | Returns one category group. |
| [`PUT /account-groups/{accountCategoryId}`](https://developers.pleo.io/reference/pleo-deprecated/accounts/update-an-account-group-for-a-company) | [`PUT /v1/bookkeeping-category-groups/{categoryGroupId}`](https://developers.pleo.io/reference/bookkeeping-category-groups/update-a-bookkeeping-category-group) | Updates a category group. |
| [`DELETE /account-groups/{accountCategoryId}`](https://developers.pleo.io/reference/pleo-deprecated/accounts/delete-an-account-group-for-a-company) | [`DELETE /v1/bookkeeping-category-groups/{categoryGroupId}`](https://developers.pleo.io/reference/bookkeeping-category-groups/delete-a-bookkeeping-category-group) | Deletes a category group. To archive it instead, send `"archived": true` in a `PUT` request. |
| — | [`POST /v1/bookkeeping-categories`](https://developers.pleo.io/reference/bookkeeping-categories/create-a-new-bookkeeping-category) | Creates a category in a category group. |
| — | [`GET /v1/bookkeeping-categories/{categoryId}`](https://developers.pleo.io/reference/bookkeeping-categories/retrieve-a-bookkeeping-category-by-its-id) | Returns one category. |
| — | [`PUT /v1/bookkeeping-categories/{categoryId}`](https://developers.pleo.io/reference/bookkeeping-categories/update-a-bookkeeping-category) | Updates a category. Use it to change the account or the Tax Code of a category. |
| — | [`DELETE /v1/bookkeeping-categories/{categoryId}`](https://developers.pleo.io/reference/bookkeeping-categories/delete-a-bookkeeping-category) | Deletes a category. |
| — | [`POST /v1/bookkeeping-categories:search`](https://developers.pleo.io/reference/bookkeeping-categories/fetch-a-list-of-bookkeeping-categories) | Searches the categories of a company. |
| — | [`GET /v1/bookkeeping-category-aggregations`](https://developers.pleo.io/reference/bookkeeping-category-aggregations/get-aggregated-bookkeeping-category-groups) | Returns the category groups with their categories and linked accounts. |

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](https://developers.pleo.io/deprecation/legacy-tax-code-api/migrate-to-tax-code-api.md).
* The rate limit is 600 requests per minute.

How the legacy account maps

The legacy account combined account data with a link to its group. In the new APIs, the account is in the Chart of Accounts API and the link is on the bookkeeping category. If you set `accountCategoryId` when you created an account, create the account first. Then create a category in the matching group with the `accountId` of that account.

## 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

| Legacy field | New field | Description |
| :- | :- | :- |
| id | `id` | The unique identifier that Pleo generates for the group. |
| name | `name` | The name of the group. |
| typeKey | `type` **\*** | The purpose of the group. The new values are in capitals. |
| hidden | `archived` **\*** | Whether the group is out of use. Hidden groups are archived groups. |
| accounts | Categories **\*** | The new group does not list its accounts. Use the category endpoints or the category aggregations endpoint. |
| — | `companyId` | The unique identifier of the company that the group belongs to. |
| — | `metadata` | A place to store extra information about the group. |

### Category

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

| New field | Description |
| :- | :- |
| `id` | The unique identifier that Pleo generates for the category. |
| `name` | The name of the category. |
| `categoryGroupId` | The unique identifier of the category group that the category belongs to. |
| `accountId` | The Pleo `id` of the account that the category uses. |
| `taxCodeId` | The Pleo `id` of the Tax Code that the category uses. |
| `archived` | Whether the category is archived. |
| `companyId` | The unique identifier of the company that the category belongs to. |
| `metadata` | A place to store extra information about the category. |

## Example

The legacy request returns the account groups of the company:

```bash theme={null}
GET https://openapi.pleo.io/v1/account-groups
```

The new request returns the category groups with their categories and linked accounts. It needs the `company_id` query parameter.

> [tab] OAuth 2.0
>
> ```bash theme={null}
> curl -X GET "https://external.pleo.io/v1/bookkeeping-category-aggregations?company_id=12abc3d4-e567-890e-1234-abc56e78fabc" \
>   -H "Authorization: Bearer <access_token>"
> ```

> [tab] API Key
>
> ```bash theme={null}
> curl --request GET \
>   -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
>   -H "Accept: application/json;charset=UTF-8" \
>   "https://external.pleo.io/v1/bookkeeping-category-aggregations?company_id=12abc3d4-e567-890e-1234-abc56e78fabc" \
>   | jq
> ```

[Get aggregated bookkeeping category groups →](https://developers.pleo.io/reference/bookkeeping-category-aggregations/get-aggregated-bookkeeping-category-groups.md)
