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