Introduction

The CashCtrl API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

The API is only available to PRO users as it requires an API user for each organization you manage, more about that in the next section: Authentication.

To test the API you can clone your main organization into a test organization and create an API user there. To do this in CashCtrl, go to Settings  Organizations  Copy.

Base URL

https://myorg.cashctrl.com/api/v1
Note that myorg is the sub-domain of the organization you're accessing.

Authentication

The CashCtrl API uses API keys to authenticate requests. You can view and manage your API keys in CashCtrl under Settings  Users & Roles.

You have to create an API user for each organization that you would like to access. This means that an API user can only access one organization and has the permissions defined by the role you've assigned to the API user.

You can add a new API user under Settings  Users & Roles  Add  Add API user.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password. This is done for every request, not just once.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Example

Retrieving the journal book entries list via curl:

curl https://myorg.cashctrl.com/api/v1/journal/list.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b:

Note: Replace zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b with your API key. The colon after the key prevents curl from asking for a password.

Error handling

CashCtrl uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success (except for validation errors). Codes in the 4xx range indicate an issue with the request, for example unauthorized, forbidden or not found. Codes in the 5xx range indicate an error with our servers (these are rare).

However, response codes are not used to indicate form validation errors (like a missing ID or incorrect date). Instead, you will get a HTTP 200 OK and the JSON response will contain a field named "success" which is either true or false. If false, there will be another field named "errors" which contains one or multiple errors, see example response.

HTTP status codes

200 - OK 200 - OKEverything worked as expected. However, form validation errors are still possible, see example response.
401 - Unauthorized 401 - UnauthorizedNo valid API key provided.
403 - Forbidden 403 - ForbiddenThe API key doesn't have permissions to perform the request.
404 - Not Found 404 - Not FoundThe requested endpoint doesn't exist.
405 - Method Not Allowed 405 - Method Not AllowedThe HTTP method (GET, POST, etc.) used is not allowed.
418 - I'm a teapot 418 - I'm a teapotError you get when CashCtrl is a teapot and not a coffee pot.
429 - Too Many Requests 429 - Too Many RequestsToo many requests hit the API too quickly. We recommend adding delays between your requests. For more information, see our Terms of Service.
500, 502, 503, 504 - Server Errors 500, 502, 503, 504 - Server ErrorsSomething went wrong on our end - not your fault. Please contact support.

Example response

This is an example response with a HTTP status of 200 but containing form validation errors:

{
    "success": false,
    "errors": [
        {
            "field": "debitId",
            "message": "This field cannot be empty."
        },
        {
            "field": "creditId",
            "message": "This field cannot be empty."
        },
        {
            "field": "amount",
            "message": "This field cannot be empty."
        }
    ]
}

Language

Unlike a regular user an API user does not have user preferences with a defined language. Instead the desired language is sent with each request. Simply add the following request parameter: lang (e.g. lang=en).

Available languages: de, fr, it, en.

For most JSON requests the language won't matter as the response only contains data, and the data may contain all languages or more accurately the languages of the data that has been entered by the user. It matters mostly for error messages and generated PDFs, Excel sheets and CSV files which will come in one language only.

Example

Retrieving the annual report PDF in German via curl:

curl https://myorg.cashctrl.com/api/v1/report/set/download_annualreport.pdf?lang=de -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b:

Examples

The following examples use cURL to perform various tasks via the API.

Note for all examples: Replace myorg with the sub-domain of the organization you're accessing. And replace zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b with your API key. The colon after the key prevents curl from asking for a password.

Get journal book entries

Retrieves the journal book entries for the current fiscal period:

curl https://myorg.cashctrl.com/api/v1/journal/list.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b:

Add a new location

Adds a location for your organization. This includes uploading a file. For this to work, make sure a file named logo.jpg exists in the same folder.

curl https://myorg.cashctrl.com/api/v1/location/create.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "name=Maria Muster Headquarters" -F "orgName=Maria Muster Inc." -F "logoFile=@logo.jpg"

Import vCards

Imports a vCard (.vcf) file into the list of people. For this to work, make sure a vCard file named people.vcf exists in the same folder.

curl https://myorg.cashctrl.com/api/v1/person/vcard/import.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "file=@people.vcf" -F "execute=true"

Add a manual book entry

Creates a new book entry in the journal. You may need to adapt the account IDs (debitId/creditId) according to your chart of accounts:

curl https://myorg.cashctrl.com/api/v1/journal/create.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "dateAdded=2020-07-06" -F "title=API generated book entry" -F "sequenceNumberId=6" -F "debitId=1" -F "creditId=15" -F "taxId=1" -F "amount=500"

Add a collective book entry

Creates a new collective book entry in the journal. The items are encoded as JSON, which has to be properly escaped:

curl https://myorg.cashctrl.com/api/v1/journal/create.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "dateAdded=2020-07-06" -F "title=API generated collective entry" -F "sequenceNumberId=6" -F "items=[{\"accountId\":1,\"debit\":500},{\"accountId\":42,\"credit\":250},{\"accountId\":15,\"credit\":250}]"

Add an invoice

Creates a new sales invoice. The items are encoded as JSON, which has to be properly escaped. This example also creates a new person named "New customer" (use a person ID otherwise).

curl https://myorg.cashctrl.com/api/v1/order/create.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "categoryId=4" -F "date=2020-07-06" -F "sequenceNumberId=1" -F "description=API generated invoice" -F "associateId=New customer" -F "accountId=4" -F "roundingId=1" -F "items=[{\"accountId\":15,\"taxId\":1,\"unitId\":2,\"articleNr\":\"S-0002\",\"quantity\":6,\"name\":\"Design\",\"unitPrice\":172.32},{\"accountId\":15,\"taxId\":1,\"unitId\":2,\"articleNr\":\"S-0001\",\"quantity\":15,\"name\":\"Web development\",\"unitPrice\":172.32}]"

Add person with custom fields

Creates a new person with additional custom fields. Custom fields are XML-encoded. Assuming two custom fields with identifier customField1 and customField2 have been created beforehand:

curl https://myorg.cashctrl.com/api/v1/person/create.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "firstName=Stefan" -F "lastName=Meier" --form-string "custom=<values><customField1>Blue</customField1><customField2>Vanilla</customField2></values>"

Get the annual report PDF

Retrieves the annual report PDF in French:

curl https://myorg.cashctrl.com/api/v1/report/set/download_annualreport.pdf?lang=fr -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b:

Account

The following API endpoints are for managing accounts. To avoid confusion: We are talking about financial accounts (assets, liabilities, etc.), not user accounts.

Read account

Returns a single account by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/account/read.json

List accounts

Returns a list of all accounts.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter the list by. See Account category.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the balances. Leave empty to use the current fiscal period. See Switch fiscal period.

onlyActiveonlyActive
BOOLEAN

Flag to only include active accounts. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'number'.

Endpoint

GET /api/v1/account/list.json

Export to Excel

Returns an Excel file of the account list.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter the list by. See Account category.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the balances. Leave empty to use the current fiscal period. See Switch fiscal period.

onlyActiveonlyActive
BOOLEAN

Flag to only include active accounts. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'number'.

Endpoint

GET /api/v1/account/list.xlsx

Export to CSV

Returns a CSV file of the account list.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter the list by. See Account category.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the balances. Leave empty to use the current fiscal period. See Switch fiscal period.

onlyActiveonlyActive
BOOLEAN

Flag to only include active accounts. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'number'.

Endpoint

GET /api/v1/account/list.csv

Export to PDF

Returns a PDF file of the account list.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter the list by. See Account category.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the balances. Leave empty to use the current fiscal period. See Switch fiscal period.

onlyActiveonlyActive
BOOLEAN

Flag to only include active accounts. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'number'.

Endpoint

GET /api/v1/account/list.pdf

Get account balance

Returns the balance of a single account for the given date.

Parameters

idid
mandatory
NUMBER

The ID of the account.

datedate
DATE

The date for the balance (always end of day). Defaults to the last day of the current fiscal period. See Switch fiscal period.

Format: YYYY-MM-DD. Example: 2020-01-15.

Endpoint

GET /api/v1/account/balance

Create account

Creates a new account. The account number must be unique. Returns either a success or multiple error messages (for each issue).

Parameters

categoryIdcategoryId
mandatory
NUMBER

The ID of the category. See Account category.

namename
mandatory
TEXT
MAX:100

The name of the account.

numbernumber
mandatory
TEXT
MAX:20

The account number. Must be numeric but can contain a decimal point.

currencyIdcurrencyId
NUMBER

The ID of the account's currency. Leave empty to use the default currency. See Currency.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

isInactiveisInactive
BOOLEAN

Mark this account as inactive. Inactive accounts are greyed out in the list and are no longer suggested by the app. Possible values: true, false.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

targetMaxtargetMax
NUMBER

The target maximum balance (aka budget) you hope this account to stay beneath of by the end of the fiscal period. This will then be displayed by the Targets report, comparing your target to the actual balance. Please first switch to the desired fiscal period to set the target for that period, see Switch fiscal period.

targetMintargetMin
NUMBER

The target minimum balance you hope this account to hit by the end of the fiscal period. This will then be displayed by the Targets report, comparing your target to the actual balance. Please first switch to the desired fiscal period to set the target for that period, see Switch fiscal period.

taxIdtaxId
NUMBER

The ID of the tax rate associated with this account. See Tax rates.

Endpoint

POST /api/v1/account/create.json

Update account

Updates an existing account. Returns either a success or multiple error messages (for each issue).

Parameters

categoryIdcategoryId
mandatory
NUMBER

The ID of the category. See Account category.

idid
mandatory
NUMBER

The ID of the account to update.

namename
mandatory
TEXT
MAX:100

The name of the account.

numbernumber
mandatory
TEXT
MAX:20

The account number. Must be numeric but can contain a decimal point.

currencyIdcurrencyId
NUMBER

The ID of the account's currency. Leave empty to use the default currency. See Currency.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

isInactiveisInactive
BOOLEAN

Mark this account as inactive. Inactive accounts are greyed out in the list and are no longer suggested by the app. Possible values: true, false.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

targetMaxtargetMax
NUMBER

The target maximum balance (aka budget) you hope this account to stay beneath of by the end of the fiscal period. This will then be displayed by the Targets report, comparing your target to the actual balance. Please first switch to the desired fiscal period to set the target for that period, see Switch fiscal period.

targetMintargetMin
NUMBER

The target minimum balance you hope this account to hit by the end of the fiscal period. This will then be displayed by the Targets report, comparing your target to the actual balance. Please first switch to the desired fiscal period to set the target for that period, see Switch fiscal period.

taxIdtaxId
NUMBER

The ID of the tax rate associated with this account. See Tax rates.

Endpoint

POST /api/v1/account/update.json

Delete accounts

Deletes one or multiple accounts. Only unused accounts can be deleted (accounts without any journal entries). Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/account/delete.json

Categorize accounts

Assigns one or multiple accounts to the desired category. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the entries to categorize, comma-separated.

targettarget
mandatory
NUMBER

The ID of the target category.

Endpoint

POST /api/v1/account/categorize.json

Category

The following API endpoints are for managing account categories. Note that the top categories (assets, liabilities, etc.) cannot be manipulated.

Read category

Returns a single category by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/account/category/read.json

Get tree of categories

Returns a tree of all categories or the tree below a parent category.

Parameters

idid
NUMBER

Optional ID of the parent category (omit to get all categories).

Endpoint

GET /api/v1/account/category/tree.json

Create category

Creates a new category. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:100

The name of the account category.

numbernumber
TEXT
MAX:20

The number of the account category according to the chart of accounts. Must be numeric. This is used for sorting the categories.

parentIdparentId
NUMBER

The ID of the parent category.

Endpoint

POST /api/v1/account/category/create.json

Update category

Updates an existing category. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the category to update.

namename
mandatory
TEXT
MAX:100

The name of the account category.

numbernumber
TEXT
MAX:20

The number of the account category according to the chart of accounts. Must be numeric. This is used for sorting the categories.

parentIdparentId
NUMBER

The ID of the parent category.

Endpoint

POST /api/v1/account/category/update.json

Delete categories

Deletes one or multiple existing category. Note that you can only delete empty categories. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/account/category/delete.json

Currency

The following API endpoints are for managing currencies.

Read currency

Returns a single currency by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/currency/read.json

List currencies

Returns a list of all currencies.

Endpoint

GET /api/v1/currency/list.json

Create currency

Creates a new currency. The currency code must be unique. Returns either a success or multiple error messages (for each issue).

Parameters

codecode
mandatory
TEXT
MIN:3
MAX:3

The 3-characters currency code, like CHF, EUR, etc.

descriptiondescription
TEXT
MAX:100

An optional description of the currency.

isDefaultisDefault
BOOLEAN

Use the currency as the default / main currency. This can only be set if there are no book entries yet. Defaults to false. Possible values: true, false.

raterate
NUMBER

The exchange rate of this currency into the default currency. If this currency is the default currency, then the rate is 1. For most currencies, CashCtrl automatically retrieves the exchange rate, so this doesn't have to be set and will be ignored. Only set the rate for unsupported currencies. For supported currencies, see Get exchange rate.

Endpoint

POST /api/v1/currency/create.json

Update currency

Updates an existing currency. Returns either a success or multiple error messages (for each issue).

Parameters

codecode
mandatory
TEXT
MIN:3
MAX:3

The 3-characters currency code, like CHF, EUR, etc.

idid
mandatory
NUMBER

The ID of the currency to update.

descriptiondescription
TEXT
MAX:100

An optional description of the currency.

isDefaultisDefault
BOOLEAN

Use the currency as the default / main currency. This can only be set if there are no book entries yet. Defaults to false. Possible values: true, false.

raterate
NUMBER

The exchange rate of this currency into the default currency. If this currency is the default currency, then the rate is 1. For most currencies, CashCtrl automatically retrieves the exchange rate, so this doesn't have to be set and will be ignored. Only set the rate for unsupported currencies. For supported currencies, see Get exchange rate.

Endpoint

POST /api/v1/currency/update.json

Delete currencies

Deletes one or multiple currencies. Only unused currencies can be deleted, and the main currency cannot be deleted (switch first). Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/currency/delete.json

Get exchange rate

Returns the exchange rate between two currencies for a specific date.

Parameters

fromfrom
mandatory
TEXT

The source currency to convert. Possible values: AUD, BTC, CAD, CHF, CNY, DKK, EUR, GBP, INR, JPY, RUB, SEK, THB, USD.

toto
mandatory
TEXT

The target currency to convert into. Possible values: AUD, BTC, CAD, CHF, CNY, DKK, EUR, GBP, INR, JPY, RUB, SEK, THB, USD.

datedate
DATE

The date for the exchange rate. Leave empty to use today.

Format: YYYY-MM-DD. Example: 2020-01-15.

Endpoint

GET /api/v1/currency/exchangerate

Custom field

The following API endpoints are for managing custom fields. An infinite number of custom fields can be defined for all main modules (Journal, Account, Inventory, Order, Person).

Read custom field

Returns a single custom field by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/customfield/read.json

List custom fields

Returns a list of custom fields by type.

Parameters

typetype
mandatory
TEXT

The type of custom field, meaning: which module the custom field belongs to. Possible values: JOURNAL, ACCOUNT, PERSON, INVENTORY_STOCK, INVENTORY_SERVICE, INVENTORY_ASSET, ORDER.

Endpoint

GET /api/v1/customfield/list.json

Create custom field

Creates a new custom field for the given type. Returns either a success or multiple error messages (for each issue).

Parameters

dataTypedataType
mandatory
TEXT

The data type of the custom field. Possible values: TEXT, TEXTAREA, CHECKBOX, DATE, COMBOBOX, NUMBER.

namename
mandatory
TEXT
MAX:100

The name of the custom field.

typetype
mandatory
TEXT

The type of custom field, meaning: which module the custom field belongs to. Possible values: JOURNAL, ACCOUNT, PERSON, INVENTORY_STOCK, INVENTORY_SERVICE, INVENTORY_ASSET, ORDER.

descriptiondescription
TEXT
MAX:250

An optional description of the custom field.

groupIdgroupId
TEXT

The ID of the custom field group. If empty, the custom field is in the default group 'More'. Groups are basically displayed as tabs in the edit dialog, whereas the default tab is 'More'.

isInactiveisInactive
BOOLEAN

Mark the custom field as inactive. Inactive custom fields are no longer displayed anywhere. However, the data is not removed, as opposed to deleting the custom field. Defaults to false. Possible values: true, false.

isMultiisMulti
BOOLEAN

Is the custom field a multi-field? Multi-fields can have multiple values. The data is then stored as JSON array, like for example ["val1", "val2", "val3"]. Defaults to false. Possible values: true, false.

valuesvalues
TEXT

Values the user can choose from, if the data type is COMBOBOX. Ignored otherwise. Use the JSON format like this: ["red","green","blue"]. Note that these values are not enforced, the user can still set arbitrary text as the custom field value.

Endpoint

POST /api/v1/customfield/create.json

Update custom field

Updates an existing custom field. Returns either a success or multiple error messages (for each issue).

Parameters

dataTypedataType
mandatory
TEXT

The data type of the custom field. Possible values: TEXT, TEXTAREA, CHECKBOX, DATE, COMBOBOX, NUMBER.

idid
mandatory
NUMBER

The ID of the custom field to update.

namename
mandatory
TEXT
MAX:100

The name of the custom field.

typetype
mandatory
TEXT

The type of custom field, meaning: which module the custom field belongs to. Possible values: JOURNAL, ACCOUNT, PERSON, INVENTORY_STOCK, INVENTORY_SERVICE, INVENTORY_ASSET, ORDER.

descriptiondescription
TEXT
MAX:250

An optional description of the custom field.

groupIdgroupId
TEXT

The ID of the custom field group. If empty, the custom field is in the default group 'More'. Groups are basically displayed as tabs in the edit dialog, whereas the default tab is 'More'.

isInactiveisInactive
BOOLEAN

Mark the custom field as inactive. Inactive custom fields are no longer displayed anywhere. However, the data is not removed, as opposed to deleting the custom field. Defaults to false. Possible values: true, false.

isMultiisMulti
BOOLEAN

Is the custom field a multi-field? Multi-fields can have multiple values. The data is then stored as JSON array, like for example ["val1", "val2", "val3"]. Defaults to false. Possible values: true, false.

valuesvalues
TEXT

Values the user can choose from, if the data type is COMBOBOX. Ignored otherwise. Use the JSON format like this: ["red","green","blue"]. Note that these values are not enforced, the user can still set arbitrary text as the custom field value.

Endpoint

POST /api/v1/customfield/update.json

Delete custom field

Deletes one or multiple custom fields. Note that you can delete custom fields even if they hava data. All data of deleted custom fields will be lost. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/customfield/delete.json

Reorder custom fields

Changes the order of one or multiple custom fields. This is the order in which the custom fields are displayed. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the entries to reorder, comma-separated.

targettarget
mandatory
NUMBER

