Clear Books
API docs by Redocly

Clear Books API (1.0.0)

Download OpenAPI specification:Download

Terms of Service

REST API for interfacing with Clear Books products

Authentication

This API uses OAuth 2 for authentication and authorisation. A compatible OAuth 2 client library or sufficient knowledge to implement an OAuth 2 client is required.

Only confidential clients are supported and must use the "Authorization code" grant type. PKCE is supported (and recommended) but not mandatory.

OAuth2

Security Scheme Type: OAuth2
Flow type: authorizationCode
Authorization URL: https://secure.clearbooks.co.uk/account/action/oauth/
Token URL: https://api.clearbooks.co.uk/oauth/token
Scopes:
  • businesses:read -

    Read business data

  • businesses:write -

    Update business data

  • accounting.account_codes:read -

    Read account codes

  • accounting.account_codes:write -

    Create, update and delete account codes

  • accounting.bank_accounts:read -

    Read bank accounts

  • accounting.bank_accounts:write -

    Create, update and delete bank accounts

  • accounting.customers:read -

    Read customers

  • accounting.customers:write -

    Create, update and delete customers

  • accounting.suppliers:read -

    Read suppliers

  • accounting.suppliers:write -

    Create, update and delete suppliers

  • accounting.sales:read -

    Read sales documents

  • accounting.sales:write -

    Create, update and delete sales documents

  • accounting.purchases:read -

    Read purchase documents

  • accounting.purchases:write -

    Create, update and delete purchase documents

  • accounting.payments:read -

    Read payments

  • accounting.payments:write -

    Create, update and delete payments

  • accounting.allocations:read -

    Read allocations

  • accounting.allocations:write -

    Create, update and delete allocations

  • accounting.stock_items:read -

    Read stock items

  • accounting.stock_items:write -

    Create, update and delete stock items

  • accounting.vat:read -

    Read VAT information

  • accounting.bank_feeds:write -

    Create bank feeds

  • accounting.bank_statements:write -

    Create bank statements

  • accounting.transactions:read -

    Read transactions

  • accounting.journals:write -

    Create journals

Registration

To obtain API credentials for your application, please contact us: https://www.clearbooks.co.uk/support/api/

Refresh tokens

Single use refresh tokens are issued alongside access tokens and don't expire until they're used.

Connection limits

Applications can only hold a single access token for a user at any given time. If a user completes the OAuth authorisation flow a second time for an application they have already authorised, then their previous access token and refresh token will be revoked and the newly issued ones will need to be used going forward.

Rate Limits

Applications making more than 5 requests per second for a sustained period may be subject to throttling and rate limiting.

When an application is being rate limited a HTTP 429 response will be returned for API calls. Rate limited requests should be retried using an exponential backoff algorithm.

Rate limits are subject to change without prior warning and should not be hard-coded into applications.

Pagination

Endpoints that support pagination will accept a limit parameter to define how many results to return per page (up to a maximum of 200), and a page parameter to select which page of results to return.

To help you understand the full result set without having to request all pages, all paginated responses will contain the following headers:

  • X-Pagination-Limit - The number of items per page of results
  • X-Pagination-Current-Page - The current page number
  • X-Pagination-Total-Pages - The total number of pages available
  • X-Pagination-Total-Count - The total number of results across all pages

Businesses

Businesses that the current user has access to

List all businesses for the current user

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a single business

Authorizations:
OAuth2
path Parameters
businessId
required
integer <int32>

ID of the business

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "type": "LimitedCompany",
  • "address": {
    },
  • "logoUrl": "string"
}

Update a business

Authorizations:
OAuth2
path Parameters
businessId
required
integer <int32>

ID of the business

Request Body schema: application/merge-patch+json

Updated business object

name
string
type
string
Enum: "LimitedCompany" "SoleTrader" "Partnership" "Charity" "Club" "Other"
object (Address)

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "type": "LimitedCompany",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "type": "LimitedCompany",
  • "address": {
    },
  • "logoUrl": "string"
}

Account Codes

An account code, often called a 'nominal code' defines an account in the chart of accounts of a business' accounting ledger

List all account codes

Authorizations:
OAuth2
query Parameters
sortBy
string

The field to sort results by

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an account code

Authorizations:
OAuth2
header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/json

Account code object

name
required
string
heading
required
integer <int32>
defaultVatRate
string
sales
boolean
purchases
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "heading": 0,
  • "defaultVatRate": "string",
  • "sales": true,
  • "purchases": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "heading": 0,
  • "defaultVatRate": "string",
  • "sales": true,
  • "purchases": true
}

Retrieve a single account code

Authorizations:
OAuth2
path Parameters
accountCodeId
required
integer <int32>

ID of account code

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update an account code

Authorizations:
OAuth2
path Parameters
accountCodeId
required
integer <int32>

ID of account code

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/merge-patch+json

