This API enables you to create an account in Pleo, search for an account by its specific 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.
openapi: 3.0.1
info:
title: App Marketplace accounting-entries Accounts API
description: API for Pleo App Marketplace
termsOfService: https://pleo.io/terms/
contact:
email: partner-ecosystem-team@pleo.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 39.4.0
servers:
- url: https://external.pleo.io
description: Production server
- url: https://external.staging.pleo.io
description: Staging server
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Accounts
description: 'This API enables you to create an account in Pleo, search for an account by its specific 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.
'
paths:
/v1-beta/accounts:
post:
tags:
- Accounts
summary: Create a new account.
description: "\n The integration sends a request to this endpoint to create a corresponding account in Pleo for any \n new record created in the external ERP/accounting system. The request fails if any similar accounts with \n the same `externalId` and `companyId` already exists in Pleo.\n "
operationId: createAccountV4
requestBody:
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/BookkeepingAccountCreateRequestV4'
required: true
responses:
'200':
description: Request matched existing account.
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseBookkeepingAccountRestModelV4'
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/DataResponseBookkeepingAccountRestModelV4'
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 (e.g. missing required fields).
'409':
description: "\n Conflict (account with the same `externalId` exists in Pleo)\n "
/v1-beta/accounts/{accountId}:
get:
tags:
- Accounts
summary: Retrieves an account in Pleo by its ID.
description: Search for a specific account by its account ID.
operationId: getAccountV4
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/DataResponseBookkeepingAccountRestModelV4'
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: "\n Update details of an existing account in Pleo. The integration must send a request to this endpoint \n when it is trying to archive an account linked to accounting entries.\n "
operationId: updateAccountV4
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/BookkeepingAccountUpdateRequestV4'
required: true
responses:
'200':
description: Update of account successful.
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponseBookkeepingAccountRestModelV4'
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 (e.g. 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 be archived instead. Use UPDATE endpoint to archive an account.'
operationId: deleteAccountV4
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-beta/accounts:search:
post:
tags:
- Accounts
summary: Fetch a list of accounts
description: Retrieves a list of accounts with optional filters for companyId, ids, name, code and archived status. Results are paginated.
operationId: searchAccountsV4
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:
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:
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/BookkeepingAccountSearchRequestV4'
required: true
responses:
'200':
description: Fetch of accounts successful.
content:
application/json:
schema:
$ref: '#/components/schemas/CursorPaginatedResponseBookkeepingAccountRestModelV4'
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 (e.g. missing required fields, tax code does not exist in Pleo).
/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:
BookkeepingAccountRestModelV4:
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: "\n Unique external identifier of account, assigned in the external ERP/accounting system. \n Can be the same as code if no other identifier is available.\n "
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.
DataResponseBookkeepingAccountRestModelV1:
required:
- data
type: object
properties:
data:
$ref: '#/components/schemas/BookkeepingAccountRestModelV1'
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
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'
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.
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.'
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.
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.
BookkeepingAccountUpdateRequestV4:
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.
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.
taxCodeExternalId:
type: string
description: "\n The identifier in **the target system** for the tax code the account is associated with.\n - This is NOT the tax percentage (e.g. 20%)\n - This is NOT the Pleo UUID of the tax code\n "
nullable: true
description: Represents a request to update an account.
CursorPaginatedRespo
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pleo/refs/heads/main/openapi/pleo-accounts-api-openapi.yml