The ID of the target entry. The entries (see ids) will be ordered before or after (see before) this entry.

beforebefore
BOOLEAN

Reorder before the target entry, after otherwise. Defaults to true. Possible values: true, false.

Endpoint

POST /api/v1/customfield/reorder.json

Custom field group

The following API endpoints are for managing custom field groups. A group is displayed as a tab in the edit dialog (e.g. of an article), and you can have multiple such tabs to maintain a tidy UI. Custom fields that do not have a group go in a tab named 'More' by default.

Read custom field group

Returns a single custom field group by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/customfield/group/read.json

List custom field groups

Returns a list of custom field groups.

Parameters

typetype
TEXT

The type of custom field group, meaning: which module the custom field group belongs to. Possible values: JOURNAL, ACCOUNT, PERSON, INVENTORY_STOCK, INVENTORY_SERVICE, INVENTORY_ASSET, ORDER.

Endpoint

GET /api/v1/customfield/group/list.json

Create custom field group

Creates a new custom field group. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:50

The name of the group.

typetype
mandatory
TEXT

The type of group, meaning: which module the group belongs to. Possible values: JOURNAL, ACCOUNT, PERSON, INVENTORY_STOCK, INVENTORY_SERVICE, INVENTORY_ASSET, ORDER.

Endpoint

POST /api/v1/customfield/group/create.json

Update custom field group

Updates an existing custom field group. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the group to update.

namename
mandatory
TEXT
MAX:50

The name of the group.

typetype
mandatory
TEXT

The type of group, meaning: which module the group belongs to. Possible values: JOURNAL, ACCOUNT, PERSON, INVENTORY_STOCK, INVENTORY_SERVICE, INVENTORY_ASSET, ORDER.

Endpoint

POST /api/v1/customfield/group/update.json

Delete custom field group

Deletes one or multiple custom field groups. This does not delete any custom fields, and no data will be lost. The custom fields in that group just won't have a group anymore and will be displayed in the default 'More' tab. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/customfield/group/delete.json

Reorder custom field groups

Changes the order of one or multiple custom field groups. This is the order in which the tabs are displayed in the edit dialog. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the entries to reorder, comma-separated.

targettarget
mandatory
NUMBER

The ID of the target entry. The entries (see ids) will be ordered before or after (see before) this entry.

beforebefore
BOOLEAN

Reorder before the target entry, after otherwise. Defaults to true. Possible values: true, false.

Endpoint

POST /api/v1/customfield/group/reorder.json

File

The following API endpoint is for retrieving uploaded files.

Get file

Returns a file by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/file/get

Rounding

The following API endpoints are for managing roundings. These rounding configurations are mainly used for rounding the grand total of orders (invoices, etc.).

Read rounding

Returns a single rounding by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/rounding/read.json

List roundings

Returns a list of all roundings.

Endpoint

GET /api/v1/rounding/list.json

Create rounding

Creates a new rounding. Returns either a success or multiple error messages (for each issue).

Parameters

accountIdaccountId
mandatory
NUMBER

The ID of the account onto which the rounding amount is booked.

namename
mandatory
TEXT
MAX:100

A name to describe the rounding method (e.g. 'Round to 0.05').

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

roundingrounding
mandatory
NUMBER
MIN:0.0

The rounding amount (e.g. 0.05 to round to five cents).

modemode
TEXT

The rounding mode. Defaults to HALF_UP. Possible values: UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN, UNNECESSARY.

Endpoint

POST /api/v1/rounding/create.json

Update rounding

Updates an existing rounding. Returns either a success or multiple error messages (for each issue).

Parameters

accountIdaccountId
mandatory
NUMBER

The ID of the account onto which the rounding amount is booked.

idid
mandatory
NUMBER

The ID of the rounding to update.

namename
mandatory
TEXT
MAX:100

A name to describe the rounding method (e.g. 'Round to 0.05').

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

roundingrounding
mandatory
NUMBER
MIN:0.0

The rounding amount (e.g. 0.05 to round to five cents).

modemode
TEXT

The rounding mode. Defaults to HALF_UP. Possible values: UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN, UNNECESSARY.

Endpoint

POST /api/v1/rounding/update.json

Delete roundings

Deletes one or multiple roundings. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/rounding/delete.json

Sequence number

The following API endpoints are for managing sequence numbers. Sequence numbers are used for generating new numbers for journal entries (reference / receipt no.), inventory articles (article no.), orders (invoice no., etc.) and people (customer/vendor no.).

Read sequence number

Returns a single sequence number by ID or type and optionally category.

Parameters

idid
mandatory
NUMBER

The ID of the sequence number. Either id or type must be set.

typetype
mandatory
TEXT

The type of the sequence number, meaning: which module the sequence number belongs to. Either id or type must be set. Possible values: INVENTORY_STOCK, INVENTORY_SERVICE, INVENTORY_ASSET, JOURNAL, ORDER, PERSON, SALES_INVOICE.

categoryIdcategoryId
NUMBER

Optional ID of the category where a sequence number is defined. This only works together with the type parameter. For example if the type is PERSON and the categoryId the ID of a person category, you'll retrieve the sequence number defined in that category (if defined).

Endpoint

GET /api/v1/sequencenumber/read.json

Get generated number

Returns the next generated number for the given ID or type and optionally category.

Parameters

idid
mandatory
NUMBER

The ID of the sequence number. Either id or type must be set.

typetype
mandatory
TEXT

The type of the sequence number, meaning: which module the sequence number belongs to. Either id or type must be set. Possible values: INVENTORY_STOCK, INVENTORY_SERVICE, INVENTORY_ASSET, JOURNAL, ORDER, PERSON, SALES_INVOICE.

categoryIdcategoryId
NUMBER

Optional ID of the category where a sequence number is defined. This only works together with the type parameter. For example if the type is PERSON and the categoryId the ID of a person category, you'll retrieve the sequence number defined in that category (if defined).

Endpoint

GET /api/v1/sequencenumber/get

List sequence numbers

Returns a list of all sequence numbers.

Endpoint

GET /api/v1/sequencenumber/list.json

Create sequence number

Creates a new sequence number. Note that you cannot assign the sequence number to a type (e.g. Journal) here, this is done in the Settings or in the corresponding category (e.g. Order category). Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:100

A name to describe and identify the sequence number.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

patternpattern
mandatory
TEXT
MAX:50

The sequence number pattern, which consists of variables and arbitrary text from which a sequence number will be generated. Possible variables: $y = Current year. $m = Current month. $d = Current day. $ny = Sequence number, resets annually (on Jan 1st). $nm = Sequence number, resets monthly. $nd = Sequence number, resets daily. $nn = Sequence number, never resets. Example pattern: RE-$y$m$d$nd which may generate 'RE-2007151' (on July 15, 2020).

currentDailyNumbercurrentDailyNumber
NUMBER

The current value of the daily number (variable $nd). Defaults to 1.

currentInfiniteNumbercurrentInfiniteNumber
NUMBER

The current value of the infinite number (variable $nn). Defaults to 1.

currentMonthlyNumbercurrentMonthlyNumber
NUMBER

The current value of the monthly number (variable $nm). Defaults to 1.

currentYearlyNumbercurrentYearlyNumber
NUMBER

The current value of the yearly number (variable $ny). Defaults to 1.

dailyNumberDigitsdailyNumberDigits
NUMBER

The number of digits for the daily number (variable $nd). If the number of digits are lower than this, the number will be prepended by zeroes (e.g. 0001 if 4 digits). Defaults to 1.

dayDigitsdayDigits
NUMBER

The number of digits for the current day (variable $d). Defaults to 2.

infiniteNumberDigitsinfiniteNumberDigits
NUMBER

The number of digits for the infinite number (variable $nn). If the number of digits are lower than this, the number will be prepended by zeroes (e.g. 0001 if 4 digits). Defaults to 1.

monthDigitsmonthDigits
NUMBER

The number of digits for the current month (variable $m). Defaults to 2.

monthlyNumberDigitsmonthlyNumberDigits
NUMBER

The number of digits for the monthly number (variable $nm). If the number of digits are lower than this, the number will be prepended by zeroes (e.g. 0001 if 4 digits). Defaults to 1.

yearDigitsyearDigits
NUMBER

The number of digits for the current year (variable $y). Defaults to 4.

yearlyNumberDigitsyearlyNumberDigits
NUMBER

The number of digits for the yearly number (variable $ny). If the number of digits are lower than this, the number will be prepended by zeroes (e.g. 0001 if 4 digits). Defaults to 1.

Endpoint

POST /api/v1/sequencenumber/create.json

Update sequence number

Updates an existing sequence number. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the sequence number to update.

namename
mandatory
TEXT
MAX:100

A name to describe and identify the sequence number.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

patternpattern
mandatory
TEXT
MAX:50

The sequence number pattern, which consists of variables and arbitrary text from which a sequence number will be generated. Possible variables: $y = Current year. $m = Current month. $d = Current day. $ny = Sequence number, resets annually (on Jan 1st). $nm = Sequence number, resets monthly. $nd = Sequence number, resets daily. $nn = Sequence number, never resets. Example pattern: RE-$y$m$d$nd which may generate 'RE-2007151' (on July 15, 2020).

currentDailyNumbercurrentDailyNumber
NUMBER

The current value of the daily number (variable $nd). Defaults to 1.

currentInfiniteNumbercurrentInfiniteNumber
NUMBER

The current value of the infinite number (variable $nn). Defaults to 1.

currentMonthlyNumbercurrentMonthlyNumber
NUMBER

The current value of the monthly number (variable $nm). Defaults to 1.

currentYearlyNumbercurrentYearlyNumber
NUMBER

The current value of the yearly number (variable $ny). Defaults to 1.

dailyNumberDigitsdailyNumberDigits
NUMBER

The number of digits for the daily number (variable $nd). If the number of digits are lower than this, the number will be prepended by zeroes (e.g. 0001 if 4 digits). Defaults to 1.

dayDigitsdayDigits
NUMBER

The number of digits for the current day (variable $d). Defaults to 2.

infiniteNumberDigitsinfiniteNumberDigits
NUMBER

The number of digits for the infinite number (variable $nn). If the number of digits are lower than this, the number will be prepended by zeroes (e.g. 0001 if 4 digits). Defaults to 1.

monthDigitsmonthDigits
NUMBER

The number of digits for the current month (variable $m). Defaults to 2.

monthlyNumberDigitsmonthlyNumberDigits
NUMBER

The number of digits for the monthly number (variable $nm). If the number of digits are lower than this, the number will be prepended by zeroes (e.g. 0001 if 4 digits). Defaults to 1.

yearDigitsyearDigits
NUMBER

The number of digits for the current year (variable $y). Defaults to 4.

yearlyNumberDigitsyearlyNumberDigits
NUMBER

The number of digits for the yearly number (variable $ny). If the number of digits are lower than this, the number will be prepended by zeroes (e.g. 0001 if 4 digits). Defaults to 1.

Endpoint

POST /api/v1/sequencenumber/update.json

Delete sequence number

Deletes one or multiple sequence numbers. Only unused sequence numbers can be deleted. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/sequencenumber/delete.json

Tax rate

The following API endpoints are for managing tax rates. Tax rates are used e.g. in order items or in journal entries directly. They can also be pre-configured in accounts so they will be automatically used with the corresponding account.

Read tax rate

Returns a single tax rate by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/tax/read.json

List tax rates

Returns a list of all tax rates.

Endpoint

GET /api/v1/tax/list.json

Create tax rate

Creates a new tax rate. Returns either a success or multiple error messages (for each issue).

Parameters

accountIdaccountId
mandatory
NUMBER

The ID of the account which collects the taxes.

namename
mandatory
TEXT
MAX:250

A name to describe and identify the tax rate.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

percentagepercentage
mandatory
NUMBER
MIN:0.0
MAX:100.0

The tax rate percentage. This cannot be changed anymore if the tax rate has been used already.

calcTypecalcType
TEXT

The calculation basis of the tax rate. NET means the tax rate is based on the net revenue and GROSS means the tax rate is based on the gross revenue. Note that this only applies to the regular tax rate percentage, not the flat tax rate percentage (where always GROSS is used). Defaults to NET. Possible values: NET, GROSS.

documentNamedocumentName
TEXT

The name for the tax rate displayed on documents (seen by customers). Leave empty to use the name instead.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

isInactiveisInactive
BOOLEAN

Mark the tax rate as inactive. This means that the tax rate is greyed out and no longer suggested. Tax rates already in use cannot be deleted, but you can always set them as inactive. Defaults to false. Possible values: true, false.

percentageFlatpercentageFlat
NUMBER
MIN:0.0
MAX:100.0

The flat tax rate percentage (Saldo-/Pauschalsteuersatz). This cannot be changed anymore if the tax rate has been used already. Note that for the flat tax, the calculation basis is always GROSS (see calcType).

Endpoint

POST /api/v1/tax/create.json

Update tax rate

Updates an existing tax rate. If a tax rate is already being used, only some fields can be changed, but e.g. not the actual tax rate. Returns either a success or multiple error messages (for each issue).

Parameters

accountIdaccountId
mandatory
NUMBER

The ID of the account which collects the taxes.

idid
mandatory
NUMBER

The ID of the tax rate to update.

namename
mandatory
TEXT
MAX:250

A name to describe and identify the tax rate.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

percentagepercentage
mandatory
NUMBER
MIN:0.0
MAX:100.0

The tax rate percentage. This cannot be changed anymore if the tax rate has been used already.

calcTypecalcType
TEXT

The calculation basis of the tax rate. NET means the tax rate is based on the net revenue and GROSS means the tax rate is based on the gross revenue. Note that this only applies to the regular tax rate percentage, not the flat tax rate percentage (where always GROSS is used). Defaults to NET. Possible values: NET, GROSS.

documentNamedocumentName
TEXT

The name for the tax rate displayed on documents (seen by customers). Leave empty to use the name instead.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

isInactiveisInactive
BOOLEAN

Mark the tax rate as inactive. This means that the tax rate is greyed out and no longer suggested. Tax rates already in use cannot be deleted, but you can always set them as inactive. Defaults to false. Possible values: true, false.

percentageFlatpercentageFlat
NUMBER
MIN:0.0
MAX:100.0

The flat tax rate percentage (Saldo-/Pauschalsteuersatz). This cannot be changed anymore if the tax rate has been used already. Note that for the flat tax, the calculation basis is always GROSS (see calcType).

Endpoint

POST /api/v1/tax/update.json

Delete tax rate

Deletes one or multiple tax rates. Note that you cannot delete tax rates that are being used. Instead use Update tax rate to deactivate the tax rate. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/tax/delete.json

Text template

The following API endpoints are for managing text templates. These are used e.g. for the text on the order document (text above / below the items table on the PDF).

Read text template

Returns a single text template by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/text/read.json

List text templates

Returns a list of text templates by type.

Parameters

typetype
mandatory
TEXT

The type of text template, meaning: Where the text template can be used. Possible values: ORDER_HEADER, ORDER_FOOTER, ORDER_MAIL.

Endpoint

GET /api/v1/text/list.json

Create text template

Creates a new text template. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:200

A name to describe and identify the text template.

typetype
mandatory
TEXT

The type of text template, meaning: Where the text template can be used. Possible values: ORDER_HEADER, ORDER_FOOTER, ORDER_MAIL.

isDefaultisDefault
BOOLEAN

Sets the text template as the default text template. Note that text templates defined in order categories are preferred over the default text template, see Order category. Defaults to false. Possible values: true, false.

valuevalue
TEXT

The actual text template.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

Endpoint

POST /api/v1/text/create.json

Update text template

Updates an existing text template. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the text template to update.

namename
mandatory
TEXT
MAX:200

A name to describe and identify the text template.

typetype
mandatory
TEXT

The type of text template, meaning: Where the text template can be used. Possible values: ORDER_HEADER, ORDER_FOOTER, ORDER_MAIL.

isDefaultisDefault
BOOLEAN

Sets the text template as the default text template. Note that text templates defined in order categories are preferred over the default text template, see Order category. Defaults to false. Possible values: true, false.

valuevalue
TEXT

The actual text template.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

Endpoint

POST /api/v1/text/update.json

Delete text template

Deletes one or multiple text templates. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/text/delete.json

Article

The following API endpoints are for managing articles. These are physical products that can have a stock.

Read article

Returns a single article by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/inventory/stock/read.json

List articles

Returns a list of articles.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active stock articles. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyRestockonlyRestock
BOOLEAN

Flag to include only stock articles that need to be restocked. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only stock articles without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'nr'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/stock/list.json

Export to Excel

Returns an Excel file of the entries list.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active stock articles. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyRestockonlyRestock
BOOLEAN

Flag to include only stock articles that need to be restocked. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only stock articles without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'nr'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/stock/list.xlsx

Export to CSV

Returns a CSV file of the entries list.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active stock articles. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyRestockonlyRestock
BOOLEAN

Flag to include only stock articles that need to be restocked. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only stock articles without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'nr'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/stock/list.csv

Export to PDF

Returns a PDF file of the entries list.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active stock articles. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyRestockonlyRestock
BOOLEAN

Flag to include only stock articles that need to be restocked. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only stock articles without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'nr'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/stock/list.pdf

Create article

Creates a new article. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:250

The name of the article.

binLocationbinLocation
TEXT

The place within the building (e.g. A15, B04, C11, etc.) to locate the article. See locationId.

categoryIdcategoryId
NUMBER

The ID of the category. See Article category.

currencyIdcurrencyId
NUMBER

The ID of the currency. Leave empty to use the default currency. See Currency.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

descriptiondescription
TEXT

A description of the article.

isInactiveisInactive
BOOLEAN

Mark the article as inactive. The article will be greyed out. Defaults to false. Possible values: true, false.

isPurchasePriceGrossisPurchasePriceGross
BOOLEAN

The purchase price is net (excluding tax) by default. This defines the purchase price as gross (including tax). Defaults to false. Possible values: true, false.

isSalesPriceGrossisSalesPriceGross
BOOLEAN

The sales price is net (excluding tax) by default. This defines the sales price as gross (including tax). Defaults to false. Possible values: true, false.

isStockArticleisStockArticle
BOOLEAN

Whether the article has a stock, i.e. the stock should be tracked and updated via sales and purchase orders. Defaults to false. Possible values: true, false.

lastPurchasePricelastPurchasePrice
NUMBER

The last purchase price of the article. Net (excluding tax) by default, see isPurchasePriceGross. This price is automatically updated by purchase orders.

locationIdlocationId
NUMBER

The ID of the location where the article can be found (e.g. a warehouse). See Location. Note that this represents the building whereas the binLocation parameter represents the place within the building.

maxStockmaxStock
NUMBER

The desired maximum stock of the article. isStockArticle must be true, ignored otherwise.

minStockminStock
NUMBER

The desired minimum stock of the article. isStockArticle must be true, ignored otherwise.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

nrnr
TEXT
MAX:50

The article number. Leave empty to generate the number with sequenceNumberId.