Account code object

name
required
string
heading
required
integer <int32>
defaultVatRate
string
sales
boolean
purchases
boolean

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "heading": 0,
  • "defaultVatRate": "string",
  • "sales": true,
  • "purchases": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "heading": 0,
  • "defaultVatRate": "string",
  • "sales": true,
  • "purchases": true
}

Delete account code

Authorizations:
OAuth2
path Parameters
accountCodeId
required
integer <int32>

ID of account code

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Bank Accounts

A bank account represents either a real-world bank account in which the business has cash stored, or a logical store of cash defined by the business

List all bank accounts

Authorizations:
OAuth2
query Parameters
sortBy
string

The field to sort results by

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a bank account

Authorizations:
OAuth2
header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/json

Bank account object

name
required
string
accountNumber
string
sortCode
string
iban
string
swift
string
currency
string

ISO 4217 currency code. If omitted the home currency of the account is used.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "accountNumber": "string",
  • "sortCode": "string",
  • "iban": "string",
  • "swift": "string",
  • "currency": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "accountCode": 0,
  • "name": "string",
  • "accountNumber": "string",
  • "sortCode": "string",
  • "iban": "string",
  • "swift": "string",
  • "currency": "string",
  • "paymentMethods": [
    ]
}

Retrieve a single bank account

Authorizations:
OAuth2
path Parameters
bankAccountId
required
integer <int32>

ID of bank account

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a bank account

Authorizations:
OAuth2
path Parameters
bankAccountId
required
integer <int32>

ID of bank account

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/merge-patch+json

Bank account object

name
string
accountNumber
string
sortCode
string
iban
string
swift
string

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "accountNumber": "string",
  • "sortCode": "string",
  • "iban": "string",
  • "swift": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "accountCode": 0,
  • "name": "string",
  • "accountNumber": "string",
  • "sortCode": "string",
  • "iban": "string",
  • "swift": "string",
  • "currency": "string",
  • "paymentMethods": [
    ]
}

Delete bank account

Authorizations:
OAuth2
path Parameters
bankAccountId
required
integer <int32>

ID of bank account

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Customers

A customer represents an entity to which the business sells products or services

List all customers

Authorizations:
OAuth2
query Parameters
sortBy
string

The field to sort results by

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a customer

Authorizations:
OAuth2
header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/json

Customer object

name
required
string
object (ContactName)
email
string
phone
string
object (Address)
vatNumber
string
companyNumber
string
archived
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "contactName": {
    },
  • "email": "string",
  • "phone": "string",
  • "address": {
    },
  • "vatNumber": "string",
  • "companyNumber": "string",
  • "archived": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "contactName": {
    },
  • "email": "string",
  • "phone": "string",
  • "address": {
    },
  • "vatNumber": "string",
  • "companyNumber": "string",
  • "archived": true
}

Retrieve a single customer

Authorizations:
OAuth2
path Parameters
customerId
required
integer <int32>

ID of customer

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "contactName": {
    },
  • "email": "string",
  • "phone": "string",
  • "address": {
    },
  • "vatNumber": "string",
  • "companyNumber": "string",
  • "archived": true
}

Update a customer

Authorizations:
OAuth2
path Parameters
customerId
required
integer <int32>

ID of customer

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/merge-patch+json

Customer object

name
required
string
object (ContactName)
email
string
phone
string
object (Address)
vatNumber
string
companyNumber
string
archived
boolean

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "contactName": {
    },
  • "email": "string",
  • "phone": "string",
  • "address": {
    },
  • "vatNumber": "string",
  • "companyNumber": "string",
  • "archived": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "contactName": {
    },
  • "email": "string",
  • "phone": "string",
  • "address": {
    },
  • "vatNumber": "string",
  • "companyNumber": "string",
  • "archived": true
}

Delete customer

Authorizations:
OAuth2
path Parameters
customerId
required
integer <int32>

ID of customer

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Suppliers

A supplier represents an entity from which the business buys products or services

List all suppliers

Authorizations:
OAuth2
query Parameters
sortBy
string

The field to sort results by

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a supplier

Authorizations:
OAuth2
header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/json

Supplier object

name
required
string
object (ContactName)
email
string
phone
string
object (Address)
vatNumber
string
companyNumber
string
archived
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "contactName": {
    },
  • "email": "string",
  • "phone": "string",
  • "address": {
    },
  • "vatNumber": "string",
  • "companyNumber": "string",
  • "archived": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "contactName": {
    },
  • "email": "string",
  • "phone": "string",
  • "address": {
    },
  • "vatNumber": "string",
  • "companyNumber": "string",
  • "archived": true
}

Retrieve a single supplier

Authorizations:
OAuth2
path Parameters
supplierId
required
integer <int32>

ID of supplier

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "contactName": {
    },
  • "email": "string",
  • "phone": "string",
  • "address": {
    },
  • "vatNumber": "string",
  • "companyNumber": "string",
  • "archived": true
}

