> ## 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 Chart of Accounts API

> Migration guide from the legacy Accounts API to the Chart of Accounts API. Use it if your integration creates, reads, updates, archives or deletes accounts (legacy /accounts). For category groups, see Migrate to the New Bookkeeping Categories API.

The legacy Accounts API has been deprecated. This guide covers how to migrate the accounts of a company to the [new Chart of Accounts API](https://developers.pleo.io/reference/accounts/chart-of-accounts-api-overview.md). If you also manage category groups, see [Migrate to the New Bookkeeping Categories API](https://developers.pleo.io/deprecation/legacy-accounts-api/migrate-to-bookkeeping-categories-api.md).

If you used the legacy Accounts API to keep the accounts of a company in step with an Accounting System, see the [Chart of Accounts Sync Workflow Guide](https://developers.pleo.io/docs/current/guides/accounting-integrations/imports/accounts-sync-workflow-guide.md). It describes the sync process that the new Chart of Accounts API supports.

> **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 does the Chart of Accounts API match accounts?

It matches accounts on `externalId`, not on `code` or `name`.

* `externalId` is the identifier of the account in the Accounting System. You must send it when you create an account.
* Pleo rejects a second account with the same `externalId`. In a batch create, the item appears in `data.failed[]` with `EXTERNAL_ID_ALREADY_EXISTS`, and the other valid items are still created.
* The legacy `accountNumber` is now `code`.

### Should I delete an account in production?

No. Archive it instead.

* Archive with a `PUT` request and `"archived": true`. The legacy `hidden` field is now `archived`.
* Pleo deletes an account at once, even when a category maps to it or accounting entries use it. Pleo does not return a `409`, and you cannot undo a delete.
* Use `DELETE` only to remove test accounts in staging.
* Chart of Accounts Sync archives accounts and does not delete them.

See [How to Delete an Account](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/accounts/how-to-delete-accounts.md).

> **Sources for the Chart of Accounts API:**
>
> * OpenAPI reference: the endpoint pages under the [Chart of Accounts API Overview](https://developers.pleo.io/reference/accounts/chart-of-accounts-api-overview.md). Use them for paths, parameters and required fields.
> * How-tos: [How to Sync Accounts](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/accounts/how-to-sync-accounts.md), [How to Create, Update, and Archive Accounts](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/accounts/how-to-create-update-archive-accounts.md), [How to Create Multiple Accounts in a Single Request](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/accounts/how-to-batch-create-accounts.md), [How to Handle a High-Volume Chart of Accounts](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/accounts/how-to-handle-high-volume-accounts.md) and [How to Delete an Account](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/accounts/how-to-delete-accounts.md).
> * If a how-to and the reference disagree, trust the how-to. How-tos record tested behaviour.

> This page is the canonical source for migrating the *accounts* of a company from the legacy Accounts API (`/accounts`) to the Chart of Accounts API. Related pages cover different concerns:
>
> * [Migrate to the New Bookkeeping Categories API](https://developers.pleo.io/deprecation/legacy-accounts-api/migrate-to-bookkeeping-categories-api.md): category groups and categories (`/account-groups`), not accounts.
> * [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 Chart of Accounts API**.

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

## New to the Chart of Accounts API?

> [card] [API Overview](https://developers.pleo.io/reference/accounts/chart-of-accounts-api-overview.md)
>
> What accounts are and how the new API is structured.

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

> [card] [Chart of Accounts Sync Overview](https://developers.pleo.io/docs/current/platform/accounting-integrations/imports/accounts/accounts-sync-overview.md)
>
> How accounts from an Accounting System become accounts in Pleo.

> [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 [`accounts:read`](https://developers.pleo.io/reference/accounts/chart-of-accounts-api-scopes) scope to read accounts. You also need the `accounts:write` scope to create, update or delete them.

The new Chart of Accounts API takes the company as the `companyId` field. If you manage more than one company, map the chart of accounts of 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).

## Endpoint Mapping

The table below maps the account endpoints of the legacy Accounts API to the endpoints of the new Chart of Accounts API.

* `—` : endpoint is not available in the legacy Accounts API

| Legacy Accounts API | New Chart of Accounts API | Description |
| :- | :- | :- |
| [`GET /accounts`](https://developers.pleo.io/reference/pleo-deprecated/accounts/get-company-accounts) | [`POST /v1/chart-of-accounts:search`](https://developers.pleo.io/reference/accounts/fetch-a-list-of-accounts) | Returns the accounts of a company. The new endpoint takes a search body. |
| [`POST /accounts`](https://developers.pleo.io/reference/pleo-deprecated/accounts/create-an-account-for-a-company) | [`POST /v1/chart-of-accounts`](https://developers.pleo.io/reference/accounts/create-a-new-account) | Creates an account. |
| [`GET /accounts/{accountId}`](https://developers.pleo.io/reference/pleo-deprecated/accounts/get-an-account-for-a-company) | [`GET /v1/chart-of-accounts/{accountId}`](https://developers.pleo.io/reference/accounts/retrieve-an-account-in-pleo-by-its-id) | Returns one account. |
| [`PUT /accounts/{accountId}`](https://developers.pleo.io/reference/pleo-deprecated/accounts/update-an-account-for-a-company) | [`PUT /v1/chart-of-accounts/{accountId}`](https://developers.pleo.io/reference/accounts/update-an-account) | Updates an account. |
| [`DELETE /accounts/{accountId}`](https://developers.pleo.io/reference/pleo-deprecated/accounts/delete-an-account-for-a-company) | [`DELETE /v1/chart-of-accounts/{accountId}`](https://developers.pleo.io/reference/accounts/delete-an-account) | Deletes an account permanently. Pleo does not check whether a category or an accounting entry uses it. In production, archive the account instead with `"archived": true` in a `PUT` request. |
| — | [`POST /v1/chart-of-accounts/batch`](https://developers.pleo.io/reference/accounts/create-multiple-accounts-in-a-single-request) | Creates 1 to 1000 accounts in one request. |

## Key Differences

* Every account now has an `externalId`. It is the identifier of the account in the Accounting System, and you must send it when you create an account. Chart of Accounts Sync matches accounts on `externalId` and not on `code` or `name`. Pleo rejects a second account with the same `externalId` in the same company.
* The legacy `accountNumber` is now `code`.
* The new create request needs the `companyId`. The legacy API had no company in the request.
* The new update request needs `archived` and `name`. Send the full account when you update it.
* Deleting an account is permanent, and Pleo does not check whether a category maps to it or accounting entries use it. Archive the account with a `PUT` request instead. Use `DELETE` only to remove test accounts in staging. See [How to Delete an Account](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/accounts/how-to-delete-accounts.md). Chart of Accounts Sync archives accounts and does not delete them.
* The legacy `hidden` field is now `archived`.
* The legacy `taxCodeId` held the Pleo ID of a Tax Code. The new `taxCodeExternalId` holds the identifier of the tax code in the Accounting System. Pleo does not link it to a Tax Code.
* The legacy `accountCategoryId` is the ID of the account group of the account. It is not on the new account. A bookkeeping category now belongs to a group through its `categoryGroupId` and links to an account through its `accountId`. See [Migrate to the New Bookkeeping Categories API](https://developers.pleo.io/deprecation/legacy-accounts-api/migrate-to-bookkeeping-categories-api.md).
* The legacy list used `pageOffset` and `pageSize`. The new search takes the `limit`, `after`, `before` and `offset` query parameters, and you can sort with `sorting_keys` and `sorting_order`. You can filter by `companyId`, `archived`, `code`, `codes`, `externalId`, `ids` and `name`. The search body must include `companyId`, `excludeIfAssignedToCategory` and `excludeIfAssignedToContraAccount`.
* A company can have no more than 11,000 active accounts. For large charts of accounts, see [How to Handle a High-Volume Chart of Accounts](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/accounts/how-to-handle-high-volume-accounts.md).
* The rate limit is 600 requests per minute.

## Field Mapping

The table below maps the fields of the legacy account to the fields of the new account.

* `—` : 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 account. |
| accountNumber | `code` | The account number that users see in Pleo. |
| name | `name` | The name of the account. |
| hidden | `archived` **\*** | Whether the account is out of use. Hidden accounts are archived accounts. |
| taxCodeId | `taxCodeExternalId` **\*** | The new field holds the identifier of the tax code in the Accounting System, not the Pleo ID. |
| accountCategoryId | — | The ID of the account group. Moved to the bookkeeping category. The category has a `categoryGroupId` for the group and a separate `accountId` for the account. |
| — | `externalId` | The unique identifier of the account in the Accounting System. |
| — | `companyId` | The unique identifier of the company that the account belongs to. |
| — | `metadata` | A place to store extra information about the account. |

## Example

The legacy request returns the accounts of the company:

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

The new request creates an account. Send the `companyId` and the `externalId`.

> [tab] OAuth 2.0
>
> ```bash theme={null}
> curl -X POST "https://external.pleo.io/v1/chart-of-accounts" \
>   -H "Authorization: Bearer <access_token>" \
>   -H "Content-Type: application/json" \
>   -d '{
>         "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
>         "externalId": "ext-3000",
>         "code": "3000",
>         "name": "Software",
>         "archived": false
>       }'
> ```

> [tab] API Key
>
> ```bash theme={null}
> curl --request POST \
>   -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
>   -H "Accept: application/json;charset=UTF-8" \
>   -H "Content-Type: application/json" \
>   "https://external.pleo.io/v1/chart-of-accounts" \
>   -d '{
>         "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
>         "externalId": "ext-3000",
>         "code": "3000",
>         "name": "Software",
>         "archived": false
>       }' \
>   | jq
> ```

The response contains the new account and its Pleo `id`.

[Migrate to the New Bookkeeping Categories API →](https://developers.pleo.io/deprecation/legacy-accounts-api/migrate-to-bookkeeping-categories-api.md)