salesPricesalesPrice
NUMBER

The sales price of the article. Net (excluding tax) by default, see isSalesPriceGross.

sequenceNumberIdsequenceNumberId
NUMBER

The ID of the sequence number used to generate the article number (see nr). If this is empty, the sequence number will not update when nr is set. See Sequence number.

stockstock
NUMBER

The current stock of the article. isStockArticle must be true, ignored otherwise.

Endpoint

POST /api/v1/inventory/stock/create.json

Update article

Updates an existing article. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the article to update.

namename
mandatory
TEXT
MAX:250

The name of the article.

binLocationbinLocation
TEXT

The place within the building (e.g. A15, B04, C11, etc.) to locate the article. See locationId.

categoryIdcategoryId
NUMBER

The ID of the category. See Article category.

currencyIdcurrencyId
NUMBER

The ID of the currency. Leave empty to use the default currency. See Currency.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

descriptiondescription
TEXT

A description of the article.

isInactiveisInactive
BOOLEAN

Mark the article as inactive. The article will be greyed out. Defaults to false. Possible values: true, false.

isPurchasePriceGrossisPurchasePriceGross
BOOLEAN

The purchase price is net (excluding tax) by default. This defines the purchase price as gross (including tax). Defaults to false. Possible values: true, false.

isSalesPriceGrossisSalesPriceGross
BOOLEAN

The sales price is net (excluding tax) by default. This defines the sales price as gross (including tax). Defaults to false. Possible values: true, false.

isStockArticleisStockArticle
BOOLEAN

Whether the article has a stock, i.e. the stock should be tracked and updated via sales and purchase orders. Defaults to false. Possible values: true, false.

lastPurchasePricelastPurchasePrice
NUMBER

The last purchase price of the article. Net (excluding tax) by default, see isPurchasePriceGross. This price is automatically updated by purchase orders.

locationIdlocationId
NUMBER

The ID of the location where the article can be found (e.g. a warehouse). See Location. Note that this represents the building whereas the binLocation parameter represents the place within the building.

maxStockmaxStock
NUMBER

The desired maximum stock of the article. isStockArticle must be true, ignored otherwise.

minStockminStock
NUMBER

The desired minimum stock of the article. isStockArticle must be true, ignored otherwise.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

nrnr
TEXT
MAX:50

The article number. Leave empty to generate the number with sequenceNumberId.

salesPricesalesPrice
NUMBER

The sales price of the article. Net (excluding tax) by default, see isSalesPriceGross.

sequenceNumberIdsequenceNumberId
NUMBER

The ID of the sequence number used to generate the article number (see nr). If this is empty, the sequence number will not update when nr is set. See Sequence number.

stockstock
NUMBER

The current stock of the article. isStockArticle must be true, ignored otherwise.

Endpoint

POST /api/v1/inventory/stock/update.json

Delete articles

Deletes one or multiple articles. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/inventory/stock/delete.json

Categorize articles

Assigns one or multiple articles to the desired category. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the entries to categorize, comma-separated.

targettarget
mandatory
NUMBER

The ID of the target category.

Endpoint

POST /api/v1/inventory/stock/categorize.json

Article category

The following API endpoints are for managing article categories.

Read category

Returns a single category by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/inventory/stock/category/read.json

Get tree of categories

Returns a tree of all categories or the tree below a parent category.

Parameters

idid
NUMBER

Optional ID of the parent category (omit to get all categories).

Endpoint

GET /api/v1/inventory/stock/category/tree.json

Create category

Creates a new category. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:100

The name of the category.

parentIdparentId
NUMBER

The ID of the parent category.

purchaseAccountIdpurchaseAccountId
NUMBER

The ID of the purchase account, which will be used when purchasing articles in this category through Orders.

salesAccountIdsalesAccountId
NUMBER

The ID of the sales account, which will be used when selling aticles in this category through Orders.

sequenceNrIdsequenceNrId
NUMBER

The ID of the sequence number used for services in this category. If empty, the sequence number of the parent category is inherited.

Endpoint

POST /api/v1/inventory/stock/category/create.json

Update category

Updates an existing category. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the category to update.

namename
mandatory
TEXT
MAX:100

The name of the category.

parentIdparentId
NUMBER

The ID of the parent category.

purchaseAccountIdpurchaseAccountId
NUMBER

The ID of the purchase account, which will be used when purchasing articles in this category through Orders.

salesAccountIdsalesAccountId
NUMBER

The ID of the sales account, which will be used when selling aticles in this category through Orders.

sequenceNrIdsequenceNrId
NUMBER

The ID of the sequence number used for services in this category. If empty, the sequence number of the parent category is inherited.

Endpoint

POST /api/v1/inventory/stock/category/update.json

Delete categories

Deletes one or multiple existing category. Note that you can only delete empty categories. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/inventory/stock/category/delete.json

Fixed asset

The following API endpoints are for managing fixed assets.

Read fixed asset

Returns a single fixed asset by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/inventory/asset/read.json

List fixed assets

Returns a list of fixed assets. Please first switch to the appropriate fiscal period to see the entries for that period only, see Switch fiscal period.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the current values. Leave empty to use the current fiscal period. See Switch fiscal period.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active fixed assets. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only fixed assets without a category. Defaults to false. Possible values: true, false.

onlyWithoutDeprTypeonlyWithoutDeprType
BOOLEAN

Flag to include only fixed assets without depreciation configured. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'dateAdded'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/asset/list.json

Export to Excel

Returns an Excel file of the entries list. Please first switch to the appropriate fiscal period to see the entries for that period only, see Switch fiscal period.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the current values. Leave empty to use the current fiscal period. See Switch fiscal period.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active fixed assets. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only fixed assets without a category. Defaults to false. Possible values: true, false.

onlyWithoutDeprTypeonlyWithoutDeprType
BOOLEAN

Flag to include only fixed assets without depreciation configured. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'dateAdded'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/asset/list.xlsx

Export to CSV

Returns a CSV file of the entries list. Please first switch to the appropriate fiscal period to see the entries for that period only, see Switch fiscal period.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the current values. Leave empty to use the current fiscal period. See Switch fiscal period.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active fixed assets. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only fixed assets without a category. Defaults to false. Possible values: true, false.

onlyWithoutDeprTypeonlyWithoutDeprType
BOOLEAN

Flag to include only fixed assets without depreciation configured. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'dateAdded'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/asset/list.csv

Export to PDF

Returns a PDF file of the entries list. Please first switch to the appropriate fiscal period to see the entries for that period only, see Switch fiscal period.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the current values. Leave empty to use the current fiscal period. See Switch fiscal period.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active fixed assets. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only fixed assets without a category. Defaults to false. Possible values: true, false.

onlyWithoutDeprTypeonlyWithoutDeprType
BOOLEAN

Flag to include only fixed assets without depreciation configured. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'dateAdded'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/asset/list.pdf

Create fixed asset

Creates a new fixed asset. Returns either a success or multiple error messages (for each issue).

Parameters

accountIdaccountId
mandatory
NUMBER

The ID of the account onto which the fixed asset is booked (e.g. Mobile assets). See Account.

dateAddeddateAdded
mandatory
DATE

The date when the fixed asset has been added.

Format: YYYY-MM-DD. Example: 2020-01-15.

namename
mandatory
TEXT
MAX:250

The name of the fixed asset.

purchasePricepurchasePrice
mandatory
NUMBER

The initial purchase price of the fixed asset.

categoryIdcategoryId
NUMBER

The ID of the category. See Fixed asset category.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

dateDisposeddateDisposed
DATE

The date of the disposal. Must be set if disposalType is set.

Format: YYYY-MM-DD. Example: 2020-01-15.

deprAccountIddeprAccountId
NUMBER

The ID of the depreciation account (an expense account for depreciations). Must be set if deprType is set. See Account.

deprDurationdeprDuration
NUMBER

The duration of the depreciation in years. Must be set if deprType is set.

deprSalvageValuedeprSalvageValue
NUMBER

The salvage value after depreciation is finished. This is the book value the fixed asset will retain afterwards. Defaults to 0.

deprTypedeprType
TEXT

The type of depreciation. Defaults to NONE (no deprecation). Possible values: NONE, LINEAR, DEGRESSIVE.

descriptiondescription
TEXT

A description of the fixed asset.

disposalDebitIddisposalDebitId
NUMBER

The ID of the account for the disposal (an expense account for disposals, similar to depreciation). Must be set if disposalType is set. See Account.

disposalTypedisposalType
TEXT

The type of disposal. Defaults to NONE. Possible values: NONE, DIRECT, SALE_DIRECT.

initialValueinitialValue
NUMBER

The initial value of the fixed asset. If purchaseType is DIRECT, then this parameter will be ignored and the purchasePrice is used as initial value. This parameter is only used if the purchaseType is HISTORIC.

locationIdlocationId
NUMBER

The ID of the location where the fixed asset can be found (e.g. a warehouse). See Location.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

nrnr
TEXT
MAX:50

The article number. Leave empty to generate the number with sequenceNumberId.

purchaseCreditIdpurchaseCreditId
NUMBER

The ID of the account for the fixed asset purchase (e.g. Bank account). See Account.

purchaseTaxIdpurchaseTaxId
NUMBER

The ID of the tax rate for the purchase of the fixed asset. See Tax rates.

purchaseTypepurchaseType
TEXT

The type of purchase. Defaults to DIRECT. Possible values: DIRECT, HISTORICAL.

saleAmountsaleAmount
NUMBER

The sale amount of the fixed asset, if the fixed asset has been sold. Must be set if disposalType is SALE_DIRECT.

saleCreditIdsaleCreditId
NUMBER

The ID of the credit account for the sale of the fixed asset. Must be set if disposalType is SALE_DIRECT. See Account.

saleDebitIdsaleDebitId
NUMBER

The ID of the debit account for the sale of the fixed asset. Must be set if disposalType is SALE_DIRECT. See Account.

saleTaxIdsaleTaxId
NUMBER

The ID of the tax rate for the sale of the fixed asset. Can be set if disposalType is SALE_DIRECT. See Tax rates.

sequenceNumberIdsequenceNumberId
NUMBER

The ID of the sequence number used to generate the article number (see nr). If this is empty, the sequence number will not update when nr is set. See Sequence number.

Endpoint

POST /api/v1/inventory/asset/create.json

Update fixed asset

Updates an existing fixed asset. Returns either a success or multiple error messages (for each issue).

Parameters

accountIdaccountId
mandatory
NUMBER

The ID of the account onto which the fixed asset is booked (e.g. Mobile assets). See Account.

dateAddeddateAdded
mandatory
DATE

The date when the fixed asset has been added.

Format: YYYY-MM-DD. Example: 2020-01-15.

idid
mandatory
NUMBER

The ID of the fixed asset to update.

namename
mandatory
TEXT
MAX:250

The name of the fixed asset.

purchasePricepurchasePrice
mandatory
NUMBER

The initial purchase price of the fixed asset.

categoryIdcategoryId
NUMBER

The ID of the category. See Fixed asset category.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

dateDisposeddateDisposed
DATE

The date of the disposal. Must be set if disposalType is set.

Format: YYYY-MM-DD. Example: 2020-01-15.

deprAccountIddeprAccountId
NUMBER

The ID of the depreciation account (an expense account for depreciations). Must be set if deprType is set. See Account.

deprDurationdeprDuration
NUMBER

The duration of the depreciation in years. Must be set if deprType is set.

deprSalvageValuedeprSalvageValue
NUMBER

The salvage value after depreciation is finished. This is the book value the fixed asset will retain afterwards. Defaults to 0.

deprTypedeprType
TEXT

The type of depreciation. Defaults to NONE (no deprecation). Possible values: NONE, LINEAR, DEGRESSIVE.

descriptiondescription
TEXT

A description of the fixed asset.

disposalDebitIddisposalDebitId
NUMBER

The ID of the account for the disposal (an expense account for disposals, similar to depreciation). Must be set if disposalType is set. See Account.

disposalTypedisposalType
TEXT

The type of disposal. Defaults to NONE. Possible values: NONE, DIRECT, SALE_DIRECT.

initialValueinitialValue
NUMBER

The initial value of the fixed asset. If purchaseType is DIRECT, then this parameter will be ignored and the purchasePrice is used as initial value. This parameter is only used if the purchaseType is HISTORIC.

locationIdlocationId
NUMBER

The ID of the location where the fixed asset can be found (e.g. a warehouse). See Location.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

nrnr
TEXT
MAX:50

The article number. Leave empty to generate the number with sequenceNumberId.

purchaseCreditIdpurchaseCreditId
NUMBER

The ID of the account for the fixed asset purchase (e.g. Bank account). See Account.

purchaseTaxIdpurchaseTaxId
NUMBER

The ID of the tax rate for the purchase of the fixed asset. See Tax rates.

purchaseTypepurchaseType
TEXT

The type of purchase. Defaults to DIRECT. Possible values: DIRECT, HISTORICAL.

saleAmountsaleAmount
NUMBER

The sale amount of the fixed asset, if the fixed asset has been sold. Must be set if disposalType is SALE_DIRECT.

saleCreditIdsaleCreditId
NUMBER

The ID of the credit account for the sale of the fixed asset. Must be set if disposalType is SALE_DIRECT. See Account.

saleDebitIdsaleDebitId
NUMBER

The ID of the debit account for the sale of the fixed asset. Must be set if disposalType is SALE_DIRECT. See Account.

saleTaxIdsaleTaxId
NUMBER

The ID of the tax rate for the sale of the fixed asset. Can be set if disposalType is SALE_DIRECT. See Tax rates.

sequenceNumberIdsequenceNumberId
NUMBER

The ID of the sequence number used to generate the article number (see nr). If this is empty, the sequence number will not update when nr is set. See Sequence number.

Endpoint

POST /api/v1/inventory/asset/update.json

Delete fixed assets

Deletes one or multiple fixed assets. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/inventory/asset/delete.json

Categorize fixed assets

Assigns one or multiple fixed assets to the desired category. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the entries to categorize, comma-separated.

targettarget
mandatory
NUMBER

The ID of the target category.

Endpoint

POST /api/v1/inventory/asset/categorize.json

Fixed asset category

The following API endpoints are for managing fixed asset categories.

Read category

Returns a single category by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/inventory/asset/category/read.json

Get tree of categories

Returns a tree of all categories or the tree below a parent category.

Parameters

idid
NUMBER

Optional ID of the parent category (omit to get all categories).

Endpoint

GET /api/v1/inventory/asset/category/tree.json

Create category

Creates a new category. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:100

The name of the category.

parentIdparentId
NUMBER

The ID of the parent category.

Endpoint

POST /api/v1/inventory/asset/category/create.json

Update category

Updates an existing category. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the category to update.

namename
mandatory
TEXT
MAX:100

The name of the category.

parentIdparentId
NUMBER

The ID of the parent category.

Endpoint

POST /api/v1/inventory/asset/category/update.json

Delete categories

Deletes one or multiple existing category. Note that you can only delete empty categories. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/inventory/asset/category/delete.json

Service

The following API endpoints are for managing services. Here, service refers to a non-physical article, i.e. a service that your company provides to customers, as opposed to a Stock article.

Read service

Returns a single service by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/inventory/service/read.json

List services

Returns a list of services.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active services. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only services without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'nr'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/service/list.json

Export to Excel

Returns an Excel file of the entries list.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active services. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only services without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'nr'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/service/list.xlsx

Export to CSV

Returns a CSV file of the entries list.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active services. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only services without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'nr'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/service/list.csv

Export to PDF

Returns a PDF file of the entries list.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active services. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only services without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'nr'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/service/list.pdf

Create service

Creates a new service. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:250

The name of the service.

categoryIdcategoryId
NUMBER

The ID of the category. See Service category.

currencyIdcurrencyId
NUMBER

The ID of the currency. Leave empty to use the default currency. See Currency.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

descriptiondescription
TEXT

A description of the service.

isInactiveisInactive
BOOLEAN

Mark the service as inactive. The service will be greyed out. Defaults to false. Possible values: true, false.

isSalesPriceGrossisSalesPriceGross
BOOLEAN

The sales price is net (excluding tax) by default. This defines the sales price as gross (including tax). Defaults to false. Possible values: true, false.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

nrnr
TEXT
MAX:50

The article number. Leave empty to generate the number with sequenceNumberId.

salesPricesalesPrice
NUMBER

The sales price of the service. Net (excluding tax) by default, see isSalesPriceGross.

sequenceNumberIdsequenceNumberId
NUMBER

The ID of the sequence number used to generate the article number (see nr). If this is empty, the sequence number will not update when nr is set. See Sequence number.

unitIdunitId
TEXT

The ID of the unit (like hours, minutes, etc.). See Units.

Endpoint

POST /api/v1/inventory/service/create.json

Update service

Updates an existing service. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the service to update.

namename
mandatory
TEXT
MAX:250

The name of the service.

categoryIdcategoryId
NUMBER

The ID of the category. See Service category.

currencyIdcurrencyId
NUMBER

The ID of the currency. Leave empty to use the default currency. See Currency.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

descriptiondescription
TEXT

A description of the service.

isInactiveisInactive
BOOLEAN

Mark the service as inactive. The service will be greyed out. Defaults to false. Possible values: true, false.

isSalesPriceGrossisSalesPriceGross
BOOLEAN

The sales price is net (excluding tax) by default. This defines the sales price as gross (including tax). Defaults to false. Possible values: true, false.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

nrnr
TEXT
MAX:50

The article number. Leave empty to generate the number with sequenceNumberId.

salesPricesalesPrice
NUMBER

The sales price of the service. Net (excluding tax) by default, see isSalesPriceGross.

sequenceNumberIdsequenceNumberId
NUMBER

The ID of the sequence number used to generate the article number (see nr). If this is empty, the sequence number will not update when nr is set. See Sequence number.

unitIdunitId
TEXT

The ID of the unit (like hours, minutes, etc.). See Units.

Endpoint

POST /api/v1/inventory/service/update.json

Delete services

Deletes one or multiple service. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/inventory/service/delete.json

Categorize services

Assigns one or multiple services to the desired category. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the entries to categorize, comma-separated.

targettarget
mandatory
NUMBER

The ID of the target category.

Endpoint

POST /api/v1/inventory/service/categorize.json

Service category

The following API endpoints are for managing service categories.

Read category

Returns a single category by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/inventory/service/category/read.json

Get tree of categories

Returns a tree of all categories or the tree below a parent category.

Parameters

idid
NUMBER

Optional ID of the parent category (omit to get all categories).

Endpoint

GET /api/v1/inventory/service/category/tree.json

Create category

Creates a new category. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:100

The name of the category.

parentIdparentId
NUMBER

The ID of the parent category.

purchaseAccountIdpurchaseAccountId
NUMBER

The ID of the purchase account, which will be used when purchasing services in this category through Orders.

salesAccountIdsalesAccountId
NUMBER

The ID of the sales account, which will be used when selling services in this category through Orders.

sequenceNrIdsequenceNrId
NUMBER

