openapi: 3.0.1
info:
  title: Chart of Accounts API
  description: Bookkeeping Core OpenAPI definitions
  termsOfService: https://pleo.io/terms/
  contact:
    email: team.actina@pleo.io
  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