Pleo Chart of Accounts API
Chart of accounts management API for creating single and batch ledger accounts, searching, updating, and deleting nominal account records.
OpenAPI Specification
openapi: 3.0.1
info:
title: Chart of Accounts API
description: Bookkeeping Core OpenAPI definitions
termsOfService: https://pleo.io/terms/
contact:
email: [email protected]
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 24.9.0
servers:
- url: https://external.pleo.io
description: Production server
- url: https://external.staging.pleo.io
description: Staging server
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: BookkeepingCore
description: This resource is associated with the BookkeepingCore API
- name: Accounts
description: 'This API enables you to create an account in Pleo, search for an account
by its ID, update details of an account recorded in Pleo, delete an account from
Pleo, or apply specific filters to retrieve a list of accounts managed in Pleo.
💡**Note**
Please note that only response codes specific to the API behaviour are documented.
Otherwise, we follow HTTP response codes.
'
- name: Aggregated Bookkeeping Category Groups
description: 'This API enables you to read aggregated bookkeeping category groups.
💡**Note**
Please note that only response codes specific to the API behaviour are documented.
Otherwise, we follow HTTP response codes.'
- name: Aggregated Contra Accounts
description: 'This API enables you to read aggregated contra accounts.
💡**Note**
Please note that only response codes specific to the API behaviour are documented.
Otherwise, we follow HTTP response codes.'
- name: Bookkeeping Categories
description: 'This API enables you to perform operations on a bookkeeping category.
💡**Note**
Please note that only response codes specific to the API behaviour are documented.
Otherwise, we follow HTTP response codes..
'
- name: Bookkeeping Category Groups
description: 'This API enables you to perform operations on a bookkeeping category
group.
💡**Note**
Please note that only response codes specific to the API behaviour are documented.
Otherwise, we follow HTTP response codes.'
- name: Contra Accounts
description: 'This API enables you to manage contra accounts.
💡**Note**
Please note that only response codes specific to the API behaviour are documented.
Otherwise, we follow HTTP response codes..
'
- name: Bookkeeping Preferences Resource
paths:
/v1/chart-of-accounts:
post:
tags:
- Accounts
summary: Create a new account
description: '
The integration sends a request to this endpoint to create a corresponding
account in Pleo for any new record created in the external ERP/accounting
system.
The request will fail if an account with the same `externalId` and `companyId`
already exists in Pleo.
'
operationId: createAccountV1
requestBody:
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/BookkeepingAccountCreateRequestV1'
required: true
responses:
'200':
description: Request matched existing account.
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseBookkeepingAccountRestModelV1'
example:
data:
archived: false
code: '2001'
companyId: 123e4567-e89b-12d3-a456-426614174006
externalId: External Id
id: 123e4567-e89b-12d3-a456-426614174005
name: Bank Charges
taxCodeExternalId: IVA 20
'201':
description: Account created.
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseBookkeepingAccountRestModelV1'
example:
data:
archived: false
code: '2001'
companyId: 123e4567-e89b-12d3-a456-426614174006
externalId: External Id
id: 123e4567-e89b-12d3-a456-426614174005
name: Bank Charges
taxCodeExternalId: IVA 20
'400':
description: 'Bad request: for example, missing required fields.'
'409':
description: 'Conflict: account with the same `externalId` exists in Pleo.'
/v1/chart-of-accounts/batch:
post:
tags:
- Accounts
summary: Create multiple accounts in a single request
description: '
Creates multiple bookkeeping accounts in a single batch operation.
This endpoint validates each account in the batch and returns both successfully
created accounts and failed items with their failure reasons.
Accounts that pass validation will be created, while invalid accounts will
be returned in the failed list.
'
operationId: createAccountsBatchV1
requestBody:
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/BookkeepingAccountBatchCreateRequestV1'
required: true
responses:
'201':
description: Batch creation completed. Check the response for created and
failed items.
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseBookkeepingAccountBatchCreateResponseV1'
example:
data:
created:
- archived: false
code: '2001'
companyId: 123e4567-e89b-12d3-a456-426614174006
externalId: ext-001
id: 123e4567-e89b-12d3-a456-426614174005
name: Bank Charges
taxCodeExternalId: IVA 20
- archived: false
code: '2002'
companyId: 123e4567-e89b-12d3-a456-426614174006
externalId: ext-002
id: 123e4567-e89b-12d3-a456-426614174007
name: Office Supplies
taxCodeExternalId: IVA 20
failed:
- reasons:
- EXTERNAL_ID_ALREADY_EXISTS
- NAME_EMPTY
request:
archived: false
code: '2003'
externalId: ext-duplicate
name: ''
taxCodeExternalId: IVA 20
'400':
description: 'Bad request: for example, batch size outside allowed range,
missing required fields or contains invalid input.'
/v1/chart-of-accounts/{accountId}:
get:
tags:
- Accounts
summary: Retrieve an account in Pleo by its ID
description: Search for a specific account by its ID.
operationId: getAccountV1
parameters:
- name: accountId
in: path
description: ID of the account to retrieve.
required: true
style: simple
explode: false
schema:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174015
responses:
'200':
description: Retrieval of account successful.
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseBookkeepingAccountRestModelV1'
example:
data:
archived: false
code: '2001'
companyId: 123e4567-e89b-12d3-a456-426614174006
externalId: External Id
id: 123e4567-e89b-12d3-a456-426614174005
name: Bank Charges
taxCodeExternalId: IVA 20
'404':
description: Account not found.
put:
tags:
- Accounts
summary: Update an account
description: '
Update details of an existing account in Pleo.
The integration must send a request to this endpoint when it is trying to
archive an account linked to accounting entries.
'
operationId: updateAccountV1
parameters:
- name: accountId
in: path
description: ID of the account to update.
required: true
style: simple
explode: false
schema:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174015
requestBody:
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/BookkeepingAccountUpdateRequestV1'
required: true
responses:
'200':
description: Update of account successful.
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseBookkeepingAccountRestModelV1'
example:
data:
archived: false
code: '2001'
companyId: 123e4567-e89b-12d3-a456-426614174006
externalId: External Id
id: 123e4567-e89b-12d3-a456-426614174005
name: Bank Charges
taxCodeExternalId: IVA 20
'400':
description: 'Bad request: for example, missing required fields, tax code
does not exist in Pleo.'
'404':
description: Account not found.
delete:
tags:
- Accounts
summary: Delete an account
description: '
Deletes an existing account in Pleo.
Only accounts not linked to any accounting entries can be deleted. Trying
to delete an account linked to accounting entries will result in an error.
If an account is linked, it can only be archived. Use UPDATE endpoint to archive
an account.
'
operationId: deleteAccountV1
parameters:
- name: accountId
in: path
description: ID of the account to delete.
required: true
style: simple
explode: false
schema:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174015
responses:
'204':
description: Deletion of account successful.
'404':
description: Account not found.
'409':
description: Account linked to accounting entries and cannot be deleted.
Use UPDATE endpoint to archive the account.
/v1/chart-of-accounts:search:
post:
tags:
- Accounts
summary: Fetch a list of accounts
description: Retrieves a list of accounts with companyId and other optional
filters. Results are paginated.
operationId: searchAccountsV1
parameters:
- name: before
in: query
description: Lower bound of the page of data to return (cannot be used together
with [after] or [offset]).
required: false
style: form
explode: true
schema:
pattern: ^[A-Z2-7=~]+$
type: string
- name: after
in: query
description: Upper bound of the page of data to return (cannot be used together
with [before] or [offset]).
required: false
style: form
explode: true
schema:
pattern: ^[A-Z2-7=~]+$
type: string
- name: offset
in: query
description: Offset of the page of data to return (cannot be used together
with [before] or [after]).
required: false
style: form
explode: true
schema:
type: integer
format: int64
- name: limit
in: query
description: The maximum amount of items to return.
required: false
style: form
explode: true
schema:
type: integer
format: int32
- name: sorting_keys
in: query
description: The keys to sort the results by.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: sorting_order
in: query
description: The order to sort the results by. Must be the same length as
[sortingKeys]; one order per key.
required: false
style: form
explode: true
schema:
type: array
items:
$ref: '#/components/schemas/PageOrder'
requestBody:
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/BookkeepingAccountSearchRequestV1'
required: true
responses:
'200':
description: Retrieval of accounts successful.
content:
application/json:
schema:
$ref: '#/components/schemas/CursorPaginatedResponseBookkeepingAccountRestModelV1'
example:
data:
- accountingSystem: xero
archived: false
code: '2001'
companyId: 123e4567-e89b-12d3-a456-426614174006
externalId: External Id
id: 123e4567-e89b-12d3-a456-426614174005
name: Bank Charges
taxCodeExternalId: IVA 20
pagination:
currentRequestPagination:
parameters: {}
endCursor: string
hasNextPage: true
hasPreviousPage: true
startCursor: string
total: 1
'400':
description: 'Bad request: for example, missing required fields, tax code
does not exist in Pleo.'
components:
schemas:
AggregatedBookkeepingCategoryGroupTypeRestModelV1:
type: string
description: Bookkeeping category group types supported by Pleo. Used to classify
category groups in frontend.
enum:
- ENTERTAINMENT
- EQUIPMENT_AND_HARDWARE
- MARKETING_AND_ADVERTISING
- MEALS_AND_DRINKS
- OFFICE_EXPENSES
- PHONE_AND_INTERNET
- SERVICES_AND_CONSULTANCY
- SOFTWARE
- SUPPLIES
- TRAVEL
- OTHER
- NO_SUITABLE_CATEGORY
BookkeepingAccountBatchCreateRequestV1:
required:
- companyId
- items
type: object
properties:
companyId:
type: string
description: Pleo's internal identifier for the company the accounts are
associated with.
format: uuid
items:
maxItems: 1000
minItems: 1
type: array
description: 'List of bookkeeping accounts to be created.
The number of accounts in the batch must be between 1 and 1000.'
items:
$ref: '#/components/schemas/BookkeepingAccountBatchRequestItemV1'
BookkeepingAccountBatchCreateResponseV1:
required:
- created
- failed
type: object
properties:
created:
type: array
description: List of successfully created accounts.
items:
$ref: '#/components/schemas/BookkeepingAccountRestModelV1'
failed:
type: array
description: List of accounts that failed to be created, including the reasons
for failure.
items:
$ref: '#/components/schemas/BookkeepingAccountBatchFailedItemV1'
description: Response for batch account creation operation.
BookkeepingAccountBatchFailedItemV1:
required:
- reasons
- request
type: object
properties:
reasons:
type: array
description: List of reasons why the account creation failed.
items:
type: string
description: Possible reasons for account creation failure in batch operations.
enum:
- EXTERNAL_ID_ALREADY_EXISTS
- EXTERNAL_ID_TOO_LONG
- EXTERNAL_ID_EMPTY
- NAME_TOO_LONG
- NAME_EMPTY
- CODE_TOO_LONG
- OTHER
request:
$ref: '#/components/schemas/BookkeepingAccountBatchRequestItemV1'
description: Represents a failed account creation in a batch operation.
BookkeepingAccountBatchRequestItemV1:
required:
- archived
- externalId
- name
type: object
properties:
archived:
type: boolean
description: Boolean flag used to determine if the account is archived.
code:
maxLength: 255
minLength: 0
type: string
description: 'Account code or number used in the accounting system''s chart
of accounts. Maximum length: 255 characters.'
nullable: true
externalId:
maxLength: 255
minLength: 1
type: string
description: 'Non empty unique external identifier of the account, assigned
in the external ERP/accounting system. Can be the same as code if no other
identifier is available. Maximum length: 255 characters.'
metadata:
type: object
additionalProperties:
type: object
description: Place for API users to store flexible data.
nullable: true
description: Place for API users to store flexible data.
nullable: true
name:
maxLength: 255
minLength: 0
type: string
description: 'Name of the account. Maximum length: 255 characters.'
taxCodeExternalId:
type: string
description: 'The identifier in **the target system** for the tax code the
account is associated with.
- This is NOT the tax percentage (e.g. 20%)
- This is NOT the Pleo UUID of the tax code'
nullable: true
description: 'List of bookkeeping accounts to be created.
The number of accounts in the batch must be between 1 and 1000.'
BookkeepingAccountCreateRequestV1:
required:
- archived
- companyId
- externalId
- name
type: object
properties:
archived:
type: boolean
description: Boolean flag used to determine if the account is archived.
code:
maxLength: 255
minLength: 0
type: string
description: 'Account code or number used in the accounting system''s chart
of accounts. Maximum length: 255 characters.'
nullable: true
companyId:
type: string
description: Pleo's internal identifier for the company the account is associated
with.
format: uuid
externalId:
maxLength: 255
minLength: 1
type: string
description: 'Non empty unique external identifier of the account, assigned
in the external ERP/accounting system. Can be the same as code if no other
identifier is available. Maximum length: 255 characters.'
metadata:
type: object
additionalProperties:
type: object
description: Place for API users to store flexible data.
nullable: true
description: Place for API users to store flexible data.
nullable: true
name:
maxLength: 255
minLength: 0
type: string
description: 'Name of the account. Maximum length: 255 characters.'
taxCodeExternalId:
type: string
description: 'The identifier in **the target system** for the tax code the
account is associated with.
- This is NOT the tax percentage (e.g. 20%)
- This is NOT the Pleo UUID of the tax code'
nullable: true
BookkeepingAccountRestModelV1:
required:
- archived
- companyId
- externalId
- id
- name
type: object
properties:
archived:
type: boolean
description: Boolean flag used to determine if the account is archived.
code:
type: string
description: Account code or number used in the accounting system's chart
of accounts.
nullable: true
companyId:
type: string
description: Pleo's internal identifier of the company the account is associated
with.
format: uuid
externalId:
type: string
description: Unique external identifier of the account, assigned in the
external ERP/accounting system. Can be the same as code if no other identifier
is available.
id:
type: string
description: Pleo's internal identifier of the account.
format: uuid
metadata:
type: object
additionalProperties:
type: object
description: Place for API users to store flexible data.
nullable: true
description: Place for API users to store flexible data.
nullable: true
name:
type: string
description: Name of the account.
taxCodeExternalId:
type: string
description: 'The identifier in **the target system** for the tax code the
account is associated with. '
nullable: true
description: Represents an account in Pleo.
BookkeepingAccountSearchRequestV1:
required:
- companyId
- excludeIfAssignedToCategory
- excludeIfAssignedToContraAccount
type: object
properties:
archived:
type: boolean
description: Filter by archived status.
nullable: true
example: false
code:
type: string
description: Search by code.
nullable: true
example: '2001'
deprecated: true
codes:
uniqueItems: true
type: array
description: Search by a list of codes.
nullable: true
items:
type: string
description: Search by a list of codes.
nullable: true
companyId:
type: string
description: Filter by company ID.
format: uuid
example: 123e4567-e89b-12d3-a456-426614174011
excludeIfAssignedToCategory:
type: boolean
description: Exclude bookkeeping accounts assigned to a bookkeeping category.
example: false
default: false
excludeIfAssignedToContraAccount:
type: boolean
description: Exclude bookkeeping accounts assigned to a contra account.
example: false
default: false
externalId:
type: string
description: Search by external id.
nullable: true
example: 123e4567-e89b-12d3-a456-426614174011
ids:
uniqueItems: true
type: array
description: Filter by a list of account IDs.
nullable: true
items:
type: string
description: Filter by a list of account IDs.
format: uuid
nullable: true
name:
type: string
description: Search by name.
nullable: true
example: Bank Charges
description: Represents a request to search for accounts.
BookkeepingAccountUpdateRequestV1:
required:
- archived
- name
type: object
properties:
archived:
type: boolean
description: Boolean flag used to determine if the account is archived.
code:
maxLength: 255
minLength: 0
type: string
description: 'Account code or number used in the accounting system''s chart
of accounts. Maximum length: 255 characters.'
nullable: true
metadata:
type: object
additionalProperties:
type: object
description: Place for API users to store flexible data.
nullable: true
description: Place for API users to store flexible data.
nullable: true
name:
maxLength: 255
minLength: 0
type: string
description: 'Name of the account. Maximum length: 255 characters.'
taxCodeExternalId:
type: string
description: 'The identifier in **the target system** for the tax code the
account is associated with.
- This is NOT the tax percentage (e.g. 20%)
- This is NOT the Pleo UUID of the tax code'
nullable: true
description: Represents a request to update an account.
BookkeepingCategoryGroupTypeRestModelV5:
type: string
description: Bookkeeping category group types supported by Pleo. Used to classify
category groups in frontend.
enum:
- ENTERTAINMENT
- EQUIPMENT_AND_HARDWARE
- MARKETING_AND_ADVERTISING
- MEALS_AND_DRINKS
- OFFICE_EXPENSES
- PHONE_AND_INTERNET
- SERVICES_AND_CONSULTANCY
- SOFTWARE
- SUPPLIES
- TRAVEL
- OTHER
- NO_SUITABLE_CATEGORY
BookkeepingMethod:
type: string
description: Bookkeeping method supported by target system for accounting entries.
NONE means there would be no bookkeeping method used.
enum:
- NONE
- JOURNAL
- ACCOUNTS_PAYABLE
CursorPageCurrentRequestInfo:
required:
- parameters
type: object
properties:
after:
type: string
before:
type: string
limit:
type: integer
format: int32
offset:
type: integer
format: int64
parameters:
type: object
additionalProperties:
type: array
items:
type: string
sortingKeys:
type: array
items:
type: string
sortingOrder:
type: array
items:
$ref: '#/components/schemas/PageOrder'
CursorPageInfo:
required:
- currentRequestPagination
- hasNextPage
- hasPreviousPage
type: object
properties:
currentRequestPagination:
$ref: '#/components/schemas/CursorPageCurrentRequestInfo'
endCursor:
type: string
hasNextPage:
type: boolean
hasPreviousPage:
type: boolean
startCursor:
type: string
total:
type: integer
format: int64
CursorPaginatedResponseBookkeepingAccountRestModelV1:
required:
- data
- pagination
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/BookkeepingAccountRestModelV1'
pagination:
$ref: '#/components/schemas/CursorPageInfo'
DataResponseBookkeepingAccountBatchCreateResponseV1:
required:
- data
type: object
properties:
data:
$ref: '#/components/schemas/BookkeepingAccountBatchCreateResponseV1'
DataResponseBookkeepingAccountRestModelV1:
required:
- data
type: object
properties:
data:
$ref: '#/components/schemas/BookkeepingAccountRestModelV1'
PageOrder:
type: string
enum:
- ASC
- ASC_NULLS_FIRST
- ASC_NULLS_LAST
- DESC
- DESC_NULLS_FIRST
- DESC_NULLS_LAST
securitySchemes:
bearerAuth:
type: http
description: 'JWT Bearer token authentication. Include the token in the Authorization
header as: `Bearer <token>`'
scheme: bearer
bearerFormat: JWT
basicAuth:
type: http
description: Basic HTTP authentication using API key. Use your API key as the
username and leave the password empty. The credentials will be Base64 encoded
automatically.
scheme: basic