Pleo Bookkeeping Core API
RESTful API for managing bookkeeping accounts — creating, updating, searching, and deleting chart-of-accounts entries linked to Pleo company spend.
OpenAPI Specification
openapi: 3.0.1
info:
title: Bookkeeping Core 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: 12.2.0
servers:
- url: https://external.pleo.io
description: Production server
- url: https://external.staging.pleo.io
description: Staging server
security:
- bearerAuth: []
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 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.
'
- 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: 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-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).
components:
schemas:
BookkeepingAccountCreateRequestV4:
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.
nullable: true
companyId:
type: string
description: Pleo's internal identifier for the company the account is associated
with.
format: uuid
externalId:
maxLength: 255
minLength: 0
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 "
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
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.
BookkeepingAccountSearchRequestV4:
required:
- companyId
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'
companyId:
type: string
description: Filter by company ID.
format: uuid
example: 123e4567-e89b-12d3-a456-426614174011
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.
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.
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
CursorPaginatedResponseBookkeepingAccountRestModelV4:
required:
- data
- pagination
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/BookkeepingAccountRestModelV4'
pagination:
$ref: '#/components/schemas/CursorPageInfo'
DataResponseBookkeepingAccountRestModelV4:
required:
- data
type: object
properties:
data:
$ref: '#/components/schemas/BookkeepingAccountRestModelV4'
PageOrder:
type: string
enum:
- ASC
- ASC_NULLS_FIRST
- ASC_NULLS_LAST
- DESC
- DESC_NULLS_FIRST
- DESC_NULLS_LAST
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
x-readme:
explorer-enabled: true
proxy-enabled: true