The ID of the sequence number used for services in this category. If empty, the sequence number of the parent category is inherited.

Endpoint

POST /api/v1/inventory/service/category/create.json

Update category

Updates an existing category. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the category to update.

namename
mandatory
TEXT
MAX:100

The name of the category.

parentIdparentId
NUMBER

The ID of the parent category.

purchaseAccountIdpurchaseAccountId
NUMBER

The ID of the purchase account, which will be used when purchasing services in this category through Orders.

salesAccountIdsalesAccountId
NUMBER

The ID of the sales account, which will be used when selling services in this category through Orders.

sequenceNrIdsequenceNrId
NUMBER

The ID of the sequence number used for services in this category. If empty, the sequence number of the parent category is inherited.

Endpoint

POST /api/v1/inventory/service/category/update.json

Delete categories

Deletes one or multiple existing category. Note that you can only delete empty categories. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/inventory/service/category/delete.json

Unit

The following API endpoints are for managing units. A unit can be pcs., years, hours, meters, etc. The default unit is pcs.

Read unit

Returns a single unit by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/inventory/unit/read.json

List units

Returns a list of all units.

Endpoint

GET /api/v1/inventory/unit/list.json

Create unit

Creates a new unit. Returns either a success or multiple error messages (for each issue).

Parameters

namename
TEXT
MAX:100

The name of the unit ('hours', 'minutes', etc.).

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

Endpoint

POST /api/v1/inventory/unit/create.json

Update unit

Updates an existing unit. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the unit to update.

namename
TEXT
MAX:100

The name of the unit ('hours', 'minutes', etc.).

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

Endpoint

POST /api/v1/inventory/unit/update.json

Delete units

Deletes one or multiple units. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/inventory/unit/delete.json

Journal

The following API endpoints are for managing journal entries. Any kind of entry can be read but only manual book entries can be manipulated. Automatic book entries happen for example through orders, depreciations or currency exchange rate corrections. They cannot be manipulated here but in the respective API (e.g. Orders).

Read journal entry

Returns a single journal entry by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/journal/read.json

List journal entries

Returns a list of journal entries.

Parameters

accountIdaccountId
NUMBER

Optional ID of account to retrieve the journal for that specific account.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the entries. Leave empty to use the current fiscal period. See Switch fiscal period.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyCollectiveonlyCollective
BOOLEAN

Flag to only include collective book entries. Defaults to false. Possible values: true, false.

onlyImportedonlyImported
BOOLEAN

Flag to only include imported book entries. Defaults to false. Possible values: true, false.

onlyManualonlyManual
BOOLEAN

Flag to only include manual book entries. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'dateAdded'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/journal/list.json

Export to Excel

Returns an Excel file of the entries list.

Parameters

accountIdaccountId
NUMBER

Optional ID of account to retrieve the journal for that specific account.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the entries. Leave empty to use the current fiscal period. See Switch fiscal period.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyCollectiveonlyCollective
BOOLEAN

Flag to only include collective book entries. Defaults to false. Possible values: true, false.

onlyImportedonlyImported
BOOLEAN

Flag to only include imported book entries. Defaults to false. Possible values: true, false.

onlyManualonlyManual
BOOLEAN

Flag to only include manual book entries. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'dateAdded'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/journal/list.xlsx

Export to CSV

Returns a CSV file of the entries list.

Parameters

accountIdaccountId
NUMBER

Optional ID of account to retrieve the journal for that specific account.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the entries. Leave empty to use the current fiscal period. See Switch fiscal period.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyCollectiveonlyCollective
BOOLEAN

Flag to only include collective book entries. Defaults to false. Possible values: true, false.

onlyImportedonlyImported
BOOLEAN

Flag to only include imported book entries. Defaults to false. Possible values: true, false.

onlyManualonlyManual
BOOLEAN

Flag to only include manual book entries. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'dateAdded'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/journal/list.csv

Export to PDF

Returns a PDF file of the entries list.

Parameters

accountIdaccountId
NUMBER

Optional ID of account to retrieve the journal for that specific account.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the entries. Leave empty to use the current fiscal period. See Switch fiscal period.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyCollectiveonlyCollective
BOOLEAN

Flag to only include collective book entries. Defaults to false. Possible values: true, false.

onlyImportedonlyImported
BOOLEAN

Flag to only include imported book entries. Defaults to false. Possible values: true, false.

onlyManualonlyManual
BOOLEAN

Flag to only include manual book entries. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'dateAdded'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/journal/list.pdf

Create journal entry

Creates a new manual journal entry. Returns either a success or multiple error messages (for each issue).

Parameters

amountamount
mandatory
NUMBER

The amount of the journal entry (e.g. 125.50). This parameter is ignored if items is set.

creditIdcreditId
mandatory
NUMBER

The ID of the account on the credit side. See Account. This parameter is ignored if items is set.

debitIddebitId
mandatory
NUMBER

The ID of the account on the debit side. See Account. This parameter is ignored if items is set.

associateIdassociateId
TEXT

The ID of the business associate (person). Instead of an ID you can also create a new person on-the-fly by entering a name here. See Person.

currencyIdcurrencyId
NUMBER

The ID of the currency. Leave empty to use the default currency. See Currency.

currencyRatecurrencyRate
NUMBER

The exchange rate from foreign currency to main currency. Only required if the currency is not supported or if you want to use a different rate than suggested.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

dateAddeddateAdded
DATE

The date of the book entry.

Format: YYYY-MM-DD. Example: 2020-01-15.

itemsitems
JSON

Items for the collective book entry (Sammelbuchung). Leave empty to create a regular book entry, and set if you want to create a collective book entry.

This is a JSON array [{...},{...},...] with the following parameters:

accountIdaccountId
mandatory
NUMBER

The ID of the account. See Account.

associateIdassociateId
TEXT

The ID of the business associate (person). Instead of an ID you can also create a new person on-the-fly by entering a name here. See Person.

creditcredit
NUMBER

The amount on the credit side. Either debit or credit must be set.

debitdebit
NUMBER

The amount on the debit side. Either debit or credit must be set.

descriptiondescription
TEXT

The description of the item.

taxIdtaxId
NUMBER

The ID of the tax rate. See Tax rates.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

referencereference
TEXT
MAX:100

An optional reference / receipt for the book entry. Can be automatically generated using sequenceNumberId.

sequenceNumberIdsequenceNumberId
NUMBER

The ID of the sequence number used to generate the reference (see reference). If this is empty, the sequence number will not update when reference is set. See Sequence number.

taxIdtaxId
NUMBER

The ID of the tax rate. See Tax rates.

titletitle
TEXT
MAX:250

The description of the book entry.

Endpoint

POST /api/v1/journal/create.json

Update journal entry

Updates an existing manual journal entry. Note that you cannot update automatically created entries this way (use the appropriate API, e.g. Orders). Returns either a success or multiple error messages (for each issue).

Parameters

amountamount
mandatory
NUMBER

The amount of the journal entry (e.g. 125.50). This parameter is ignored if items is set.

creditIdcreditId
mandatory
NUMBER

The ID of the account on the credit side. See Account. This parameter is ignored if items is set.

debitIddebitId
mandatory
NUMBER

The ID of the account on the debit side. See Account. This parameter is ignored if items is set.

idid
mandatory
NUMBER

The ID of the journal entry to update.

associateIdassociateId
TEXT

The ID of the business associate (person). Instead of an ID you can also create a new person on-the-fly by entering a name here. See Person.

currencyIdcurrencyId
NUMBER

The ID of the currency. Leave empty to use the default currency. See Currency.

currencyRatecurrencyRate
NUMBER

The exchange rate from foreign currency to main currency. Only required if the currency is not supported or if you want to use a different rate than suggested.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

dateAddeddateAdded
DATE

The date of the book entry.

Format: YYYY-MM-DD. Example: 2020-01-15.

itemsitems
JSON

Items for the collective book entry (Sammelbuchung). Leave empty to create a regular book entry, and set if you want to create a collective book entry.

This is a JSON array [{...},{...},...] with the following parameters:

accountIdaccountId
mandatory
NUMBER

The ID of the account. See Account.

associateIdassociateId
TEXT

The ID of the business associate (person). Instead of an ID you can also create a new person on-the-fly by entering a name here. See Person.

creditcredit
NUMBER

The amount on the credit side. Either debit or credit must be set.

debitdebit
NUMBER

The amount on the debit side. Either debit or credit must be set.

descriptiondescription
TEXT

The description of the item.

taxIdtaxId
NUMBER

The ID of the tax rate. See Tax rates.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

referencereference
TEXT
MAX:100

An optional reference / receipt for the book entry. Can be automatically generated using sequenceNumberId.

sequenceNumberIdsequenceNumberId
NUMBER

The ID of the sequence number used to generate the reference (see reference). If this is empty, the sequence number will not update when reference is set. See Sequence number.

taxIdtaxId
NUMBER

The ID of the tax rate. See Tax rates.

titletitle
TEXT
MAX:250

The description of the book entry.

Endpoint

POST /api/v1/journal/update.json

Delete journal entries

Deletes one or multiple manual journal entries. Note that you cannot delete automatically created entries here (use the appropriate API, e.g. Orders). Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/journal/delete.json

Import

The following API endpoints are for managing imports of journal entries via MT940 or ISO 20022 camt files. An import object contains the raw file contents, and meta data like file name, content type, etc. For the actual entries, see Journal import entry.

Read import

Returns a single import object by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/journal/import/read.json

List imports

Returns a list of imports.

Parameters

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the imports. Leave empty to use the current fiscal period. See Switch fiscal period.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'created'.

Endpoint

GET /api/v1/journal/import/list.json

Create import

Creates a new import. This will persist the entries to be imported in the database (see Journal import entry), but doesn't actually import anything into the journal, yet. The entries have to be confirmed first, and then imported via the Execute endpoint (see next endpoint). Returns either a success or multiple error messages (for each issue).

Parameters

filefile
FILE

File to import. Valid formats: camt.052, camt.053, camt.054, MT940 and any of these formats within a ZIP or TAR file.

targetAccountIdtargetAccountId
NUMBER

The ID of the target account (e.g. your bank account) to import the entries into.

Endpoint

POST /api/v1/journal/import/create.json

Execute import

Executes a import. This means that all confirmed entries are actually imported into the journal. To confirm entries, see Journal import entry. Returns either a success or error message.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

POST /api/v1/journal/import/execute.json

Import entry

The following API endpoints are for managing journal import entries. These entries have been created by a Journal import and are to be imported into the journal. They are not yet imported unless the entries have been confirmed (see Confirm import entry) and the import has been executed (see Execute journal import).

Read import entry

Returns a single import entry by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/journal/import/entry/read.json

List import entries

Returns a list of import entries.

Parameters

importIdimportId
mandatory
NUMBER

The ID of the journal import.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'dateAdded'.

Endpoint

GET /api/v1/journal/import/entry/list.json

Export to Excel

Returns an Excel file of the entries list.

Parameters

importIdimportId
mandatory
NUMBER

The ID of the journal import.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'dateAdded'.

Endpoint

GET /api/v1/journal/import/entry/list.xlsx

Export to CSV

Returns a CSV file of the entries list.

Parameters

importIdimportId
mandatory
NUMBER

The ID of the journal import.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'dateAdded'.

Endpoint

GET /api/v1/journal/import/entry/list.csv

Export to PDF

Returns a PDF file of the entries list.

Parameters

importIdimportId
mandatory
NUMBER

The ID of the journal import.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'dateAdded'.

Endpoint

GET /api/v1/journal/import/entry/list.pdf

Update import entry

Updates an import entry. Note that this automatically confirms the entry. Returns either a success or multiple error messages (for each issue).

Parameters

amountamount
mandatory
NUMBER

The amount of the journal entry (e.g. 125.50).

contraAccountIdcontraAccountId
mandatory
NUMBER

The ID of the contra account. That's the account opposite of the target account that we import into. For example if the target account is a bank account, the contra account may be an expense or revenue account. See Account.

dateAddeddateAdded
mandatory
DATE

The date of the book entry.

Format: YYYY-MM-DD. Example: 2020-01-15.

idid
mandatory
NUMBER

The ID of the import entry to update.

associateIdassociateId
TEXT

The ID of the business associate (person). See Person.

currencyIdcurrencyId
NUMBER

The ID of the currency. Leave empty to use the default currency. See Currency.

currencyRatecurrencyRate
NUMBER

The exchange rate from foreign currency to main currency. Only required if the currency is not supported or if you want to use a different rate than suggested.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

orderIdorderId
NUMBER

The ID of the order that this book entry belongs to. This is the case, for example, if this book entry is a payment for an existing order.

orderStatusIdorderStatusId
NUMBER

The ID of the order status. Only set this if orderId is set. This updates the status of the order, e.g. from 'Open' to 'Paid'. Without setting this, the status of the order won't change after importing this entry.

referencereference
TEXT
MAX:100

An optional reference / receipt for the book entry.

taxIdtaxId
NUMBER

The ID of the tax rate. See Tax rates.

titletitle
TEXT
MAX:250

The description of the book entry.

Endpoint

POST /api/v1/journal/import/entry/update.json

Ignore import entries

Ignores one or multiple import entries. This doesn't actually delete the entry but marks it as ignored, which is to say: Do not import. You can restore ignored entries, see next API endpoint. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/journal/import/entry/delete.json

Restore import entries

Restores one or multiple import entries. This restores ignored import entries. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/journal/import/entry/restore.json

Confirm import entries

Confirms one or multiple import entries. Confirmed entries are ready to be imported with Execute journal import. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/journal/import/entry/confirm.json

Unconfirm import entries

Unconfirms one or multiple import entries. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/journal/import/entry/unconfirm.json

Fiscal period

The following API endpoints are for manipulating fiscal periods. A fiscal period is simply a time period, usually a calendar year. All journal book entries (their dates) must be covered by a fiscal period and cannot be created outside of existing fiscal periods. So a fiscal period must first be created before book entries for that period can be created. Fiscal periods can be completed which locks the book entries in that period. Completed fiscal periods can be reopened anytime.

Read fiscal period

Returns a single fiscal period by ID or the current fiscal period.

Parameters

idid
TEXT

The ID of the fiscal period. Leave empty to read the current fiscal period (see Switch fiscal period).

Endpoint

GET /api/v1/fiscalperiod/read.json

List fiscal periods

Returns a list of all fiscal periods.

Endpoint

GET /api/v1/fiscalperiod/list.json

Create fiscal period

Creates a new manual fiscal period. Returns either a success or multiple error messages (for each issue).

Parameters

endend
DATE

The end date of the fiscal period, if isCustom is set to true, ignored otherwise.

Format: YYYY-MM-DD. Example: 2020-01-15.

isCustomisCustom
BOOLEAN

If true, create a custom fiscal period with start and end date. type will be ignored. Defaults to false. Possible values: true, false.

namename
TEXT
MAX:30

The name of the fiscal period, if isCustom is set to true, ignored otherwise.

startstart
DATE

The start date of the fiscal period, if isCustom is set to true, ignored otherwise.

Format: YYYY-MM-DD. Example: 2020-01-15.

typetype
TEXT

Creation type for creating a calendar year, if isCustom is not set. Either LATEST, which will create the next year after the latest existing year, or EARLIEST, which will create the year before the earliest existing year. Defaults to LATEST. Possible values: EARLIEST, LATEST.

Endpoint

POST /api/v1/fiscalperiod/create.json

Update fiscal period

Updates an existing fiscal period. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the fiscal period to update.

endend
DATE

The end date of the fiscal period, if isCustom is set to true, ignored otherwise.

Format: YYYY-MM-DD. Example: 2020-01-15.

isCustomisCustom
BOOLEAN

If true, create a custom fiscal period with start and end date. type will be ignored. Defaults to false. Possible values: true, false.

namename
TEXT
MAX:30

The name of the fiscal period, if isCustom is set to true, ignored otherwise.

startstart
DATE

The start date of the fiscal period, if isCustom is set to true, ignored otherwise.

Format: YYYY-MM-DD. Example: 2020-01-15.

typetype
TEXT

Creation type for creating a calendar year, if isCustom is not set. Either LATEST, which will create the next year after the latest existing year, or EARLIEST, which will create the year before the earliest existing year. Defaults to LATEST. Possible values: EARLIEST, LATEST.

Endpoint

POST /api/v1/fiscalperiod/update.json

Switch fiscal period

Switches the current fiscal period. Every user has a current fiscal period set, which is considered for various data responses like e.g. the list of journal entries. If you retrieve the list of journal entries, only the entries in the current fiscal period are returned. You have to use this API endpoint to switch the current fiscal period to another one.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/fiscalperiod/switch.json

Delete fiscal periods

Deletes one or multiple fiscal periods. Note that you cannot delete fiscal periods if there are book entries that are not covered by another fiscal period. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/fiscalperiod/delete.json

Get result

Get the result (profit or loss) of the given fiscal period.

Parameters

idid
NUMBER

The ID of the fiscal period. Leave empty to use the current fiscal period (see Switch fiscal period).

Endpoint

GET /api/v1/fiscalperiod/result

List depreciations

List the depreciations on fixed assets to be booked in the current fiscal period (see Switch fiscal period). This doesn't actually book anything, see the next API endpoint for that.

Endpoint

GET /api/v1/fiscalperiod/depreciations.json

Book depreciations

Book depreciations on fixed assets in the current fiscal period (see Switch fiscal period).

Parameters

depreciationdepreciation
mandatory
CSV

The IDs of fixed asset accounts to depreciate, comma-separated. See previous endpoint for a list of depreciable accounts.

Endpoint

POST /api/v1/fiscalperiod/bookdepreciations.json

List currency exchange differences

List the currency exchange differences to be booked in the current fiscal period (see Switch fiscal period). These book entries make corrections to the main currency balance of accounts with a foreign currency. This doesn't actually book anything, see the next API endpoint for that.

Endpoint

GET /api/v1/fiscalperiod/exchangediff.json

Book currency exchange differences

Book currency exchange differences in the current fiscal period (see Switch fiscal period). These book entries make corrections to the main currency balance of accounts with a foreign currency.

Parameters

exchangeDiffexchangeDiff
mandatory
JSON

The exchange differences to book.

This is a JSON array [{...},{...},...] with the following parameters:

accountIdaccountId
mandatory
NUMBER

The ID of the account in a foreign currency.

currencyRatecurrencyRate
mandatory
NUMBER

The final exchange rate to use (by which the main currency amount will be corrected).

Endpoint

POST /api/v1/fiscalperiod/bookexchangediff.json

Complete fiscal period

Completes the current fiscal period (see Switch fiscal period). This action locks the book entries in this period so they cannot be manipulated anymore. However, you can reopen the fiscal period any time, see next API endpoint.

Endpoint

POST /api/v1/fiscalperiod/complete.json

Reopen fiscal period

Reopens the current fiscal period (see Switch fiscal period). This unlocks the book entries in this period so they can be manipulated again.

Endpoint

