Skip to main content
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. If you also manage category groups, see Migrate to the New Bookkeeping Categories API. 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. It describes the sync process that the new Chart of Accounts API supports.

New to the Chart of Accounts API?

API Overview

What accounts are and how the new API is structured.

API Scopes

Required scopes: accounts:read and accounts:write.

Chart of Accounts Sync Overview

How accounts from an Accounting System become accounts in Pleo.

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 accounts:read 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.

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

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

Example

The legacy request returns the accounts of the company:
The new request creates an account. Send the companyId and the externalId.
The response contains the new account and its Pleo id.

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