Update a supplier

Authorizations:
OAuth2
path Parameters
supplierId
required
integer <int32>

ID of supplier

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/merge-patch+json

Supplier object

name
required
string
object (ContactName)
email
string
phone
string
object (Address)
vatNumber
string
companyNumber
string
archived
boolean

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "contactName": {
    },
  • "email": "string",
  • "phone": "string",
  • "address": {
    },
  • "vatNumber": "string",
  • "companyNumber": "string",
  • "archived": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "contactName": {
    },
  • "email": "string",
  • "phone": "string",
  • "address": {
    },
  • "vatNumber": "string",
  • "companyNumber": "string",
  • "archived": true
}

Delete supplier

Authorizations:
OAuth2
path Parameters
supplierId
required
integer <int32>

ID of supplier

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Sales

Sales documents such as invoices, quotes and sales credit notes are issued to customers and represent a sale or prospective sale

List all sales documents of a given type (e.g invoices, quotes)

Authorizations:
OAuth2
path Parameters
salesType
required
string
Enum: "invoices" "creditNotes" "quotes"

Type of sales document

query Parameters
sortBy
string

The field to sort results by

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
Example
[ ]

Create a sales document of the given type

Authorizations:
OAuth2
path Parameters
salesType
required
string
Enum: "invoices" "creditNotes" "quotes"

Type of sales document

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/json

Sales document object

One of
documentNumber
string
date
required
string <date>
dateAccrual
string <date>
reference
string
currency
string

ISO 4217 currency code. If omitted the home currency of the account is used.

exchangeRate
double

Exchange rate from the home currency of the account to the specified currency for this document. May only be set if currency is provided. If omitted, will be provided automatically.

description
string

Referred to as "summary" in the Clear Books UI.

vatTreatment
required
string
required
Array of objects (LineItem)
customerId
required
integer <int32>
dateDue
string <date>
displayBankAccountId
integer <int32>

ID of a bank account whose details will be displayed on the print-formatted invoice.

internetPaymentAccountIds
Array of integers <int32> [ items <int32 > ]

List of bank account IDs for internet payment provider accounts. These will be made available for customer payments via the invoice web view. Instant Bank Payments, Stripe and PayPal accounts may be used. No more than one account per payment provider may be included. For Stripe, if the business has additional currency accounts configured, only the parent account ID should be used.

Responses

Request samples

Content type
application/json
Example
{
  • "documentNumber": "string",
  • "date": "2019-08-24",
  • "dateAccrual": "2019-08-24",
  • "reference": "string",
  • "currency": "string",
  • "exchangeRate": null,
  • "description": "string",
  • "vatTreatment": "string",
  • "lineItems": [
    ],
  • "customerId": 0,
  • "dateDue": "2019-08-24",
  • "displayBankAccountId": 0,
  • "internetPaymentAccountIds": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "documentNumber": "string",
  • "formattedDocumentNumber": "string",
  • "date": "2019-08-24",
  • "dateAccrual": "2019-08-24",
  • "datePaid": "2019-08-24",
  • "reference": "string",
  • "currency": "string",
  • "exchangeRate": null,
  • "description": "string",
  • "status": "string",
  • "gross": 0,
  • "net": 0,
  • "vat": 0,
  • "vatTreatment": "string",
  • "lineItems": [
    ],
  • "customerId": 0,
  • "dateDue": "2019-08-24",
  • "due": 0,
  • "displayBankAccountId": 0,
  • "internetPaymentAccountIds": [
    ]
}

Retrieve a single sales document

Retrieve a sales document. If the provided ID refers to a voided previous revision of a document, a redirect to the current revision will be returned.

Authorizations:
OAuth2
path Parameters
salesType
required
string
Enum: "invoices" "creditNotes" "quotes"

Type of sales document

salesId
required
integer <int32>

ID of sales document

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "documentNumber": "string",
  • "formattedDocumentNumber": "string",
  • "date": "2019-08-24",
  • "dateAccrual": "2019-08-24",
  • "datePaid": "2019-08-24",
  • "reference": "string",
  • "currency": "string",
  • "exchangeRate": null,
  • "description": "string",
  • "status": "string",
  • "gross": 0,
  • "net": 0,
  • "vat": 0,
  • "vatTreatment": "string",
  • "lineItems": [
    ],
  • "customerId": 0,
  • "dateDue": "2019-08-24",
  • "due": 0,
  • "displayBankAccountId": 0,
  • "internetPaymentAccountIds": [
    ]
}

Update a sales document

Update a sales document. For a non-draft invoice or credit note, the original document will be voided (soft deleted) and a new copy created with a new ID. For a quote or draft invoice, the document will be updated in-place and retain its original ID. You only need to provide the fields you want to update. No fields on the body of the document are required.