POST /api/v1/fiscalperiod/reopen.json

Fiscal period task

The following API endpoints are for manipulating tasks, which appear in the fiscal period completion dialog.

List tasks

Returns a list of tasks.

Endpoint

GET /api/v1/fiscalperiod/task/list.json

Create task

Creates a new task. Returns either a success or error message.

Parameters

namename
mandatory
TEXT

The name/text of the task.

Endpoint

POST /api/v1/fiscalperiod/task/create.json

Delete tasks

Deletes one or multiple tasks. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/fiscalperiod/task/delete.json

Location

The following API endpoints are for managing locations. An organization can have multiple locations (e.g. headquarters, branches, warehouses) with each an address, logo, bank data, UID, etc.

Read location

Returns a single location by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/location/read.json

List locations

Returns a list of all locations.

Endpoint

GET /api/v1/location/list.json

Create location

Creates a new location. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:250

A name to describe and identify the location. Not used in an address, just for identification.

addressaddress
TEXT
MAX:250

The address (street, house number, additional info) of the location. Can contain multiple lines.

bicbic
TEXT
MAX:11

The BIC (Business Identifier Code) of your bank.

citycity
TEXT
MAX:100

The town / city of the location.

countrycountry
TEXT

The country of the location. This is a country code with 3 characters (ISO 3166-1 alpha-3). Possible values: AFG, ALA, ALB, DZA, ASM, AND, AGO, AIA, ATG, ARG, ARM, ABW, AUS, AUT, AZE, BHS, BHR, BGD, BRB, BLR, BEL, BLZ, BEN, BMU, BTN, BOL, BES, BIH, BWA, BVT, BRA, IOT, BRN, BGR, BFA, BDI, KHM, CMR, CAN, CPV, CYM, CAF, TCD, CHL, CHN, CXR, CCK, COL, COM, COG, COK, CRI, CIV, HRV, CUB, CUW, CYP, CZE, DNK, DJI, DOM, DMA, ECU, EGY, SLV, GNQ, ERI, EST, ETH, FLK, FRO, FJI, FIN, FRA, GUF, GUY, PYF, GAB, GMB, GEO, DEU, GHA, GIB, GRC, GRL, GRD, GLP, GUM, GTM, GGY, GNB, GIN, HTI, HMD, VAT, HND, HKG, HUN, IND, IDN, IRN, IRQ, IRL, IMN, ISR, ITA, JAM, JPN, JEY, JOR, KAZ, KEN, KIR, PRK, KOR, KWT, KGZ, LAO, LVA, LBN, LSO, LBR, LBY, LIE, LTU, LUX, MAC, MKD, MDG, MWI, MYS, MDV, SOM, MLI, MLT, MHL, MTQ, MRT, MUS, MYT, MEX, FSM, MDA, MCO, MNG, MNE, MSR, MAR, MOZ, MMR, NAM, NRU, NPL, NLD, NCL, NZL, NIC, NGA, NER, NIU, NFK, MNP, NOR, OMN, PAK, PLW, PSE, PAN, PNG, PRY, PER, PHL, PCN, POL, PRT, PRI, QAT, REU, ROU, RUS, RWA, BLM, SHN, KNA, LCA, MAF, SPM, VCT, WSM, SMR, STP, SAU, SEN, SRB, SYC, SLE, SGP, SXM, SVK, SVN, SLB, ZAF, SGS, SSD, ESP, LKA, SDN, SUR, SJM, SWZ, SWE, CHE, SYR, TWN, TJK, TZA, THA, TLS, TGO, TKL, TON, TTO, TUN, TUR, TKM, TCA, TUV, UGA, UKR, ARE, GBR, USA, URY, UZB, VUT, VEN, VNM, VIR, VGB, WLF, YEM, ZMB, ZWE, ISL.

footerfooter
TEXT

Footer text to display on order documents. See Order.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

ibaniban
TEXT
MAX:100

The IBAN (International Bank Account Number).

logoFilelogoFile
FILE

The company logo. Supported types: JPG, GIF, PNG. Max. size: 400KB. Max. resolution: 2500x2500px.

orgNameorgName
TEXT
MAX:250

The name of the company.

qrIbanqrIban
TEXT
MAX:100

The QR-IBAN, which is an IBAN especially for QR invoices (former ESR). This is specific to Switzerland.

typetype
TEXT

The type of location. Defaults to MAIN (= company headquarters). Possible values: MAIN, BRANCH, STORAGE, OTHER.

vatUidvatUid
TEXT
MAX:100

The UID (VAT no.) of the company.

zipzip
TEXT
MAX:10

The postal code of the location.

Endpoint

POST /api/v1/location/create.json

Update location

Updates an existing location. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the location to update.

namename
mandatory
TEXT
MAX:250

A name to describe and identify the location. Not used in an address, just for identification.

addressaddress
TEXT
MAX:250

The address (street, house number, additional info) of the location. Can contain multiple lines.

bicbic
TEXT
MAX:11

The BIC (Business Identifier Code) of your bank.

citycity
TEXT
MAX:100

The town / city of the location.

countrycountry
TEXT

The country of the location. This is a country code with 3 characters (ISO 3166-1 alpha-3). Possible values: AFG, ALA, ALB, DZA, ASM, AND, AGO, AIA, ATG, ARG, ARM, ABW, AUS, AUT, AZE, BHS, BHR, BGD, BRB, BLR, BEL, BLZ, BEN, BMU, BTN, BOL, BES, BIH, BWA, BVT, BRA, IOT, BRN, BGR, BFA, BDI, KHM, CMR, CAN, CPV, CYM, CAF, TCD, CHL, CHN, CXR, CCK, COL, COM, COG, COK, CRI, CIV, HRV, CUB, CUW, CYP, CZE, DNK, DJI, DOM, DMA, ECU, EGY, SLV, GNQ, ERI, EST, ETH, FLK, FRO, FJI, FIN, FRA, GUF, GUY, PYF, GAB, GMB, GEO, DEU, GHA, GIB, GRC, GRL, GRD, GLP, GUM, GTM, GGY, GNB, GIN, HTI, HMD, VAT, HND, HKG, HUN, IND, IDN, IRN, IRQ, IRL, IMN, ISR, ITA, JAM, JPN, JEY, JOR, KAZ, KEN, KIR, PRK, KOR, KWT, KGZ, LAO, LVA, LBN, LSO, LBR, LBY, LIE, LTU, LUX, MAC, MKD, MDG, MWI, MYS, MDV, SOM, MLI, MLT, MHL, MTQ, MRT, MUS, MYT, MEX, FSM, MDA, MCO, MNG, MNE, MSR, MAR, MOZ, MMR, NAM, NRU, NPL, NLD, NCL, NZL, NIC, NGA, NER, NIU, NFK, MNP, NOR, OMN, PAK, PLW, PSE, PAN, PNG, PRY, PER, PHL, PCN, POL, PRT, PRI, QAT, REU, ROU, RUS, RWA, BLM, SHN, KNA, LCA, MAF, SPM, VCT, WSM, SMR, STP, SAU, SEN, SRB, SYC, SLE, SGP, SXM, SVK, SVN, SLB, ZAF, SGS, SSD, ESP, LKA, SDN, SUR, SJM, SWZ, SWE, CHE, SYR, TWN, TJK, TZA, THA, TLS, TGO, TKL, TON, TTO, TUN, TUR, TKM, TCA, TUV, UGA, UKR, ARE, GBR, USA, URY, UZB, VUT, VEN, VNM, VIR, VGB, WLF, YEM, ZMB, ZWE, ISL.

footerfooter
TEXT

Footer text to display on order documents. See Order.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

ibaniban
TEXT
MAX:100

The IBAN (International Bank Account Number).

logoFilelogoFile
FILE

The company logo. Supported types: JPG, GIF, PNG. Max. size: 400KB. Max. resolution: 2500x2500px.

orgNameorgName
TEXT
MAX:250

The name of the company.

qrIbanqrIban
TEXT
MAX:100

The QR-IBAN, which is an IBAN especially for QR invoices (former ESR). This is specific to Switzerland.

typetype
TEXT

The type of location. Defaults to MAIN (= company headquarters). Possible values: MAIN, BRANCH, STORAGE, OTHER.

vatUidvatUid
TEXT
MAX:100

The UID (VAT no.) of the company.

zipzip
TEXT
MAX:10

The postal code of the location.

Endpoint

POST /api/v1/location/update.json

Delete locations

Deletes one or multiple locations. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/location/delete.json

Organization

The following API endpoints are for reading organization (aka domain) related information. Please understand that we currently do not allow creation or manipulation of organizations via the API.

Get logo

Returns the logo image of the organization (if set) or a one pixel invisible image if not set. The content type is that of the uploaded logo image (PNG, GIF or JPEG).

Endpoint

GET /api/v1/domain/current/logo

Settings

The following API endpoints are for managing general settings.

Read settings

Returns all settings.

Endpoint

GET /api/v1/setting/read.json

Update settings

Updates the settings. You can update any number of settings, you don't have to include all of them. The parameters are not listed here (there are too many). Read the settings first (with previous endpoint) to get a list of available settings, and then update the ones you would like to update.

Endpoint

GET /api/v1/setting/update.json

Order

The following API endpoints are for managing order objects like offers, invoices, delivery notes, etc., both sales and purchase orders.

Read order

Returns a single order by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/order/read.json

List orders

Returns a list of orders per type (sales or purchase).

Parameters

categoryIdcategoryId
NUMBER

The ID of the order category to filter by. See Order category.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the orders. Leave empty to use the current fiscal period. See Switch fiscal period.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyOpenonlyOpen
BOOLEAN

Flag to only include open orders (incomplete status like 'Open' as opposed to completed status like 'Paid'). Defaults to false. Possible values: true, false.

onlyOverdueonlyOverdue
BOOLEAN

Flag to only include orders that are overdue (past the due date). Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'date'.

startstart
NUMBER

The starting entry. Defaults to 0.

statusIdstatusId
NUMBER

The ID of the order status to filter by. See Order category.

typetype
TEXT

The type of order (sales or purchase). Defaults to SALES. Possible values: SALES, PURCHASE.

Endpoint

GET /api/v1/order/list.json

Export to Excel

Returns an Excel file of the orders list per type (sales or purchase).

Parameters

categoryIdcategoryId
NUMBER

The ID of the order category to filter by. See Order category.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the orders. Leave empty to use the current fiscal period. See Switch fiscal period.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyOpenonlyOpen
BOOLEAN

Flag to only include open orders (incomplete status like 'Open' as opposed to completed status like 'Paid'). Defaults to false. Possible values: true, false.

onlyOverdueonlyOverdue
BOOLEAN

Flag to only include orders that are overdue (past the due date). Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'date'.

startstart
NUMBER

The starting entry. Defaults to 0.

statusIdstatusId
NUMBER

The ID of the order status to filter by. See Order category.

typetype
TEXT

The type of order (sales or purchase). Defaults to SALES. Possible values: SALES, PURCHASE.

Endpoint

GET /api/v1/order/list.xlsx

Export to CSV

Returns a CSV file of the orders list per type (sales or purchase).

Parameters

categoryIdcategoryId
NUMBER

The ID of the order category to filter by. See Order category.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the orders. Leave empty to use the current fiscal period. See Switch fiscal period.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyOpenonlyOpen
BOOLEAN

Flag to only include open orders (incomplete status like 'Open' as opposed to completed status like 'Paid'). Defaults to false. Possible values: true, false.

onlyOverdueonlyOverdue
BOOLEAN

Flag to only include orders that are overdue (past the due date). Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'date'.

startstart
NUMBER

The starting entry. Defaults to 0.

statusIdstatusId
NUMBER

The ID of the order status to filter by. See Order category.

typetype
TEXT

The type of order (sales or purchase). Defaults to SALES. Possible values: SALES, PURCHASE.

Endpoint

GET /api/v1/order/list.csv

Export to PDF

Returns a PDF file of the orders list per type (sales or purchase).

Parameters

categoryIdcategoryId
NUMBER

The ID of the order category to filter by. See Order category.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'DESC'. Possible values: ASC, DESC.

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the orders. Leave empty to use the current fiscal period. See Switch fiscal period.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyOpenonlyOpen
BOOLEAN

Flag to only include open orders (incomplete status like 'Open' as opposed to completed status like 'Paid'). Defaults to false. Possible values: true, false.

onlyOverdueonlyOverdue
BOOLEAN

Flag to only include orders that are overdue (past the due date). Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'date'.

startstart
NUMBER

The starting entry. Defaults to 0.

statusIdstatusId
NUMBER

The ID of the order status to filter by. See Order category.

typetype
TEXT

The type of order (sales or purchase). Defaults to SALES. Possible values: SALES, PURCHASE.

Endpoint

GET /api/v1/order/list.pdf

Create order

Creates a new order. Returns either a success or multiple error messages (for each issue).

Parameters

associateIdassociateId
mandatory
TEXT

The ID of the business partner (customer / vendor). See Person.

categoryIdcategoryId
mandatory
NUMBER

The ID of the category. See Order category.

datedate
mandatory
DATE

The date of the order.

Format: YYYY-MM-DD. Example: 2020-01-15.

accountIdaccountId
NUMBER

The ID of the account. Leave empty to use the account from the category. See Account.

currencyIdcurrencyId
NUMBER

The ID of the currency. Leave empty to use the default currency. See Currency.

currencyRatecurrencyRate
NUMBER

The exchange rate from foreign currency to main currency. Only required if the currency is not supported or if you want to use a different rate than suggested.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

descriptiondescription
TEXT
MAX:200

A description of the order document.

discountPercentagediscountPercentage
NUMBER
MIN:0.0
MAX:100.0

The discount percentage for the entire order (can be overriden in items).

dueDaysdueDays
NUMBER

The due days. Order date + due days = Due date (the date, when payment is due).

endDateendDate
DATE

The end date for the recurrence (see recurrence parameter). Orders repeat automatically up until this date, when the recurrence will stop.

Format: YYYY-MM-DD. Example: 2020-01-15.

groupIdgroupId
NUMBER

The ID of the order group (dossier). Use this to include the order in a dossier with other orders that belong together (e.g. the offer, order confirmation, delivery note and invoice of the same order). Note that isGrouped must be set to true. This overrides the group of previousId (if both are set).

isDisplayItemGrossisDisplayItemGross
BOOLEAN

Whether to display item totals as gross (including tax). Defaults to false (net). Possible values: true, false.

isGroupedisGrouped
BOOLEAN

Whether to group the order in a dossier or not. See also previousId and groupId. Defaults to true. Possible values: true, false.

itemsitems
JSON

The list of order items.

This is a JSON array [{...},{...},...] with the following parameters:

accountIdaccountId
mandatory
NUMBER

The ID of the account (revenue account for sales, expense account for purchase). See Account.

namename
mandatory
TEXT

The name of the item.

unitPriceunitPrice
mandatory
NUMBER

The price of the item (for one unit).

articleNrarticleNr
TEXT

The article number.

descriptiondescription
TEXT

A description of the item.

discountPercentagediscountPercentage
NUMBER

Discount percentage for the item price.

inventoryIdinventoryId
NUMBER

The ID of the inventory article. See Inventory.

quantityquantity
NUMBER

The amount of units of the item. Defaults to 1.

taxIdtaxId
NUMBER

The ID of the tax rate. See Tax rates.

typetype
TEXT

The type of item. Defaults to ARTICLE. Possible values: ARTICLE, TEXT, PAGEBREAK, SUBTOTAL.

unitIdunitId
TEXT

The ID of the unit (pcs., hours, etc.). See Units.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

nrnr
TEXT
MAX:50

The order number (e.g. 'IN-2001015' for an invoice). Leave empty to generate the number with sequenceNumberId. This becomes mandatory, if a sequence number is set neither here nor in the order category.

previousIdpreviousId
NUMBER

The ID of the previous order from which this order is created (Next step / Continue as). The new order will be grouped with the previous order in a dossier, if isGroupedis set to true. groupId doesn't have to be set.

recurrencerecurrence
TEXT

The interval of how often the order should be automatically repeated. Leave empty to not repeat the order. See also startDate and endDate. Possible values: MONTHLY, WEEKLY, DAILY, YEARLY, SEMESTRAL, QUARTERLY, BI_MONTHLY, BI_WEEKLY.

responsiblePersonIdresponsiblePersonId
TEXT

The ID of the responsible person (Sachbearbeiter). See Person.

roundingIdroundingId
NUMBER

The ID of the rounding to use for the grand total. See Rounding.

sequenceNumberIdsequenceNumberId
NUMBER

The ID of the sequence number used to generate the order number (see nr). If empty, the sequence number of the category is used (if set). See Sequence number.

startDatestartDate
DATE

The start date for the recurrence (see recurrence parameter). This is the date when the order will be repeated next. Should probably be called nextDate instead.

Format: YYYY-MM-DD. Example: 2020-01-15.

statusIdstatusId
NUMBER

The ID of the status to set. Leave empty to use the first status in the list. See Order category.

Endpoint

POST /api/v1/order/create.json

Update order

Updates an existing order. Returns either a success or multiple error messages (for each issue).

Parameters

associateIdassociateId
mandatory
TEXT

The ID of the business partner (customer / vendor). See Person.

categoryIdcategoryId
mandatory
NUMBER

The ID of the category. See Order category.

datedate
mandatory
DATE

The date of the order.

Format: YYYY-MM-DD. Example: 2020-01-15.

idid
mandatory
NUMBER

The ID of the order to update.

accountIdaccountId
NUMBER

The ID of the account. Leave empty to use the account from the category. See Account.

currencyIdcurrencyId
NUMBER

The ID of the currency. Leave empty to use the default currency. See Currency.

currencyRatecurrencyRate
NUMBER

The exchange rate from foreign currency to main currency. Only required if the currency is not supported or if you want to use a different rate than suggested.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

descriptiondescription
TEXT
MAX:200

A description of the order document.

discountPercentagediscountPercentage
NUMBER
MIN:0.0
MAX:100.0

The discount percentage for the entire order (can be overriden in items).

dueDaysdueDays
NUMBER

The due days. Order date + due days = Due date (the date, when payment is due).

endDateendDate
DATE

The end date for the recurrence (see recurrence parameter). Orders repeat automatically up until this date, when the recurrence will stop.

Format: YYYY-MM-DD. Example: 2020-01-15.

groupIdgroupId
NUMBER

The ID of the order group (dossier). Use this to include the order in a dossier with other orders that belong together (e.g. the offer, order confirmation, delivery note and invoice of the same order). Note that isGrouped must be set to true. This overrides the group of previousId (if both are set).

isDisplayItemGrossisDisplayItemGross
BOOLEAN

Whether to display item totals as gross (including tax). Defaults to false (net). Possible values: true, false.

isGroupedisGrouped
BOOLEAN

Whether to group the order in a dossier or not. See also previousId and groupId. Defaults to true. Possible values: true, false.

itemsitems
JSON

The list of order items.

This is a JSON array [{...},{...},...] with the following parameters:

accountIdaccountId
mandatory
NUMBER

The ID of the account (revenue account for sales, expense account for purchase). See Account.

namename
mandatory
TEXT

The name of the item.

unitPriceunitPrice
mandatory
NUMBER

The price of the item (for one unit).

articleNrarticleNr
TEXT

The article number.

descriptiondescription
TEXT

A description of the item.

discountPercentagediscountPercentage
NUMBER

Discount percentage for the item price.

inventoryIdinventoryId
NUMBER

The ID of the inventory article. See Inventory.

quantityquantity
NUMBER

The amount of units of the item. Defaults to 1.

taxIdtaxId
NUMBER

The ID of the tax rate. See Tax rates.

typetype
TEXT

The type of item. Defaults to ARTICLE. Possible values: ARTICLE, TEXT, PAGEBREAK, SUBTOTAL.

unitIdunitId
TEXT

The ID of the unit (pcs., hours, etc.). See Units.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

nrnr
TEXT
MAX:50

The order number (e.g. 'IN-2001015' for an invoice). Leave empty to generate the number with sequenceNumberId. This becomes mandatory, if a sequence number is set neither here nor in the order category.

previousIdpreviousId
NUMBER

The ID of the previous order from which this order is created (Next step / Continue as). The new order will be grouped with the previous order in a dossier, if isGroupedis set to true. groupId doesn't have to be set.

recurrencerecurrence
TEXT

The interval of how often the order should be automatically repeated. Leave empty to not repeat the order. See also startDate and endDate. Possible values: MONTHLY, WEEKLY, DAILY, YEARLY, SEMESTRAL, QUARTERLY, BI_MONTHLY, BI_WEEKLY.

responsiblePersonIdresponsiblePersonId
TEXT

The ID of the responsible person (Sachbearbeiter). See Person.

roundingIdroundingId
NUMBER

The ID of the rounding to use for the grand total. See Rounding.

sequenceNumberIdsequenceNumberId
NUMBER

The ID of the sequence number used to generate the order number (see nr). If empty, the sequence number of the category is used (if set). See Sequence number.

startDatestartDate
DATE

The start date for the recurrence (see recurrence parameter). This is the date when the order will be repeated next. Should probably be called nextDate instead.

Format: YYYY-MM-DD. Example: 2020-01-15.

statusIdstatusId
NUMBER

The ID of the status to set. Leave empty to use the first status in the list. See Order category.

Endpoint

POST /api/v1/order/update.json

Delete orders

Deletes one or multiple orders. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/order/delete.json

Read status

Reads the status of an existing order by order ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/order/status_info.json

Update status

Updates the status of an existing order by order ID. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the order.

statusIdstatusId
mandatory
NUMBER

The ID of the new status.

Endpoint

POST /api/v1/order/update_status.json

Update recurrence

Updates the recurrence of an existing order by order ID. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the order.

endDateendDate
DATE

The end date for the recurrence. Orders repeat automatically up until this date, when the recurrence will stop.

Format: YYYY-MM-DD. Example: 2020-01-15.

recurrencerecurrence
TEXT

The interval of how often the order should be automatically repeated. Leave empty to not repeat the order (or to remove recurrence). Possible values: MONTHLY, WEEKLY, DAILY, YEARLY, SEMESTRAL, QUARTERLY, BI_MONTHLY, BI_WEEKLY.

startDatestartDate
DATE

The start date for the recurrence. This is the date when the order will be repeated next. Should probably be called nextDate instead.

Format: YYYY-MM-DD. Example: 2020-01-15.

Endpoint

POST /api/v1/order/update_recurrence.json

Read dossier

Reads a dossier (group of orders that belong together).

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/order/dossier.json

Book entry

The following API endpoints are for managing order book entries. These are all the journal book entries that are created for an order (e.g. an invoice or a credit note), either automatically from items or manually by the user, like payments for example. Automatically created book entries cannot be manipulated directly, only by changing items (see Orders).

Read book entry

Returns a single book entry by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/order/bookentry/read.json

List book entries

Returns a list of book entries for an order.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/order/bookentry/list.json

Create book entry

Creates a new book entry. Returns either a success or multiple error messages (for each issue).

Parameters

accountIdaccountId
mandatory
NUMBER

The ID of the account (e.g. a bank account). This is the contra account to the account defined in the order category (typically the debtors or creditors account). See Account.

amountamount
mandatory
NUMBER

The amount of the book entry (e.g. 125.50).

orderIdorderId
mandatory
NUMBER

The ID of the order. See Order.

currencyIdcurrencyId
NUMBER

The ID of the currency. Leave empty to use the default currency. See Currency.

currencyRatecurrencyRate
NUMBER

The exchange rate from foreign currency to main currency. Only required if the currency is not supported or if you want to use a different rate than suggested.

datedate
DATE

The date of the book entry.

Format: YYYY-MM-DD. Example: 2020-01-15.

descriptiondescription
TEXT
MAX:200

The description of the book entry.

referencereference
TEXT

An optional reference / receipt for the book entry.

taxIdtaxId
NUMBER

The ID of the tax rate. See Tax rates.

templateIdtemplateId
NUMBER

The ID of the book entry template. The templates are defined in the order category. See Order category.

Endpoint

POST /api/v1/order/bookentry/create.json

Update book entry

Updates an existing book entry. Note that you cannot update book entries that have been automatically created from order items, only manually created book entries (e.g. payments). Returns either a success or multiple error messages (for each issue).

Parameters

accountIdaccountId
mandatory
NUMBER

The ID of the account (e.g. a bank account). This is the contra account to the account defined in the order category (typically the debtors or creditors account). See Account.

amountamount
mandatory
NUMBER

The amount of the book entry (e.g. 125.50).

idid
mandatory
NUMBER

The ID of the book entry to update.

orderIdorderId
mandatory
NUMBER

The ID of the order. See Order.

currencyIdcurrencyId
NUMBER

The ID of the currency. Leave empty to use the default currency. See Currency.

currencyRatecurrencyRate
NUMBER

The exchange rate from foreign currency to main currency. Only required if the currency is not supported or if you want to use a different rate than suggested.

datedate
DATE

The date of the book entry.

Format: YYYY-MM-DD. Example: 2020-01-15.

descriptiondescription
TEXT
MAX:200

The description of the book entry.

referencereference
TEXT

An optional reference / receipt for the book entry.

taxIdtaxId
NUMBER

The ID of the tax rate. See Tax rates.

templateIdtemplateId
NUMBER

The ID of the book entry template. The templates are defined in the order category. See Order category.

Endpoint

POST /api/v1/order/bookentry/update.json

Delete book entries

Deletes one or multiple book entries. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/order/bookentry/delete.json

Category

The following API endpoints are for managing order categories. An order category is for example 'Offers', 'Invoices', 'Delivery notes', etc. A category contains the configuration for the order document and how it behaves. It defines the different status a document can have, or whether the document creates journal book entries or not. You can add as many categories as you like and thus create your own workflow.

Read category

Returns a single category by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/order/category/read.json

List categories

Returns a list of categories per type (sales or purchase).

Parameters

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period, from which we retrieve the counts (number of orders). Leave empty to use the current fiscal period. See Switch fiscal period.

typetype
TEXT

The type of category (sales orders or purchase orders). Defaults to SALES. Possible values: SALES, PURCHASE.

Endpoint

GET /api/v1/order/category/list.json

Create category

Creates a new category. Returns either a success or multiple error messages (for each issue).

Parameters

accountIdaccountId
mandatory
NUMBER

The ID of the account, which is typically the debtors account for sales and the creditors account for purchase. See Account.

namePluralnamePlural
mandatory
TEXT
MAX:100

The plural name of the category (e.g. 'Invoices').

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

nameSingularnameSingular
mandatory
TEXT
MAX:100

The singular name of the category (e.g. 'Invoice').

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

statusstatus
mandatory
JSON

The status list (like 'Draft', 'Open', 'Paid', etc.) for this order category. At least one status must exist.

This is a JSON array [{...},{...},...] with the following parameters:

iconicon
mandatory
TEXT

The icon/color of the status. Possible values: BLUE, GREEN, RED, YELLOW, ORANGE, BLACK, GRAY, BROWN, VIOLET, PINK.

namename
mandatory
TEXT

The name of the status.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

actionIdactionId
TEXT

An action associated with the status, i.e. what happens after I change the status to this? The action ID looks like this for example: CATEGORY_9. This would mean that another document of the order category with ID 9 will be created after changing to this status (CashCtrl asks the user first). The first part is either CATEGORY or BOOK_TEMPLATE. Then comes and underscore and the actual ID of the category or book template (e.g. BOOK_TEMPLATE_10).

isAddStockisAddStock
BOOLEAN

Whether inventory stock is added with this status. Note that when changing between two statuses that both have isAddStock set, it will only be added once, not twice. No matter how many times you change the status, it's only ever added once. Defaults to false. Possible values: true, false.

isBookisBook
BOOLEAN

Whether journal book entries will be created with this status. For example, the invoice status 'Draft' will not create any book entries, but all the other status after that ('Open', 'Paid', etc.) will. Defaults to false. Possible values: true, false.

isClosedisClosed
BOOLEAN

Whether the status closes / completes the order object. This would be the case, for example, if an invoice has been fully paid. The effect is that the invoice is no longer due, even if past the due date (so no longer marked red). Defaults to false. Possible values: true, false.

isRemoveStockisRemoveStock
BOOLEAN

Whether inventory stock is removed with this status. Note that when changing between two statuses that both have isRemoveStock set, it will only be removed once, not twice. No matter how many times you change the status, it's only ever removed once. Defaults to false. Possible values: true, false.

bookTemplatesbookTemplates
JSON

The book (entry) templates defined in this order category. An example of a book template for order categories would be the 'Payment' book template, which already has the appropriate bank account set, so that payments can be added with one click.

This is a JSON array [{...},{...},...] with the following parameters:

accountIdaccountId
mandatory
NUMBER

The ID of the account in this book template. This is typically a bank account in case of a payment template, and it's the contra account to the account set on the order (debtors or creditors account). See Account.

namename
mandatory
TEXT

A name / description of the book template, which will be used as the description for the actual book entry. Example: 'Payment'.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

isAllowTaxisAllowTax
BOOLEAN

Whether the actual book entry will allow setting a tax rate. This is to prevent the user from making a mistake (e.g. for payment book entries). Defaults to false. Possible values: true, false.

taxIdtaxId
NUMBER

The ID of the tax rate in this book template. This is only used if isAllowTax is true. For a payment book entry template you generally wouldn't allow setting a tax rate. See Tax rates.

bookTypebookType
TEXT

Whether the account (see accountId) is on the debit or credit side in the book entry. Defaults to DEBIT. Possible values: DEBIT, CREDIT.

currencyIdcurrencyId
NUMBER

The ID of the currency used by default for order objects in this category. Leave empty to use the default currency. See Currency.

dueDaysdueDays
NUMBER

The due days used by default for order objects in this category. The order date + due days equals the due date.

footerfooter
HTML

The text displayed below the items list on the document used by default for order objects in this category.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

hasDueDayshasDueDays
BOOLEAN

Whether order objects in this category can have due days. The dueDays parameter is ignored if set to false. Defaults to false. Possible values: true, false.

headerheader
HTML

The text displayed above the items list on the document used by default for order objects in this category.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

isDisplayItemGrossisDisplayItemGross
BOOLEAN

Whether order item totals are displayed as gross (including tax) or net. Defaults to false. Possible values: true, false.

isDisplayPricesisDisplayPrices
BOOLEAN

Whether prices and totals are displayed on the document. For example a delivery note might not display prices, but an invoice does. Defaults to false. Possible values: true, false.

isInactiveisInactive
BOOLEAN

Mark category as inactive. Inactive categories are no longer displayed, but the documents in the category are not deleted. Defaults to false. Possible values: true, false.

isSwitchRecipientisSwitchRecipient
BOOLEAN

Switch recipient? By default your company is the sender and the client/vendor is the recipient. This flag switches sender and recipient. Defaults to false. Possible values: true, false.

mailmail
HTML

The mail text (for the send mail feature) used by default for order objects in this category.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

responsiblePersonIdresponsiblePersonId
TEXT

The ID of the responsible person (Sachbearbeiter) used for order objects in this category. See Person.

roundingIdroundingId
NUMBER

The ID of the rounding used for order objects in this category. See Rounding.

sentStatusIdsentStatusId
NUMBER

The ID of the status to automatically set when the order document is either sent by mail or downloaded. See status parameter. This can only be set if the category has already been saved, otherwise the status might not have an ID yet.

sequenceNrIdsequenceNrId
NUMBER

The ID of the sequence number used for order objects in this category. See Sequence number.

templateIdtemplateId
NUMBER

The ID of the document template used for order objects in this category. See Document template.

typetype
TEXT

The type of category (sales orders or purchase orders). Defaults to SALES. Possible values: SALES, PURCHASE.

Endpoint

POST /api/v1/order/category/create.json

Update category

Updates an existing category. Returns either a success or multiple error messages (for each issue).

Parameters

accountIdaccountId
mandatory
NUMBER

The ID of the account, which is typically the debtors account for sales and the creditors account for purchase. See Account.

idid
mandatory
NUMBER

The ID of the category to update.

namePluralnamePlural
mandatory
TEXT
MAX:100

The plural name of the category (e.g. 'Invoices').

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

nameSingularnameSingular
mandatory
TEXT
MAX:100

The singular name of the category (e.g. 'Invoice').

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

statusstatus
mandatory
JSON

The status list (like 'Draft', 'Open', 'Paid', etc.) for this order category. At least one status must exist.

This is a JSON array [{...},{...},...] with the following parameters:

iconicon
mandatory
TEXT

The icon/color of the status. Possible values: BLUE, GREEN, RED, YELLOW, ORANGE, BLACK, GRAY, BROWN, VIOLET, PINK.

namename
mandatory
TEXT

The name of the status.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

actionIdactionId
TEXT

An action associated with the status, i.e. what happens after I change the status to this? The action ID looks like this for example: CATEGORY_9. This would mean that another document of the order category with ID 9 will be created after changing to this status (CashCtrl asks the user first). The first part is either CATEGORY or BOOK_TEMPLATE. Then comes and underscore and the actual ID of the category or book template (e.g. BOOK_TEMPLATE_10).

isAddStockisAddStock
BOOLEAN

Whether inventory stock is added with this status. Note that when changing between two statuses that both have isAddStock set, it will only be added once, not twice. No matter how many times you change the status, it's only ever added once. Defaults to false. Possible values: true, false.

isBookisBook
BOOLEAN

Whether journal book entries will be created with this status. For example, the invoice status 'Draft' will not create any book entries, but all the other status after that ('Open', 'Paid', etc.) will. Defaults to false. Possible values: true, false.

isClosedisClosed
BOOLEAN

Whether the status closes / completes the order object. This would be the case, for example, if an invoice has been fully paid. The effect is that the invoice is no longer due, even if past the due date (so no longer marked red). Defaults to false. Possible values: true, false.

isRemoveStockisRemoveStock
BOOLEAN

Whether inventory stock is removed with this status. Note that when changing between two statuses that both have isRemoveStock set, it will only be removed once, not twice. No matter how many times you change the status, it's only ever removed once. Defaults to false. Possible values: true, false.

bookTemplatesbookTemplates
JSON

The book (entry) templates defined in this order category. An example of a book template for order categories would be the 'Payment' book template, which already has the appropriate bank account set, so that payments can be added with one click.

This is a JSON array [{...},{...},...] with the following parameters:

accountIdaccountId
mandatory
NUMBER

The ID of the account in this book template. This is typically a bank account in case of a payment template, and it's the contra account to the account set on the order (debtors or creditors account). See Account.

namename
mandatory
TEXT

A name / description of the book template, which will be used as the description for the actual book entry. Example: 'Payment'.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

isAllowTaxisAllowTax
BOOLEAN

Whether the actual book entry will allow setting a tax rate. This is to prevent the user from making a mistake (e.g. for payment book entries). Defaults to false. Possible values: true, false.

taxIdtaxId
NUMBER

The ID of the tax rate in this book template. This is only used if isAllowTax is true. For a payment book entry template you generally wouldn't allow setting a tax rate. See Tax rates.

bookTypebookType
TEXT

Whether the account (see accountId) is on the debit or credit side in the book entry. Defaults to DEBIT. Possible values: DEBIT, CREDIT.

currencyIdcurrencyId
NUMBER

The ID of the currency used by default for order objects in this category. Leave empty to use the default currency. See Currency.

dueDaysdueDays
NUMBER

The due days used by default for order objects in this category. The order date + due days equals the due date.

footerfooter
HTML

The text displayed below the items list on the document used by default for order objects in this category.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

hasDueDayshasDueDays
BOOLEAN

Whether order objects in this category can have due days. The dueDays parameter is ignored if set to false. Defaults to false. Possible values: true, false.

headerheader
HTML

The text displayed above the items list on the document used by default for order objects in this category.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

isDisplayItemGrossisDisplayItemGross
BOOLEAN

Whether order item totals are displayed as gross (including tax) or net. Defaults to false. Possible values: true, false.

isDisplayPricesisDisplayPrices
BOOLEAN

Whether prices and totals are displayed on the document. For example a delivery note might not display prices, but an invoice does. Defaults to false. Possible values: true, false.

isInactiveisInactive
BOOLEAN

Mark category as inactive. Inactive categories are no longer displayed, but the documents in the category are not deleted. Defaults to false. Possible values: true, false.

isSwitchRecipientisSwitchRecipient
BOOLEAN

Switch recipient? By default your company is the sender and the client/vendor is the recipient. This flag switches sender and recipient. Defaults to false. Possible values: true, false.

mailmail
HTML

The mail text (for the send mail feature) used by default for order objects in this category.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

responsiblePersonIdresponsiblePersonId
TEXT

The ID of the responsible person (Sachbearbeiter) used for order objects in this category. See Person.

roundingIdroundingId
NUMBER

The ID of the rounding used for order objects in this category. See Rounding.

sentStatusIdsentStatusId
NUMBER

The ID of the status to automatically set when the order document is either sent by mail or downloaded. See status parameter. This can only be set if the category has already been saved, otherwise the status might not have an ID yet.

sequenceNrIdsequenceNrId
NUMBER

The ID of the sequence number used for order objects in this category. See Sequence number.

templateIdtemplateId
NUMBER

The ID of the document template used for order objects in this category. See Document template.

typetype
TEXT

The type of category (sales orders or purchase orders). Defaults to SALES. Possible values: SALES, PURCHASE.

Endpoint

POST /api/v1/order/category/update.json

Delete categories

Deletes one or multiple existing category. Note that you can only delete empty categories. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/order/category/delete.json

Reorder categories

Changes the order of one or multiple categories. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the entries to reorder, comma-separated.

targettarget
mandatory
NUMBER

The ID of the target entry. The entries (see ids) will be ordered before or after (see before) this entry.

beforebefore
BOOLEAN

