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 theaccounts: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 onexternalIdand not oncodeorname. Pleo rejects a second account with the sameexternalIdin the same company. - The legacy
accountNumberis nowcode. - The new create request needs the
companyId. The legacy API had no company in the request. - The new update request needs
archivedandname. 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
PUTrequest instead. UseDELETEonly 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
hiddenfield is nowarchived. - The legacy
taxCodeIdheld the Pleo ID of a Tax Code. The newtaxCodeExternalIdholds the identifier of the tax code in the Accounting System. Pleo does not link it to a Tax Code. - The legacy
accountCategoryIdis 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 itscategoryGroupIdand links to an account through itsaccountId. See Migrate to the New Bookkeeping Categories API. - The legacy list used
pageOffsetandpageSize. The new search takes thelimit,after,beforeandoffsetquery parameters, and you can sort withsorting_keysandsorting_order. You can filter bycompanyId,archived,code,codes,externalId,idsandname. The search body must includecompanyId,excludeIfAssignedToCategoryandexcludeIfAssignedToContraAccount. - 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:companyId and the externalId.
- OAuth 2.0
- API Key
id.
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 does the Chart of Accounts API match accounts?
It matches accounts on
externalId, not on code or name.externalIdis 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 indata.failed[]withEXTERNAL_ID_ALREADY_EXISTS, and the other valid items are still created. - The legacy
accountNumberis nowcode.
Should I delete an account in production?
No. Archive it instead.
- Archive with a
PUTrequest and"archived": true. The legacyhiddenfield is nowarchived. - 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
DELETEonly to remove test accounts in staging. - Chart of Accounts Sync archives accounts and does not delete them.