Authorizations:
OAuth2
path Parameters
salesType
required
string
Enum: "invoices" "creditNotes" "quotes"

Type of sales document

salesId
required
integer <int32>

ID of sales document

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/merge-patch+json

Sales document object

One of
documentNumber
string
date
required
string <date>
dateAccrual
string <date>
reference
string
currency
string

ISO 4217 currency code. If omitted the home currency of the account is used.

exchangeRate
double

Exchange rate from the home currency of the account to the specified currency for this document. May only be set if currency is provided. If omitted, will be provided automatically.

description
string

Referred to as "summary" in the Clear Books UI.

vatTreatment
required
string
required
Array of objects (LineItem)
customerId
required
integer <int32>
dateDue
string <date>
displayBankAccountId
integer <int32>

ID of a bank account whose details will be displayed on the print-formatted invoice.

internetPaymentAccountIds
Array of integers <int32> [ items <int32 > ]

List of bank account IDs for internet payment provider accounts. These will be made available for customer payments via the invoice web view. Instant Bank Payments, Stripe and PayPal accounts may be used. No more than one account per payment provider may be included. For Stripe, if the business has additional currency accounts configured, only the parent account ID should be used.

Responses

Request samples

Content type
application/merge-patch+json
Example
{
  • "documentNumber": "string",
  • "date": "2019-08-24",
  • "dateAccrual": "2019-08-24",
  • "reference": "string",
  • "currency": "string",
  • "exchangeRate": null,
  • "description": "string",
  • "vatTreatment": "string",
  • "lineItems": [
    ],
  • "customerId": 0,
  • "dateDue": "2019-08-24",
  • "displayBankAccountId": 0,
  • "internetPaymentAccountIds": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "documentNumber": "string",
  • "formattedDocumentNumber": "string",
  • "date": "2019-08-24",
  • "dateAccrual": "2019-08-24",
  • "datePaid": "2019-08-24",
  • "reference": "string",
  • "currency": "string",
  • "exchangeRate": null,
  • "description": "string",
  • "status": "string",
  • "gross": 0,
  • "net": 0,
  • "vat": 0,
  • "vatTreatment": "string",
  • "lineItems": [
    ],
  • "customerId": 0,
  • "dateDue": "2019-08-24",
  • "due": 0,
  • "displayBankAccountId": 0,
  • "internetPaymentAccountIds": [
    ]
}

Delete sales document

Delete a sales document. Non-draft invoices and credit notes will be voided (soft deleted). Quotes and draft invoices will be hard deleted.

Authorizations:
OAuth2
path Parameters
salesType
required
string
Enum: "invoices" "creditNotes" "quotes"

Type of sales document

salesId
required
integer <int32>

ID of sales document

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Purchases

Purchase documents such as bills, expenses and purchase credit notes are received from suppliers and represent a purchase or prospective purchase

List all purchase documents of a given type (e.g bills, expenses)

Authorizations:
OAuth2
path Parameters
purchaseType
required
string
Enum: "bills" "creditNotes" "expenses"

Type of purchase document

query Parameters
sortBy
string

The field to sort results by

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
Example
[ ]

Create a purchase document of the given type

Authorizations:
OAuth2
path Parameters
purchaseType
required
string
Enum: "bills" "creditNotes" "expenses"

Type of purchase document

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/json

Purchase document object

One of
documentNumber
string
date
required
string <date>
dateAccrual
string <date>
reference
string
currency
string

ISO 4217 currency code. If omitted the home currency of the account is used.

exchangeRate
double

Exchange rate from the home currency of the account to the specified currency for this document. May only be set if currency is provided. If omitted, will be provided automatically.

description
string

Referred to as "summary" in the Clear Books UI.

vatTreatment
required
string
required
Array of objects (LineItem)
supplierId
required
integer <int32>
dateDue
string <date>

Responses

Request samples

Content type
application/json
Example
{
  • "documentNumber": "string",
  • "date": "2019-08-24",
  • "dateAccrual": "2019-08-24",
  • "reference": "string",
  • "currency": "string",
  • "exchangeRate": null,
  • "description": "string",
  • "vatTreatment": "string",
  • "lineItems": [
    ],
  • "supplierId": 0,
  • "dateDue": "2019-08-24"
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "documentNumber": "string",
  • "formattedDocumentNumber": "string",
  • "date": "2019-08-24",
  • "dateAccrual": "2019-08-24",
  • "datePaid": "2019-08-24",
  • "reference": "string",
  • "currency": "string",
  • "exchangeRate": null,
  • "description": "string",
  • "status": "string",
  • "gross": 0,
  • "net": 0,
  • "vat": 0,
  • "due": 0,
  • "vatTreatment": "string",
  • "lineItems": [
    ],
  • "supplierId": 0,
  • "dateDue": "2019-08-24"
}

Retrieve a single purchase document