Reorder before the target entry, after otherwise. Defaults to true. Possible values: true, false.

typetype
TEXT

The type of category. Defaults to SALES. Possible values: SALES, PURCHASE.

Endpoint

POST /api/v1/order/category/reorder.json

Read status

Returns a single status by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/order/category/read_status.json

Document

The following API endpoints are for managing order documents. This API is not used to manage the order itself (like date, number, customer, items, etc.) - for that, see Orders. Here you only manage the sender / recipient of the document, which document template to use, and the document language. You can download the document as PDF or ZIP, and mail the document to the recipient.

Read document

Returns a single document by order ID.

Parameters

idid
mandatory
NUMBER

The ID of the order.

Endpoint

GET /api/v1/order/document/read.json

Download PDF

Downloads one or multiple order documents in one PDF file.

Parameters

idsids
mandatory
CSV

The IDs of one or multiple orders, comma-separated.

Endpoint

GET /api/v1/order/document/read.pdf

Download ZIP

Downloads one or multiple order documents in a ZIP file (one PDF for each document).

Parameters

idsids
mandatory
CSV

The IDs of one or multiple orders, comma-separated.

Endpoint

GET /api/v1/order/document/read.zip

Mail document

Sends a document per e-mail to the desired recipient(s).

Parameters

mailFrommailFrom
mandatory
TEXT
MAX:255

The sender / from e-mail address.

mailSubjectmailSubject
mandatory
TEXT
MAX:255

The mail subject. Can contain variables.

mailTextmailText
mandatory
TEXT

The mail text. Can contain variables.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

mailTomailTo
mandatory
TEXT

The recipient e-mail address. You can enter multiple addresses comma-separated.

orderIdorderId
mandatory
NUMBER

The ID of the order. See Order.

mailBccmailBcc
TEXT

The BCC (blind carbon copy) e-mail address. You can enter multiple addresses comma-separated.

mailCcmailCc
TEXT

The CC (carbon copy) e-mail address. You can enter multiple addresses comma-separated.

mailReplyTomailReplyTo
TEXT
MAX:255

The reply-to e-mail address. Replies from the recipient will go to this address instead of the mailFrom address.

sentStatusIdsentStatusId
NUMBER

The ID of the status to set on the order after the mail has been sent. See Order category.

Endpoint

POST /api/v1/order/document/mail.json

Update document

Updates an existing document. To update the actual order object, see Order.

Parameters

idid
mandatory
NUMBER

The ID of the order to update. See Order.

footerfooter
HTML

The text displayed below the items list on the document used by default for order objects in this category.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

headerheader
HTML

The text displayed above the items list on the document used by default for order objects in this category.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

isDisplayItemGrossisDisplayItemGross
BOOLEAN

Whether order item totals are displayed as gross (including tax) or net. Defaults to false. Possible values: true, false.

languagelanguage
TEXT

The language of the document. Possible values: DE, EN, FR, IT.

orgAddressorgAddress
TEXT
MAX:255

The sender address formatted with line breaks.

orgLocationIdorgLocationId
NUMBER

The ID of the sender location. See Location.

recipientAddressrecipientAddress
TEXT
MAX:255

The recipient address formatted with line breaks.

recipientAddressIdrecipientAddressId
NUMBER

The ID of the recipient address (person address). See Person.

templateIdtemplateId
NUMBER

The ID of the document template. See Document template.

Endpoint

POST /api/v1/order/document/update.json

Document template

The following API endpoints are for managing document templates. Document templates define the look and feel of the Order document.

Read template

Returns a single template by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/order/template/read.json

List templates

Returns a list of all templates.

Endpoint

GET /api/v1/order/template/list.json

Create template

Creates a new template. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT

A name to describe and identify the template.

csscss
CSS

The CSS stylesheet for the template.

footerfooter
HTML

The footer text, which is displayed at the bottom of the document.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

htmlhtml
HTML

The HTML and Apache Velocity template.

isDefaultisDefault
BOOLEAN

Mark the template as the default template to use. Defaults to false. Possible values: true, false.

isDisplayDocumentNameisDisplayDocumentName
BOOLEAN

Display document name/title? Defaults to true. Possible values: true, false.

isDisplayItemArticleNrisDisplayItemArticleNr
BOOLEAN

Display article no. for items? Defaults to true. Possible values: true, false.

isDisplayItemPriceRoundedisDisplayItemPriceRounded
BOOLEAN

Display item prices rounded? Defaults to true. Possible values: true, false.

isDisplayItemUnitisDisplayItemUnit
BOOLEAN

Display unit for items? Defaults to true. Possible values: true, false.

isDisplayLogoisDisplayLogo
BOOLEAN

Display logo? Defaults to true. Possible values: true, false.

isDisplayOrgAddressInWindowisDisplayOrgAddressInWindow
BOOLEAN

Display (your) organization address in window? Defaults to true. Possible values: true, false.

isDisplayPageNrisDisplayPageNr
BOOLEAN

Display page numbers? Defaults to true. Possible values: true, false.

isDisplayPosNrisDisplayPosNr
BOOLEAN

Display item numbering? Defaults to true. Possible values: true, false.

isDisplayRecipientNrisDisplayRecipientNr
BOOLEAN

Display recipient number (customer/vendor no.)? Defaults to true. Possible values: true, false.

isDisplayResponsiblePersonisDisplayResponsiblePerson
BOOLEAN

Display responsible person (Sachbearbeiter)? Defaults to true. Possible values: true, false.

logoHeightlogoHeight
NUMBER
MIN:0.1
MAX:9.0

The height of the logo in centimeters.

pageSizepageSize
TEXT

The page size of the document. Defaults to A4. Possible values: A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, LEGAL, LETTER, A4R.

Endpoint

POST /api/v1/order/template/create.json

Update template

Updates an existing template. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the template to update.

namename
mandatory
TEXT

A name to describe and identify the template.

csscss
CSS

The CSS stylesheet for the template.

footerfooter
HTML

The footer text, which is displayed at the bottom of the document.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

htmlhtml
HTML

The HTML and Apache Velocity template.

isDefaultisDefault
BOOLEAN

Mark the template as the default template to use. Defaults to false. Possible values: true, false.

isDisplayDocumentNameisDisplayDocumentName
BOOLEAN

Display document name/title? Defaults to true. Possible values: true, false.

isDisplayItemArticleNrisDisplayItemArticleNr
BOOLEAN

Display article no. for items? Defaults to true. Possible values: true, false.

isDisplayItemPriceRoundedisDisplayItemPriceRounded
BOOLEAN

Display item prices rounded? Defaults to true. Possible values: true, false.

isDisplayItemUnitisDisplayItemUnit
BOOLEAN

Display unit for items? Defaults to true. Possible values: true, false.

isDisplayLogoisDisplayLogo
BOOLEAN

Display logo? Defaults to true. Possible values: true, false.

isDisplayOrgAddressInWindowisDisplayOrgAddressInWindow
BOOLEAN

Display (your) organization address in window? Defaults to true. Possible values: true, false.

isDisplayPageNrisDisplayPageNr
BOOLEAN

Display page numbers? Defaults to true. Possible values: true, false.

isDisplayPosNrisDisplayPosNr
BOOLEAN

Display item numbering? Defaults to true. Possible values: true, false.

isDisplayRecipientNrisDisplayRecipientNr
BOOLEAN

Display recipient number (customer/vendor no.)? Defaults to true. Possible values: true, false.

isDisplayResponsiblePersonisDisplayResponsiblePerson
BOOLEAN

Display responsible person (Sachbearbeiter)? Defaults to true. Possible values: true, false.

logoHeightlogoHeight
NUMBER
MIN:0.1
MAX:9.0

The height of the logo in centimeters.

pageSizepageSize
TEXT

The page size of the document. Defaults to A4. Possible values: A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, LEGAL, LETTER, A4R.

Endpoint

POST /api/v1/order/template/update.json

Delete templates

Deletes one or multiple templates. Note that you cannot delete system templates, only manually created ones. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/order/template/delete.json

Person

The following API endpoints are for managing people / contacts.

Read person

Returns a single person by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/person/read.json

List people

Returns a list of people.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active people. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only people without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'name'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/person/list.json

Export to Excel

Returns an Excel file of the people list.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active people. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only people without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'name'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/person/list.xlsx

Export to CSV

Returns a CSV file of the people list.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active people. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only people without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'name'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/person/list.csv

Export to PDF

Returns a PDF file of the people list.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active people. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only people without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'name'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/person/list.pdf

Export to vCard

Returns a vCard file containing a list of people.

Parameters

categoryIdcategoryId
NUMBER

The ID of the category to filter by.

columnscolumns
CSV

The columns to include in the list, comma-separated. Check the list.json for available column names.

dirdir
TEXT

The direction of the sort order (ascending or descending). Defaults to 'ASC'. Possible values: ASC, DESC.

limitlimit
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
BOOLEAN

Flag to include only active people. Defaults to false. Possible values: true, false.

onlyNotesonlyNotes
BOOLEAN

Flag to only include entries with notes. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
BOOLEAN

Flag to include only people without a category. Defaults to false. Possible values: true, false.

queryquery
TEXT

Fulltext search query.

sortsort
TEXT

The column to sort the list by. Defaults to 'name'.

startstart
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/person/list.vcf

Create person

Creates a new person. Returns either a success or multiple error messages (for each issue).

Parameters

companycompany
mandatory
TEXT
MAX:100

The name of the organization / company. Either firstName, lastName or company must be set.

firstNamefirstName
mandatory
TEXT
MAX:50

The person's first (given) name. Either firstName, lastName or company must be set.

lastNamelastName
mandatory
TEXT
MAX:50

The person's last (family) name. Either firstName, lastName or company must be set.

addressesaddresses
JSON

A list of addresses (street, house number, zip, city, country).

This is a JSON array [{...},{...},...] with the following parameters:

typetype
mandatory
TEXT

The type of address. Main address, invoice address, etc. Possible values: MAIN, INVOICE, DELIVERY, OTHER.

addressaddress
TEXT

The address (street, house number, additional info). Can contain multiple lines.

citycity
TEXT

The town / city of the address.

countrycountry
TEXT

The country of the address. Possible values: AFG, ALA, ALB, DZA, ASM, AND, AGO, AIA, ATG, ARG, ARM, ABW, AUS, AUT, AZE, BHS, BHR, BGD, BRB, BLR, BEL, BLZ, BEN, BMU, BTN, BOL, BES, BIH, BWA, BVT, BRA, IOT, BRN, BGR, BFA, BDI, KHM, CMR, CAN, CPV, CYM, CAF, TCD, CHL, CHN, CXR, CCK, COL, COM, COG, COK, CRI, CIV, HRV, CUB, CUW, CYP, CZE, DNK, DJI, DOM, DMA, ECU, EGY, SLV, GNQ, ERI, EST, ETH, FLK, FRO, FJI, FIN, FRA, GUF, GUY, PYF, GAB, GMB, GEO, DEU, GHA, GIB, GRC, GRL, GRD, GLP, GUM, GTM, GGY, GNB, GIN, HTI, HMD, VAT, HND, HKG, HUN, IND, IDN, IRN, IRQ, IRL, IMN, ISR, ITA, JAM, JPN, JEY, JOR, KAZ, KEN, KIR, PRK, KOR, KWT, KGZ, LAO, LVA, LBN, LSO, LBR, LBY, LIE, LTU, LUX, MAC, MKD, MDG, MWI, MYS, MDV, SOM, MLI, MLT, MHL, MTQ, MRT, MUS, MYT, MEX, FSM, MDA, MCO, MNG, MNE, MSR, MAR, MOZ, MMR, NAM, NRU, NPL, NLD, NCL, NZL, NIC, NGA, NER, NIU, NFK, MNP, NOR, OMN, PAK, PLW, PSE, PAN, PNG, PRY, PER, PHL, PCN, POL, PRT, PRI, QAT, REU, ROU, RUS, RWA, BLM, SHN, KNA, LCA, MAF, SPM, VCT, WSM, SMR, STP, SAU, SEN, SRB, SYC, SLE, SGP, SXM, SVK, SVN, SLB, ZAF, SGS, SSD, ESP, LKA, SDN, SUR, SJM, SWZ, SWE, CHE, SYR, TWN, TJK, TZA, THA, TLS, TGO, TKL, TON, TTO, TUN, TUR, TKM, TCA, TUV, UGA, UKR, ARE, GBR, USA, URY, UZB, VUT, VEN, VNM, VIR, VGB, WLF, YEM, ZMB, ZWE, ISL.

zipzip
TEXT

The postal code of the address.

bicbic
TEXT
MAX:11

The BIC (Business Identifier Code) of the person's bank.

categoryIdcategoryId
NUMBER

The ID of the category. See Person category.

contactscontacts
JSON

A list of contact information (e-mail, phone, url, etc.).

This is a JSON array [{...},{...},...] with the following parameters:

addressaddress
mandatory
TEXT

The actual contact information (e-mail address, phone number, etc.).

purposepurpose
mandatory
TEXT

The purpose (sub-type) of the contact information. Possible values: PRIVATE, WORK, RECEPTION, INVOICE.

typetype
mandatory
TEXT

The type of contact information. Possible values: EMAIL, PHONE, MOBILE, FAX, SKYPE, WEBSITE, OTHER.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

dateBirthdateBirth
DATE

The person's date of birth.

Format: YYYY-MM-DD. Example: 2020-01-15.

departmentdepartment
TEXT
MAX:100

The department of the person within the company.

discountPercentagediscountPercentage
NUMBER
MIN:0.0
MAX:100.0

Discount percentage for this person, which may be used for orders. This can also be set on the category for all people in that category.

ibaniban
TEXT
MAX:50

The IBAN (International Bank Account Number) of the person.

industryindustry
TEXT
MAX:100

The industry of the company or the trade/vocation of the person.

isInactiveisInactive
BOOLEAN

Mark the person as inactive. The person will be greyed out and no longer suggested. Defaults to false. Possible values: true, false.

languagelanguage
TEXT

The main language of the person. May be used for documents. Possible values: DE, EN, FR, IT.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

nrnr
TEXT
MAX:50

The person number (e.g. customer no.).

positionposition
TEXT
MAX:100

The position (job title) of the person within the company.

sequenceNumberIdsequenceNumberId
NUMBER

The ID of the sequence number used to generate the person number (see nr). If this is empty, the sequence number will not update when nr is set. See Sequence number.

titleIdtitleId
NUMBER

The person's title (e.g. 'Mr.', 'Mrs.', 'Dr.'). See Person title.

Endpoint

POST /api/v1/person/create.json

Update person

Updates an existing person. Returns either a success or multiple error messages (for each issue).

Parameters

companycompany
mandatory
TEXT
MAX:100

The name of the organization / company. Either firstName, lastName or company must be set.

firstNamefirstName
mandatory
TEXT
MAX:50

The person's first (given) name. Either firstName, lastName or company must be set.

idid
mandatory
NUMBER

The ID of the person to update.

lastNamelastName
mandatory
TEXT
MAX:50

The person's last (family) name. Either firstName, lastName or company must be set.

addressesaddresses
JSON

A list of addresses (street, house number, zip, city, country).

This is a JSON array [{...},{...},...] with the following parameters:

typetype
mandatory
TEXT

The type of address. Main address, invoice address, etc. Possible values: MAIN, INVOICE, DELIVERY, OTHER.

addressaddress
TEXT

The address (street, house number, additional info). Can contain multiple lines.

citycity
TEXT

The town / city of the address.

countrycountry
TEXT

The country of the address. Possible values: AFG, ALA, ALB, DZA, ASM, AND, AGO, AIA, ATG, ARG, ARM, ABW, AUS, AUT, AZE, BHS, BHR, BGD, BRB, BLR, BEL, BLZ, BEN, BMU, BTN, BOL, BES, BIH, BWA, BVT, BRA, IOT, BRN, BGR, BFA, BDI, KHM, CMR, CAN, CPV, CYM, CAF, TCD, CHL, CHN, CXR, CCK, COL, COM, COG, COK, CRI, CIV, HRV, CUB, CUW, CYP, CZE, DNK, DJI, DOM, DMA, ECU, EGY, SLV, GNQ, ERI, EST, ETH, FLK, FRO, FJI, FIN, FRA, GUF, GUY, PYF, GAB, GMB, GEO, DEU, GHA, GIB, GRC, GRL, GRD, GLP, GUM, GTM, GGY, GNB, GIN, HTI, HMD, VAT, HND, HKG, HUN, IND, IDN, IRN, IRQ, IRL, IMN, ISR, ITA, JAM, JPN, JEY, JOR, KAZ, KEN, KIR, PRK, KOR, KWT, KGZ, LAO, LVA, LBN, LSO, LBR, LBY, LIE, LTU, LUX, MAC, MKD, MDG, MWI, MYS, MDV, SOM, MLI, MLT, MHL, MTQ, MRT, MUS, MYT, MEX, FSM, MDA, MCO, MNG, MNE, MSR, MAR, MOZ, MMR, NAM, NRU, NPL, NLD, NCL, NZL, NIC, NGA, NER, NIU, NFK, MNP, NOR, OMN, PAK, PLW, PSE, PAN, PNG, PRY, PER, PHL, PCN, POL, PRT, PRI, QAT, REU, ROU, RUS, RWA, BLM, SHN, KNA, LCA, MAF, SPM, VCT, WSM, SMR, STP, SAU, SEN, SRB, SYC, SLE, SGP, SXM, SVK, SVN, SLB, ZAF, SGS, SSD, ESP, LKA, SDN, SUR, SJM, SWZ, SWE, CHE, SYR, TWN, TJK, TZA, THA, TLS, TGO, TKL, TON, TTO, TUN, TUR, TKM, TCA, TUV, UGA, UKR, ARE, GBR, USA, URY, UZB, VUT, VEN, VNM, VIR, VGB, WLF, YEM, ZMB, ZWE, ISL.

zipzip
TEXT

The postal code of the address.

bicbic
TEXT
MAX:11

The BIC (Business Identifier Code) of the person's bank.

categoryIdcategoryId
NUMBER

The ID of the category. See Person category.

contactscontacts
JSON

A list of contact information (e-mail, phone, url, etc.).

This is a JSON array [{...},{...},...] with the following parameters:

addressaddress
mandatory
TEXT

The actual contact information (e-mail address, phone number, etc.).

purposepurpose
mandatory
TEXT

The purpose (sub-type) of the contact information. Possible values: PRIVATE, WORK, RECEPTION, INVOICE.

typetype
mandatory
TEXT

The type of contact information. Possible values: EMAIL, PHONE, MOBILE, FAX, SKYPE, WEBSITE, OTHER.

customcustom
XML

Custom field values. They are stored as XML in this parameter. Example: <values><customField1>My value</customField1><customField2>["value 1","value 2"]</customField2></values>. Look up custom field variable names (e.g. "customField1") in the Custom fields API.

dateBirthdateBirth
DATE

The person's date of birth.

Format: YYYY-MM-DD. Example: 2020-01-15.

