{
  "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.\n\n💡**Note**\n\nPlease note that only response codes specific to the API behaviour are documented. Otherwise, we follow HTTP response codes.\n"
    },
    {
      "name": "Aggregated Bookkeeping Category Groups",
      "description": "This API enables you to read aggregated bookkeeping category groups.\n\n💡**Note**\n\nPlease 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.\n\n💡**Note**\n\nPlease note that only response codes specific to the API behaviour are documented. Otherwise, we follow HTTP response codes..\n"
    },
    {
      "name": "Bookkeeping Category Groups",
      "description": "This API enables you to perform operations on a bookkeeping category group.\n\n💡**Note**\n\nPlease 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.\n\n💡**Note**\n\nPlease note that only response codes specific to the API behaviour are documented. Otherwise, we follow HTTP response codes..\n"
    },
    {
      "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.\n\nOnly 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
  }
}