Retrieve a purchase document. If the provided ID refers to a voided previous revision of a document, a redirect to the current revision will be returned.

Authorizations:
OAuth2
path Parameters
purchaseType
required
string
Enum: "bills" "creditNotes" "expenses"

Type of purchase document

purchaseId
required
integer <int32>

ID of purchase document

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "documentNumber": "string",
  • "formattedDocumentNumber": "string",
  • "date": "2019-08-24",
  • "dateAccrual": "2019-08-24",
  • "datePaid": "2019-08-24",
  • "reference": "string",
  • "currency": "string",
  • "exchangeRate": null,
  • "description": "string",
  • "status": "string",
  • "gross": 0,
  • "net": 0,
  • "vat": 0,
  • "due": 0,
  • "vatTreatment": "string",
  • "lineItems": [
    ],
  • "supplierId": 0,
  • "dateDue": "2019-08-24"
}

Update a purchase document

Update a purchase document. For a non-draft bill or credit note, the original document will be voided (soft deleted) and a new copy created with a new ID. For a draft bill, the document will be updated in-place. You only need to provide the fields you want to update. No fields on the body of the document are required.

Authorizations:
OAuth2
path Parameters
purchaseType
required
string
Enum: "bills" "creditNotes" "expenses"

Type of purchase document

purchaseId
required
integer <int32>

ID of purchase document

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/merge-patch+json

Purchase document object

One of
documentNumber
string
date
required
string <date>
dateAccrual
string <date>
reference
string
currency
string

ISO 4217 currency code. If omitted the home currency of the account is used.

exchangeRate
double

Exchange rate from the home currency of the account to the specified currency for this document. May only be set if currency is provided. If omitted, will be provided automatically.

description
string

Referred to as "summary" in the Clear Books UI.

vatTreatment
required
string
required
Array of objects (LineItem)
supplierId
required
integer <int32>
dateDue
string <date>

Responses

Request samples

Content type
application/merge-patch+json
Example
{
  • "documentNumber": "string",
  • "date": "2019-08-24",
  • "dateAccrual": "2019-08-24",
  • "reference": "string",
  • "currency": "string",
  • "exchangeRate": null,
  • "description": "string",
  • "vatTreatment": "string",
  • "lineItems": [
    ],
  • "supplierId": 0,
  • "dateDue": "2019-08-24"
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "documentNumber": "string",
  • "formattedDocumentNumber": "string",
  • "date": "2019-08-24",
  • "dateAccrual": "2019-08-24",
  • "datePaid": "2019-08-24",
  • "reference": "string",
  • "currency": "string",
  • "exchangeRate": null,
  • "description": "string",
  • "status": "string",
  • "gross": 0,
  • "net": 0,
  • "vat": 0,
  • "due": 0,
  • "vatTreatment": "string",
  • "lineItems": [
    ],
  • "supplierId": 0,
  • "dateDue": "2019-08-24"
}

Delete purchase document

Delete a purchase document. Non-draft bills and credit notes will be voided (soft deleted). Draft bills will be hard deleted.

Authorizations:
OAuth2
path Parameters
purchaseType
required
string
Enum: "bills" "creditNotes" "expenses"

Type of purchase document

purchaseId
required
integer <int32>

ID of purchase document

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Payments

Payments received or made to cover a sale or purchase represent a transfer of money between the business and a customer or supplier

List all payments

Authorizations:
OAuth2
query Parameters
sortBy
string

The field to sort results by

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a payment

Authorizations:
OAuth2
header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/json

Payment object

date
required
string <date>

Bank date of the payment.

accountingDate
string <date>

Accounting date of the payment. Only needs to be provided on create if it differs from the bank date. If not provided, it will be automatically populated with the bank date.

description
required
string
amount
required
number <double>

Amount of the payment. Should be positive for money received, and negative for money paid out.

exchangeRate
float

Exchange rate from the home currency of the business to the currency of the specified bank account. May only be set if those currencies differ. If omitted on create, will be provided automatically. If omitted on update, the existing rate will be retained, unless you change the bank account to one in a different currency, in which case it will be replaced automatically. Otherwise, to discard the existing rate and have the system repopulate it automatically, set it to NULL.

contactId
required
integer <int32>
paymentMethodId
integer <int32>

ID of a payment method available for the specified bank account. Payment method is recorded for reference only and is only visible when viewing individual Clear Books bank transactions and customer/supplier payments reports.

bankAccountId
required
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "date": "2019-08-24",
  • "accountingDate": "2019-08-24",
  • "description": "string",
  • "amount": 0,
  • "exchangeRate": null,
  • "contactId": 0,
  • "paymentMethodId": 0,
  • "bankAccountId": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "date": "2019-08-24",
  • "accountingDate": "2019-08-24",
  • "description": "string",
  • "amount": 0,
  • "currency": "string",
  • "exchangeRate": null,
  • "contactId": 0,
  • "paymentMethodId": 0,
  • "bankAccountId": 0
}