departmentdepartment
TEXT
MAX:100

The department of the person within the company.

discountPercentagediscountPercentage
NUMBER
MIN:0.0
MAX:100.0

Discount percentage for this person, which may be used for orders. This can also be set on the category for all people in that category.

ibaniban
TEXT
MAX:50

The IBAN (International Bank Account Number) of the person.

industryindustry
TEXT
MAX:100

The industry of the company or the trade/vocation of the person.

isInactiveisInactive
BOOLEAN

Mark the person as inactive. The person will be greyed out and no longer suggested. Defaults to false. Possible values: true, false.

languagelanguage
TEXT

The main language of the person. May be used for documents. Possible values: DE, EN, FR, IT.

notesnotes
HTML

Some optional notes.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

nrnr
TEXT
MAX:50

The person number (e.g. customer no.).

positionposition
TEXT
MAX:100

The position (job title) of the person within the company.

sequenceNumberIdsequenceNumberId
NUMBER

The ID of the sequence number used to generate the person number (see nr). If this is empty, the sequence number will not update when nr is set. See Sequence number.

titleIdtitleId
NUMBER

The person's title (e.g. 'Mr.', 'Mrs.', 'Dr.'). See Person title.

Endpoint

POST /api/v1/person/update.json

Delete people

Deletes one or multiple people. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/person/delete.json

Categorize people

Assigns one or multiple people to the desired category. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the entries to categorize, comma-separated.

targettarget
mandatory
NUMBER

The ID of the target category.

Endpoint

POST /api/v1/person/categorize.json

Category

The following API endpoints are for managing person categories (e.g. 'Customers', 'Vendors', 'Employees').

Read category

Returns a single category by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/person/category/read.json

Get tree of categories

Returns a tree of all categories or the tree below a parent category.

Parameters

idid
NUMBER

Optional ID of the parent category (omit to get all categories).

Endpoint

GET /api/v1/person/category/tree.json

Create category

Creates a new category. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:50

The name of the category.

discountPercentagediscountPercentage
NUMBER
MIN:0.0
MAX:100.0

Discount percentage for people in this category, which may be used for orders.

parentIdparentId
NUMBER

The ID of the parent category.

sequenceNrIdsequenceNrId
NUMBER

The ID of the sequence number used for people in this category. If empty, the sequence number of the parent category is inherited.

Endpoint

POST /api/v1/person/category/create.json

Update category

Updates an existing category. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the category to update.

namename
mandatory
TEXT
MAX:50

The name of the category.

discountPercentagediscountPercentage
NUMBER
MIN:0.0
MAX:100.0

Discount percentage for people in this category, which may be used for orders.

parentIdparentId
NUMBER

The ID of the parent category.

sequenceNrIdsequenceNrId
NUMBER

The ID of the sequence number used for people in this category. If empty, the sequence number of the parent category is inherited.

Endpoint

POST /api/v1/person/category/update.json

Delete categories

Deletes one or multiple existing category. Note that you can only delete empty categories. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/person/category/delete.json

Title

The following API endpoints are for managing titles (forms of addressing people). A title is for example 'Mr.', 'Mrs.' or 'Dr.' and also contains gender and letter salutation.

Read title

Returns a single title by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/person/title/read.json

List titles

Returns a list of all titles.

Endpoint

GET /api/v1/person/title/list.json

Create title

Creates a new title. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:100

The name of the title (i.e. the actual title).

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

gendergender
TEXT

The person's biological gender (male or female). Possible values: MALE, FEMALE.

sentencesentence
TEXT
MAX:255

The letter salutation (e.g. 'Dear Mr.', etc.). May be used in mail.

Endpoint

POST /api/v1/person/title/create.json

Update title

Updates an existing title. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the title to update.

namename
mandatory
TEXT
MAX:100

The name of the title (i.e. the actual title).

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

gendergender
TEXT

The person's biological gender (male or female). Possible values: MALE, FEMALE.

sentencesentence
TEXT
MAX:255

The letter salutation (e.g. 'Dear Mr.', etc.). May be used in mail.

Endpoint

POST /api/v1/person/title/update.json

Delete titles

Deletes one or multiple titles. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/person/title/delete.json

vCard import

The following API endpoints are for importing vCards into the People list.

Import file

Imports a vCard file. A vCard file can contain multiple contacts.

Parameters

executeexecute
BOOLEAN

Execute the import. If false, then nothing is imported and we just return a JSON with the contacts to be imported. Defaults to false. Possible values: true, false.

filefile
FILE

File to import. Only vCard (.vcf) files are supported.

indexesindexes
TEXT

Index numbers of contacts to import. All other contacts are ignored. You can get the indexes of contacts from the JSON response when execute is not set. Omit this parameter to import all contacts.

Endpoint

POST /api/v1/person/vcard/import.json

Read settings

Reads the vCard import settings.

Endpoint

GET /api/v1/person/vcard/settings_read.json

Update settings

Updates the vCard import settings.

Parameters

categoryIdcategoryId
NUMBER

Set the category for imported new contacts. Only used if categoryType is set to OVERWRITE, ignored otherwise.

categoryTypecategoryType
TEXT

What to do with categories. IMPORT = Import categories from file. OVERWRITE = Set the category via categoryId. IGNORE = Don't set or import categories, leave them be. Possible values: IMPORT, OVERWRITE, IGNORE.

isAddisAdd
BOOLEAN

Whether to add new contacts. Defaults to false. Possible values: true, false.

isComplementisComplement
BOOLEAN

Whether to complement existing contacts with information from the imported contacts. Defaults to false. Possible values: true, false.

Endpoint

POST /api/v1/person/vcard/settings_update.json

Report

The following API endpoint is for reading the report tree. This tree/list contains all of the instanced report sets with child elements and direct elements. A report set is a collection of report elements which are grouped together and form one document, see Report set. A report element is the actual report, for example the balance sheet or profit and loss statement, see Report element.

Get tree of reports

Returns a tree of all instanced reports containing sets and elements.

Endpoint

GET /api/v1/report/tree.json

Element

The following API endpoints are for managing report elements. Report elements are instances of report types like the balance sheet or the profit and loss statement. This means you can have multiple balance sheets with different configurations. Report elements can also be grouped together in sets, see Report set.

Read element

Returns a single element by ID. This is the element configuration and does not contain any report data.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/report/element/read.json

Create element

Creates a new element. Returns either a success or multiple error messages (for each issue).

Parameters

typetype
mandatory
TEXT

The type of the report. Possible values: BALANCE, PLS, STAGGERED, CHART_OF_ACCOUNTS, OPEN_DEBTORS, OPEN_CREDITORS, SALES_TAX, TARGET, RESULT_BY_ARTICLE_PER_PERSON, EXPENSE_BY_PERSON, REVENUE_BY_PERSON, RESULT_BY_ARTICLE, STATEMENTS, BALANCE_LIST, KEY_FIGURES, EXPENSE_BY_PERSON_CHART, REVENUE_BY_PERSON_CHART, RESULT_BY_ARTICLE_CHART, BALANCE_PROG_CHART, BALANCE_SHARE_CHART, CASH_FLOW_CHART, TEXT_IMAGE.

configconfig
JSON

Configuration options specific for each report type. We cannot document all possible configuration options here, but you can check the parameters that CashCtrl sends when saving a report config in the browser's developer console (Network tab).

This is a JSON object {...}.

filefile
FILE

File associated with the report element (e.g. image for the 'Text & Image' report).

isHideTitleisHideTitle
BOOLEAN

Hide title of the report. Defaults to false. Possible values: true, false.

isPageBreakisPageBreak
BOOLEAN

Page break before the report (for PDF). Defaults to false. Possible values: true, false.

namename
TEXT
MAX:255

Name / title of the report.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

setIdsetId
NUMBER

Optional ID of a report set, to include this element in the set.

texttext
HTML

Text / description for the report.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

Endpoint

POST /api/v1/report/element/create.json

Update element

Updates an existing element. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the element to update.

typetype
mandatory
TEXT

The type of the report. Possible values: BALANCE, PLS, STAGGERED, CHART_OF_ACCOUNTS, OPEN_DEBTORS, OPEN_CREDITORS, SALES_TAX, TARGET, RESULT_BY_ARTICLE_PER_PERSON, EXPENSE_BY_PERSON, REVENUE_BY_PERSON, RESULT_BY_ARTICLE, STATEMENTS, BALANCE_LIST, KEY_FIGURES, EXPENSE_BY_PERSON_CHART, REVENUE_BY_PERSON_CHART, RESULT_BY_ARTICLE_CHART, BALANCE_PROG_CHART, BALANCE_SHARE_CHART, CASH_FLOW_CHART, TEXT_IMAGE.

configconfig
JSON

Configuration options specific for each report type. We cannot document all possible configuration options here, but you can check the parameters that CashCtrl sends when saving a report config in the browser's developer console (Network tab).

This is a JSON object {...}.

filefile
FILE

File associated with the report element (e.g. image for the 'Text & Image' report).

isHideTitleisHideTitle
BOOLEAN

Hide title of the report. Defaults to false. Possible values: true, false.

isPageBreakisPageBreak
BOOLEAN

Page break before the report (for PDF). Defaults to false. Possible values: true, false.

namename
TEXT
MAX:255

Name / title of the report.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

setIdsetId
NUMBER

Optional ID of a report set, to include this element in the set.

texttext
HTML

Text / description for the report.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

Endpoint

POST /api/v1/report/element/update.json

Delete elements

Deletes one or multiple elements. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/report/element/delete.json

Reorder elements

Changes the order of one or multiple elements. This is the order in which the report elements are displayed in the Report tree. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the entries to reorder, comma-separated.

targettarget
mandatory
NUMBER

The ID of the target entry. The entries (see ids) will be ordered before or after (see before) this entry.

beforebefore
BOOLEAN

Reorder before the target entry, after otherwise. Defaults to true. Possible values: true, false.

Endpoint

POST /api/v1/report/element/reorder.json

Read data

Returns the data of a single element by ID for the given time period.

Parameters

elementIdelementId
mandatory
NUMBER

The ID of the element.

endDateendDate
DATE

The end date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

fiscalPeriodfiscalPeriod
NUMBER

The ID of the fiscal period. This overrides the startDate and endDate parameter, as these are derived from the fiscal period. See Fiscal period.

languagelanguage
TEXT

The language of the report.

sortsort
TEXT

The column to sort the list by.

startDatestartDate
DATE

The start date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

Endpoint

GET /api/v1/report/element/data.json

Read meta data

Returns the meta data (title, text, etc.) of a single element by ID for the given time period.

Parameters

elementIdelementId
mandatory
NUMBER

The ID of the element.

endDateendDate
DATE

The end date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

fiscalPeriodfiscalPeriod
NUMBER

The ID of the fiscal period. This overrides the startDate and endDate parameter, as these are derived from the fiscal period. See Fiscal period.

languagelanguage
TEXT

The language of the report.

sortsort
TEXT

The column to sort the list by.

startDatestartDate
DATE

The start date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

Endpoint

GET /api/v1/report/element/meta.json

Download PDF

Downloads the PDF file for a single element by ID and time period.

Parameters

elementIdelementId
mandatory
NUMBER

The ID of the element.

endDateendDate
DATE

The end date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

fiscalPeriodfiscalPeriod
NUMBER

The ID of the fiscal period. This overrides the startDate and endDate parameter, as these are derived from the fiscal period. See Fiscal period.

languagelanguage
TEXT

The language of the report.

sortsort
TEXT

The column to sort the list by.

startDatestartDate
DATE

The start date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

Endpoint

GET /api/v1/report/element/download.pdf

Download CSV

Downloads the CSV file for a single element by ID and time period.

Parameters

elementIdelementId
mandatory
NUMBER

The ID of the element.

endDateendDate
DATE

The end date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

fiscalPeriodfiscalPeriod
NUMBER

The ID of the fiscal period. This overrides the startDate and endDate parameter, as these are derived from the fiscal period. See Fiscal period.

languagelanguage
TEXT

The language of the report.

sortsort
TEXT

The column to sort the list by.

startDatestartDate
DATE

The start date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

Endpoint

GET /api/v1/report/element/download.csv

Download Excel

Downloads the Excel file for a single element by ID and time period.

Parameters

elementIdelementId
mandatory
NUMBER

The ID of the element.

endDateendDate
DATE

The end date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

fiscalPeriodfiscalPeriod
NUMBER

The ID of the fiscal period. This overrides the startDate and endDate parameter, as these are derived from the fiscal period. See Fiscal period.

languagelanguage
TEXT

The language of the report.

sortsort
TEXT

The column to sort the list by.

startDatestartDate
DATE

The start date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

Endpoint

GET /api/v1/report/element/download.xlsx

Set

The following API endpoints are for managing report sets. Report sets can contain multiple report elements, which are the actual reports (see Report element). So a report set is basically like a group or a folder. A set of reports can be viewed or downloaded as one document in PDF or other formats.

Read set

Returns a single set by ID. This is the set configuration and also returns all the report elements contained in this set (their configuration, no data).

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/report/set/read.json

Create set

Creates a new set. Returns either a success or multiple error messages (for each issue).

Parameters

namename
mandatory
TEXT
MAX:255

Name / title of the report set.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

configconfig
JSON

Configuration options.

This is a JSON object {...} with the following parameters:

isDisplayFooterisDisplayFooter
BOOLEAN

Display the footer on the PDF? Defaults to true. Possible values: true, false.

isDisplayHeaderisDisplayHeader
BOOLEAN

Display the header on the PDF? Defaults to true. Possible values: true, false.

isDisplayLogoisDisplayLogo
BOOLEAN

Display the logo? Defaults to true. Possible values: true, false.

isDisplayPeriodInTitleisDisplayPeriodInTitle
BOOLEAN

Display the time period in the title? Defaults to true. Possible values: true, false.

isDisplayTitleisDisplayTitle
BOOLEAN

Display the title? Defaults to true. Possible values: true, false.

logoHeightlogoHeight
NUMBER

The height of the logo in centimeters, as displayed on the report document (PDF).

pageSizepageSize
TEXT

The page size of the report document (PDF). Defaults to A4. Possible values: A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, LEGAL, LETTER, A4R.

texttext
HTML

Text / description for the report set.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

Endpoint

POST /api/v1/report/set/create.json

Update set

Updates an existing set. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the set to update.

namename
mandatory
TEXT
MAX:255

Name / title of the report set.

This can contain localized text. To add values in multiple languages, use the XML format like this: <values><de>German text</de><en>English text</en></values>

configconfig
JSON

Configuration options.

This is a JSON object {...} with the following parameters:

isDisplayFooterisDisplayFooter
BOOLEAN

Display the footer on the PDF? Defaults to true. Possible values: true, false.

isDisplayHeaderisDisplayHeader
BOOLEAN

Display the header on the PDF? Defaults to true. Possible values: true, false.

isDisplayLogoisDisplayLogo
BOOLEAN

Display the logo? Defaults to true. Possible values: true, false.

isDisplayPeriodInTitleisDisplayPeriodInTitle
BOOLEAN

Display the time period in the title? Defaults to true. Possible values: true, false.

isDisplayTitleisDisplayTitle
BOOLEAN

Display the title? Defaults to true. Possible values: true, false.

logoHeightlogoHeight
NUMBER

The height of the logo in centimeters, as displayed on the report document (PDF).

pageSizepageSize
TEXT

The page size of the report document (PDF). Defaults to A4. Possible values: A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, LEGAL, LETTER, A4R.

texttext
HTML

Text / description for the report set.

This can contain limited HTML for styling. Allowed tags: a, p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, b, i, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em. Allowed inline CSS rules: background, background-color, color, font, font-size, font-weight, font-style, text-align, text-indent, text-decoration.

Endpoint

POST /api/v1/report/set/update.json

Delete sets

Deletes one or multiple sets. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/report/set/delete.json

Reorder sets

Changes the order of one or multiple sets. This is the order in which the report sets are displayed in the Report tree. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the entries to reorder, comma-separated.

targettarget
mandatory
NUMBER

The ID of the target entry. The entries (see ids) will be ordered before or after (see before) this entry.

beforebefore
BOOLEAN

Reorder before the target entry, after otherwise. Defaults to true. Possible values: true, false.

Endpoint

POST /api/v1/report/set/reorder.json

Read meta data

Returns the meta data (title, text, etc.) of a single set by ID for the given time period.

Parameters

setIdsetId
mandatory
NUMBER

The ID of the set.

endDateendDate
DATE

The end date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

fiscalPeriodfiscalPeriod
NUMBER

The ID of the fiscal period. This overrides the startDate and endDate parameter, as these are derived from the fiscal period. See Fiscal period.

languagelanguage
TEXT

The language of the report.

sortsort
TEXT

The column to sort the list by.

startDatestartDate
DATE

The start date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

Endpoint

GET /api/v1/report/set/meta.json

Download PDF

Downloads the PDF file for a report set by ID and time period.

Parameters

setIdsetId
mandatory
NUMBER

The ID of the set.

endDateendDate
DATE

The end date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

fiscalPeriodfiscalPeriod
NUMBER

The ID of the fiscal period. This overrides the startDate and endDate parameter, as these are derived from the fiscal period. See Fiscal period.

languagelanguage
TEXT

The language of the report.

sortsort
TEXT

The column to sort the list by.

startDatestartDate
DATE

The start date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

Endpoint

GET /api/v1/report/set/download.pdf

Download CSV

Downloads a ZIP file containing the CSV files for a report set by ID and time period.

Parameters

setIdsetId
mandatory
NUMBER

The ID of the set.

endDateendDate
DATE

The end date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

fiscalPeriodfiscalPeriod
NUMBER

The ID of the fiscal period. This overrides the startDate and endDate parameter, as these are derived from the fiscal period. See Fiscal period.

languagelanguage
TEXT

The language of the report.

sortsort
TEXT

The column to sort the list by.

startDatestartDate
DATE

The start date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

Endpoint

GET /api/v1/report/set/download.csv

Download Excel

Downloads the Excel file for a report set by ID and time period. Each report element is a worksheet within the Excel file.

Parameters

setIdsetId
mandatory
NUMBER

The ID of the set.

endDateendDate
DATE

The end date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

fiscalPeriodfiscalPeriod
NUMBER

The ID of the fiscal period. This overrides the startDate and endDate parameter, as these are derived from the fiscal period. See Fiscal period.

languagelanguage
TEXT

The language of the report.

sortsort
TEXT

The column to sort the list by.

startDatestartDate
DATE

The start date of the report period.

Format: YYYY-MM-DD. Example: 2020-01-15.

Endpoint

GET /api/v1/report/set/download.xlsx

Download annual report

Downloads the PDF file for the annual report (balance sheet and profit and loss statement by default).

Parameters

fiscalPeriodIdfiscalPeriodId
NUMBER

The ID of the fiscal period. Leave empty to use the current fiscal period. See Switch fiscal period.

Endpoint

GET /api/v1/report/set/download_annualreport.pdf