Retrieve a single payment

Authorizations:
OAuth2
query Parameters
paymentId
integer <int32>

ID of payment

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "date": "2019-08-24",
  • "accountingDate": "2019-08-24",
  • "description": "string",
  • "amount": 0,
  • "currency": "string",
  • "exchangeRate": null,
  • "contactId": 0,
  • "paymentMethodId": 0,
  • "bankAccountId": 0
}

Update a payment

Authorizations:
OAuth2
query Parameters
paymentId
integer <int32>

ID of payment

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/merge-patch+json

Payment object

date
required
string <date>

Bank date of the payment.

accountingDate
string <date>

Accounting date of the payment. Only needs to be provided on create if it differs from the bank date. If not provided, it will be automatically populated with the bank date.

description
required
string
amount
required
number <double>

Amount of the payment. Should be positive for money received, and negative for money paid out.

exchangeRate
float

Exchange rate from the home currency of the business to the currency of the specified bank account. May only be set if those currencies differ. If omitted on create, will be provided automatically. If omitted on update, the existing rate will be retained, unless you change the bank account to one in a different currency, in which case it will be replaced automatically. Otherwise, to discard the existing rate and have the system repopulate it automatically, set it to NULL.

contactId
required
integer <int32>
paymentMethodId
integer <int32>

ID of a payment method available for the specified bank account. Payment method is recorded for reference only and is only visible when viewing individual Clear Books bank transactions and customer/supplier payments reports.

bankAccountId
required
integer <int32>

Responses

Request samples

Content type
application/merge-patch+json
{
  • "date": "2019-08-24",
  • "accountingDate": "2019-08-24",
  • "description": "string",
  • "amount": 0,
  • "exchangeRate": null,
  • "contactId": 0,
  • "paymentMethodId": 0,
  • "bankAccountId": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "date": "2019-08-24",
  • "accountingDate": "2019-08-24",
  • "description": "string",
  • "amount": 0,
  • "currency": "string",
  • "exchangeRate": null,
  • "contactId": 0,
  • "paymentMethodId": 0,
  • "bankAccountId": 0
}

Delete payment

Authorizations:
OAuth2
query Parameters
paymentId
integer <int32>

ID of payment

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Allocations

Allocations represent the association of a payment to an invoice or bill in order to clear or partly clear the balance

List allocations

Authorizations:
OAuth2
path Parameters
invoiceType
required
string
Enum: "sales" "purchases"

Type of invoice

query Parameters
allocationType
string
Enum: "creditNote" "payment"

Allocation item type

paymentId
integer <int32>

ID of payment

creditNoteId
integer <int32>

ID of credit note

invoiceId
integer <int32>

ID of a sales or purchase invoice

sortBy
string

The field to sort results by

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create an allocation

Payments and credit notes that use a different currency to the base currency of the Clear Books account, can only be allocated to invoices and bills of the same currency.

Authorizations:
OAuth2
path Parameters
invoiceType
required
string
Enum: "sales" "purchases"

Type of invoice

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/json

Payment allocation object

invoiceId
required
integer <int32>
paymentId
required
integer <int32>
allocationType
required
string
amount
required
number <double>

Responses

Request samples

Content type
application/json
Example
{
  • "invoiceId": 123,
  • "paymentId": 456,
  • "allocationType": "payment",
  • "amount": 100
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "invoiceId": 0,
  • "paymentId": 0,
  • "allocationType": "payment",
  • "amount": 0
}

Retrieve an allocation

Authorizations:
OAuth2
path Parameters
invoiceType
required
string
Enum: "sales" "purchases"

Type of invoice

allocationId
required
integer <int32>

ID of an allocation

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "invoiceId": 0,
  • "paymentId": 0,
  • "allocationType": "payment",
  • "amount": 0
}

Delete an allocation

Authorizations:
OAuth2
path Parameters
invoiceType
required
string
Enum: "sales" "purchases"

Type of invoice

allocationId
required
integer <int32>

ID of an allocation

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Stock Items

Stock items represent inventory that can be sold and purchased using sales and purchase documents

List all stock items

Authorizations:
OAuth2
query Parameters
sortBy
string

The field to sort results by

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a stock item

Authorizations:
OAuth2
header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/json

Stock item object

name
required
string
sku
string
type
required
string
Enum: "purchases" "sales" "both"
description
string
salesUnitPrice
number <double>
salesAccountCode
integer <int32>
salesVatRateKey
string
salesQuantity
integer <int32>
purchaseUnitPrice
number <double>
purchaseAccountCode
integer <int32>
purchaseVatRateKey
string
purchaseQuantity
integer <int32>
trackStock
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "sku": "string",
  • "type": "purchases",
  • "description": "string",
  • "salesUnitPrice": 0,
  • "salesAccountCode": 0,
  • "salesVatRateKey": "string",
  • "salesQuantity": 0,
  • "purchaseUnitPrice": 0,
  • "purchaseAccountCode": 0,
  • "purchaseVatRateKey": "string",
  • "purchaseQuantity": 0,
  • "trackStock": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "sku": "string",
  • "type": "purchases",
  • "description": "string",
  • "salesUnitPrice": 0,
  • "salesAccountCode": 0,
  • "salesVatRateKey": "string",
  • "salesQuantity": 0,
  • "purchaseUnitPrice": 0,
  • "purchaseAccountCode": 0,
  • "purchaseVatRateKey": "string",
  • "purchaseQuantity": 0,
  • "trackStock": true
}

Retrieve a single stock item

Authorizations:
OAuth2
path Parameters
stockItemId
required
integer <int32>

ID of stock item

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "sku": "string",
  • "type": "purchases",
  • "description": "string",
  • "salesUnitPrice": 0,
  • "salesAccountCode": 0,
  • "salesVatRateKey": "string",
  • "salesQuantity": 0,
  • "purchaseUnitPrice": 0,
  • "purchaseAccountCode": 0,
  • "purchaseVatRateKey": "string",
  • "purchaseQuantity": 0,
  • "trackStock": true
}

Update a stock item

Authorizations:
OAuth2
path Parameters
stockItemId
required
integer <int32>

ID of stock item

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/merge-patch+json

Stock item object

name
string
sku
string
type
string
Enum: "purchases" "sales" "both"
description
string
salesUnitPrice
number <double>
salesAccountCode
integer <int32>
salesVatRateKey
string
salesQuantity
integer <int32>
purchaseUnitPrice
number <double>
purchaseAccountCode
integer <int32>
purchaseVatRateKey
string
purchaseQuantity
integer <int32>
trackStock
boolean

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "sku": "string",
  • "type": "purchases",
  • "description": "string",
  • "salesUnitPrice": 0,
  • "salesAccountCode": 0,
  • "salesVatRateKey": "string",
  • "salesQuantity": 0,
  • "purchaseUnitPrice": 0,
  • "purchaseAccountCode": 0,
  • "purchaseVatRateKey": "string",
  • "purchaseQuantity": 0,
  • "trackStock": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "sku": "string",
  • "type": "purchases",
  • "description": "string",
  • "salesUnitPrice": 0,
  • "salesAccountCode": 0,
  • "salesVatRateKey": "string",
  • "salesQuantity": 0,
  • "purchaseUnitPrice": 0,
  • "purchaseAccountCode": 0,
  • "purchaseVatRateKey": "string",
  • "purchaseQuantity": 0,
  • "trackStock": true
}

Delete stock item

Authorizations:
OAuth2
path Parameters
stockItemId
required
integer <int32>

ID of stock item

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Sales Attachments

Files can be attached to sales documents for record keeping

List all attachments

Authorizations:
OAuth2
path Parameters
salesType
required
string
Enum: "invoices" "creditNotes" "quotes"

Type of sales document

salesId
required
integer <int32>

ID of sales document

query Parameters
sortBy
string

The field to sort results by

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an attachment

Authorizations:
OAuth2
path Parameters
salesType
required
string
Enum: "invoices" "creditNotes" "quotes"

Type of sales document

salesId
required
integer <int32>

ID of sales document

fileName
required
string

Name of file

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/octet-stream

Attachment object

object (AttachmentUpload)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "size": 0,
  • "dateUploaded": "string"
}

Retrieve a single attachment

Authorizations:
OAuth2
path Parameters
attachmentId
required
integer <int32>

ID of an attachment

salesType
required
string
Enum: "invoices" "creditNotes" "quotes"

Type of sales document

salesId
required
integer <int32>

ID of sales document

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "size": 0,
  • "dateUploaded": "string"
}

Delete attachment

Authorizations:
OAuth2
path Parameters
attachmentId
required
integer <int32>

ID of an attachment

salesType
required
string
Enum: "invoices" "creditNotes" "quotes"

Type of sales document

salesId
required
integer <int32>

ID of sales document

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Purchases Attachments

Files can be attached to purchase documents for record keeping

List all attachments

Authorizations:
OAuth2
path Parameters
purchaseType
required
string
Enum: "bills" "creditNotes" "expenses"

Type of purchase document

purchaseId
required
integer <int32>

ID of purchase document

query Parameters
sortBy
string

The field to sort results by

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an attachment

Authorizations:
OAuth2
path Parameters
purchaseType
required
string
Enum: "bills" "creditNotes" "expenses"

Type of purchase document

purchaseId
required
integer <int32>

ID of purchase document

fileName
required
string

Name of file

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/octet-stream

Attachment object

object (AttachmentUpload)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "size": 0,
  • "dateUploaded": "string"
}

Retrieve a single attachment

Authorizations:
OAuth2
path Parameters
attachmentId
required
integer <int32>

ID of an attachment

purchaseType
required
string
Enum: "bills" "creditNotes" "expenses"

Type of purchase document

purchaseId
required
integer <int32>

ID of purchase document

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "size": 0,
  • "dateUploaded": "string"
}

Delete attachment

Authorizations:
OAuth2
path Parameters
attachmentId
required
integer <int32>

ID of an attachment

purchaseType
required
string
Enum: "bills" "creditNotes" "expenses"

Type of purchase document

purchaseId
required
integer <int32>

ID of purchase document

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

VAT

VAT rates and treatments represent the valid VAT settings that can be used on sales and purchase documents

List VAT treatments

Authorizations:
OAuth2
path Parameters
vatType
required
string
Enum: "sales" "purchases"

Type of VAT

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List VAT rates

Authorizations:
OAuth2
path Parameters
vatType
required
string
Enum: "sales" "purchases"

Type of VAT

query Parameters
vatTreatment
string

VAT treatment

date
string <date>

Date

contactId
integer <int32>

A customer or supplier ID

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Bank Feeds

Bank feeds allow financial institutions to send transaction data direct to Clear Books and have it associated with a bank account

Create a bank feed

Linking to an existing bank account

A bank feed can be created for an existing Clear Books bank account in one of two ways:

  1. By specifying an accountId returned from one of the bank accounts endpoints.

  2. By providing and accountNumber and sortCode that match an account which already exists in Clear Books.

Creating a new bank account

If a bank account does not already exist in Clear Books for the bank feed you wish to create, then you must provide enough information to allow us to create an account for you. The required fields in this case are name, accountNumber and sortCode.

If an existing bank account that matches this information is found, then it will be used and no extra account will be created.

Authorizations:
OAuth2
header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/json
Array of objects (BankFeed)

Responses

Request samples

Content type
application/json
Example
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Bank Statements

Bank Statements represent transactions ready to be explained

Create a bank statement

Statement consolidation

Clear Books will consolidate statements posted using this API call into monthly statements ready to be explained. One statement in Clear Books will be maintained for each calendar month based on the transaction date.

The IDs returned by this call represent the statement that the posted transactions were added to, regardless of whether a new statement was created or the transactions were appended to an existing statement.

Deduplication

Clear Books will ignore transactions with a transactionId that has already been used for the same bank feed. No attempt is made to deduplicate transactions based on any other properties. Please ensure that each individual transaction you send has a consistent, unique ID.

Authorizations:
OAuth2
header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/json
Array of objects (BankStatement)

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Transactions

A transaction represents a movement of money between a business's accounts

List transactions

Authorizations:
OAuth2
query Parameters
accountingDateFrom
string <date>

Return results from this accounting date. Date format 'YYYY-MM-DD'

accountingDateTo
string <date>

Return results to this accounting date. Date format 'YYYY-MM-DD'

sortBy
string
Enum: "id" "accountingDate"

The field to sort results by. Default value 'id'

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

General Ledger

The general ledger lists debits and credits from all transactions

Get general ledger

Authorizations:
OAuth2
query Parameters
transactionId
integer

Filter by this transaction ID

accountCodeId
integer

Filter by this account code ID

accountingDateFrom
string <date>

Return results from this accounting date. Date format 'YYYY-MM-DD'

accountingDateTo
string <date>

Return results to this accounting date. Date format 'YYYY-MM-DD'

sortBy
string
Enum: "transactionId" "accountingDate" "accountCodeId" "amount"

The field to sort results by. Default value 'transactionId'

sortDirection
string
Enum: "ascending" "descending"

The direction to sort the results

limit
integer <int32> [ 1 .. 200 ]
Default: 25

The number of results to return

page
integer <int32> >= 1
Default: 1

The page of results to return

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Trial Balance

The trial balance lists the balances of all of the business's accounts

Get trial balance

Authorizations:
OAuth2
query Parameters
accountingDateFrom
required
string <date>

Return results from this accounting date. Date format 'YYYY-MM-DD'

accountingDateTo
required
string <date>

Return results to this accounting date. Date format 'YYYY-MM-DD'

header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Journals

A journal is a type of transaction created to move money between accounts outside of normal business operations

Create a journal

The sum of amounts of all lines in the journal must add up to 0.

Authorizations:
OAuth2
header Parameters
X-Business-ID
integer <int32>

ID of the business to use (required for multi-business authorisations only)

Request Body schema: application/json

Journal object

accountingDate
string <date>
description
string
Array of objects (JournalLine)

Responses

Request samples

Content type
application/json
{
  • "description": "example journal",
  • "accountingDate": "2022-02-22",
  • "lines": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "accountingDate": "2019-08-24",
  • "description": "string",
  • "lines": [
    ]
}