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 setting the logo from an uploaded file. To upload the file first, see Upload one or multiple files below.

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 "logoFileId=201"

Import vCards

Imports a vCard (.vcf) file into the list of people. For this to work, you must first upload a file. See Upload one or multiple files below.

Step 1: Create import session

curl https://myorg.cashctrl.com/api/v1/person/import/create.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "fileId=314"

Step 2: Execute the import

Use the insertId information from the response of the first step as the ID here.

curl https://myorg.cashctrl.com/api/v1/person/import/execute.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "id=21"

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:

Upload one or multiple files

There are three steps to uploading files: Prepare Put Persist. Let's say we upload two files: report.pdf and image.png.

Step 1: Prepare

We first inform CashCtrl of the file names and mime types of the files we are going to upload:

curl https://myorg.cashctrl.com/api/v1/file/prepare.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "files=[{\"name\":\"report.pdf\",\"mimeType\":\"application/pdf\"},{\"name\":\"image.png\",\"mimeType\":\"image/png\"}}]"

This will return a list of file IDs and pre-authenticated write URLs where you can upload the files using the HTTP PUT method. Example response:

{
    "success": true,
    "data": [
        {
            "fileId": 24,
            "writeUrl": "https://objectstorage.eu-zurich-1.oraclecloud.com/p/pCmCfv9GwIxISZ9pGusMqiG9vG_TqAmU8QXgUhZ6C-W6j1CXYceSoqPQSQVXr0Fx/n/zry79ircxznv/b/dev/o/rihligXi/file/hh/au/report.pdf"
        },
        {
            "fileId": 25,
            "writeUrl": "https://objectstorage.eu-zurich-1.oraclecloud.com/p/1gi7PDkRphcQRe7bYE4WgM84DJ3uS-v-iN5ldGqgD2MJswZSTqfj1xE5T7F8PBtX/n/zry79ircxznv/b/dev/o/rihligXi/file/jc/zh/image.png"
        }
    ]
}

Step 2: Put

In the second step, we actually upload the files via HTTP PUT:

curl https://objectstorage.eu-zurich-1.oraclecloud.com/p/pCmCfv9GwIxISZ9pGusMqiG9vG_TqAmU8QXgUhZ6C-W6j1CXYceSoqPQSQVXr0Fx/n/zry79ircxznv/b/dev/o/rihligXi/file/hh/au/report.pdf --upload-file report.pdf

curl https://objectstorage.eu-zurich-1.oraclecloud.com/p/1gi7PDkRphcQRe7bYE4WgM84DJ3uS-v-iN5ldGqgD2MJswZSTqfj1xE5T7F8PBtX/n/zry79ircxznv/b/dev/o/rihligXi/file/jc/zh/image.png --upload-file image.png

The files have now been uploaded and are marked temporary. They will be deleted within 4 hours unless persisted with the final step. This final step depends on what you want to do. Note that any of these steps persists the temporary files.

Step 3.a) Persist directly

You just want to save the files and see them in the CashCtrl file manager:

curl https://myorg.cashctrl.com/api/v1/file/persist.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "ids=24,25"

Step 3.b) Persist with additional information

You want to add a description, notes, custom fields, etc. to each file, instead of just persisting the files:

curl https://myorg.cashctrl.com/api/v1/file/create.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "id=24" -F "name=report.pdf" -F "description=API generated report"

curl https://myorg.cashctrl.com/api/v1/file/create.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "id=25" -F "name=image.png" "notes=Some API generated notes"

Step 3.c) Attach to an entry

You want to attach the files to a Person entry (id being the Person ID):

curl https://myorg.cashctrl.com/api/v1/person/update_attachments.json -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -X POST -F "id=47" "fileIds=24,25"

Step 3.d) Use the file as a logo, or for importing something

You want to set the file as the logo of your organization or a location. See Add new location example above. You basically set a parameter named logoFileId (or similar) in the corresponding endpoint. Or you want to Import a vCard file for importing contacts.

Download a file

Downloads a file that you have previously uploaded (see previous example). Please be aware that the response may redirect to the actual file URL (a pre-authenticated cloud storage URL), so be sure to handle redirects. Using cURL, we can simply add the -L parameter.

curl https://myorg.cashctrl.com/api/v1/file/get?id=24 -u zjdqcZjsfSYyM4EPG19tHss6X5NIHf0b: -L
 

Account

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

Account

Read account

Returns a single account by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

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

List accounts

Returns a list of all accounts.

Parameters

categoryIdcategoryId
optional
NUMBER

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
BOOLEAN

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

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

GET /api/v1/account/list.json
Account

Export to Excel

Returns an Excel file of the account list.

Parameters

categoryIdcategoryId
optional
NUMBER

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

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
BOOLEAN

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

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

GET /api/v1/account/list.xlsx
Account

Export to CSV

Returns a CSV file of the account list.

Parameters

categoryIdcategoryId
optional
NUMBER

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

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
BOOLEAN

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

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

GET /api/v1/account/list.csv
Account

Export to PDF

Returns a PDF file of the account list.

Parameters

categoryIdcategoryId
optional
NUMBER

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

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
BOOLEAN

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

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

GET /api/v1/account/list.pdf
Account

Get account balance

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

Parameters

idid
mandatory
NUMBER

The ID of the account.

datedate
optional
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
Account

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.

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>

numbernumber
mandatory
TEXT
MAX:20

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

allocationsallocations
optional
JSON

Allocations to cost centers, if this account is either an expense or revenue account.

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

shareshare
mandatory
NUMBER

Allocation share. This can be a percentage or just a share number.

toCostCenterIdtoCostCenterId
mandatory
NUMBER

ID of cost center to allocate to. See Cost center.

currencyIdcurrencyId
optional
NUMBER

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

customcustom
optional
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
optional
BOOLEAN

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

notesnotes
optional
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
optional
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
optional
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
optional
NUMBER

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

Endpoint

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

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.

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>

numbernumber
mandatory
TEXT
MAX:20

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

allocationsallocations
optional
JSON

Allocations to cost centers, if this account is either an expense or revenue account.

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

shareshare
mandatory
NUMBER

Allocation share. This can be a percentage or just a share number.

toCostCenterIdtoCostCenterId
mandatory
NUMBER

ID of cost center to allocate to. See Cost center.

currencyIdcurrencyId
optional
NUMBER

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

customcustom
optional
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
optional
BOOLEAN

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

notesnotes
optional
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
optional
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
optional
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
optional
NUMBER

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

Endpoint

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

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
Account

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
Account

Update attachments

Updates the file attachments of an account. Use the File API to upload a file and then use the file ID here. Returns either a success or error message.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

fileIdsfileIds
optional
CSV

A list of file IDs, comma-separated. Leave empty to remove all attachments. Use the File API to upload a file and then use the file ID here.

Endpoint

POST /api/v1/account/update_attachments.json
Account  

Category

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

Account Category

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
Account Category

List categories

Returns a list of all categories.

Endpoint

GET /api/v1/account/category/list.json
Account Category

Get tree of categories

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

Parameters

idid
optional
NUMBER

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

Endpoint

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

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
optional
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
optional
NUMBER

The ID of the parent category.

Endpoint

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

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
optional
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
optional
NUMBER

The ID of the parent category.

Endpoint

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

Delete categories

Deletes one or multiple existing categories. 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
Account  

Cost center

The following API endpoints are for managing cost centers.

Account Cost center

Read cost center

Returns a single cost center by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/account/costcenter/read.json
Account Cost center

List cost centers

Returns a list of all cost centers.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter the list by. See Cost center category.

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

GET /api/v1/account/costcenter/list.json
Account Cost center

Export to Excel

Returns an Excel file of the cost center list.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter the list by. See Cost center category.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

GET /api/v1/account/costcenter/list.xlsx
Account Cost center

Export to CSV

Returns a CSV file of the cost center list.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter the list by. See Cost center category.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

GET /api/v1/account/costcenter/list.csv
Account Cost center

Export to PDF

Returns a PDF file of the cost center list.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter the list by. See Cost center category.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

GET /api/v1/account/costcenter/list.pdf
Account Cost center

Get cost center balance

Returns the balance of a single cost center for the given date.

Parameters

idid
mandatory
NUMBER

The ID of the cost center.

datedate
optional
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/costcenter/balance
Account Cost center

Create cost center

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

Parameters

namename
mandatory
TEXT
MAX:100

The name of the cost center.

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>

numbernumber
mandatory
TEXT
MAX:20

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

categoryIdcategoryId
optional
NUMBER

The ID of the category. See Cost center category.

isInactiveisInactive
optional
BOOLEAN

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

notesnotes
optional
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
optional
NUMBER

The target maximum balance (aka budget) you hope this cost center 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
optional
NUMBER

The target minimum balance you hope this cost center / cost unit 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.

Endpoint

POST /api/v1/account/costcenter/create.json
Account Cost center

Update cost center

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

Parameters

idid
mandatory
NUMBER

The ID of the cost center to update.

namename
mandatory
TEXT
MAX:100

The name of the cost center.

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>

numbernumber
mandatory
TEXT
MAX:20

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

categoryIdcategoryId
optional
NUMBER

The ID of the category. See Cost center category.

isInactiveisInactive
optional
BOOLEAN

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

notesnotes
optional
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
optional
NUMBER

The target maximum balance (aka budget) you hope this cost center 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
optional
NUMBER

The target minimum balance you hope this cost center / cost unit 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.

Endpoint

POST /api/v1/account/costcenter/update.json
Account Cost center

Delete cost centers

Deletes one or multiple cost centers. Only unused cost centers can be deleted (cost centers 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/costcenter/delete.json
Account Cost center

Categorize cost centers

Assigns one or multiple cost centers 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/costcenter/categorize.json
Account Cost center

Update attachments

Updates the file attachments of a cost center. Use the File API to upload a file and then use the file ID here. Returns either a success or error message.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

fileIdsfileIds
optional
CSV

A list of file IDs, comma-separated. Leave empty to remove all attachments. Use the File API to upload a file and then use the file ID here.

Endpoint

POST /api/v1/account/costcenter/update_attachments.json
Account  

Cost center category

The following API endpoints are for managing cost center categories.

Account Cost center category

Read category

Returns a single category by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/account/costcenter/category/read.json
Account Cost center category

List categories

Returns a list of all categories.

Endpoint

GET /api/v1/account/costcenter/category/list.json
Account Cost center category

Get tree of categories

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

Parameters

idid
optional
NUMBER

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

Endpoint

GET /api/v1/account/costcenter/category/tree.json
Account Cost center category

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 cost center category.

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>

numbernumber
optional
TEXT
MAX:20

An optional number for the cost center category. Must be numeric. This is used for sorting the categories.

parentIdparentId
optional
NUMBER

The ID of the parent category.

Endpoint

POST /api/v1/account/costcenter/category/create.json
Account Cost center category

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 cost center category.

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>

numbernumber
optional
TEXT
MAX:20

An optional number for the cost center category. Must be numeric. This is used for sorting the categories.

parentIdparentId
optional
NUMBER

The ID of the parent category.

Endpoint

POST /api/v1/account/costcenter/category/update.json
Account Cost center category

Delete categories

Deletes one or multiple existing categories. 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/costcenter/category/delete.json
Common  

Currency

The following API endpoints are for managing currencies.

Common Currency

Read currency

Returns a single currency by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/currency/read.json
Common Currency

List currencies

Returns a list of all currencies.

Endpoint

GET /api/v1/currency/list.json
Common Currency

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
optional
TEXT
MAX:50

An optional description of the currency.

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>

isDefaultisDefault
optional
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
optional
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
Common Currency

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
optional
TEXT
MAX:50

An optional description of the currency.

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>

isDefaultisDefault
optional
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
optional
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
Common Currency

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
Common Currency

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
optional
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
Common  

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).

Common Custom field

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
Common Custom field

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, INVENTORY_ARTICLE, INVENTORY_ASSET, ORDER, PERSON, FILE.

Endpoint

GET /api/v1/customfield/list.json
Common Custom field

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, ACCOUNT, PERSON.

namename
mandatory
TEXT
MAX:100

The name of the custom field.

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>

typetype
mandatory
TEXT

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

descriptiondescription
optional
TEXT
MAX:240

An optional description of the custom field.

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>

groupIdgroupId
optional
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
optional
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
optional
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
optional
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
Common Custom field

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, ACCOUNT, PERSON.

idid
mandatory
NUMBER

The ID of the custom field to update.

namename
mandatory
TEXT
MAX:100

The name of the custom field.

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>

typetype
mandatory
TEXT

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

descriptiondescription
optional
TEXT
MAX:240

An optional description of the custom field.

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>

groupIdgroupId
optional
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
optional
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
optional
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
optional
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
Common Custom field

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
Common Custom field

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
optional
BOOLEAN

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

Endpoint

POST /api/v1/customfield/reorder.json
Common Custom field

Get custom field types

Returns a list of custom field types, with type and i18nKey.

Endpoint

GET /api/v1/customfield/types.json
Common  

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.

Common Custom field group

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
Common Custom field group

List custom field groups

Returns a list of custom field groups.

Parameters

typetype
mandatory
TEXT

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

Endpoint

GET /api/v1/customfield/group/list.json
Common Custom field group

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.

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>

typetype
mandatory
TEXT

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

Endpoint

POST /api/v1/customfield/group/create.json
Common Custom field group

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.

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>

typetype
mandatory
TEXT

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

Endpoint

POST /api/v1/customfield/group/update.json
Common Custom field group

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
Common Custom field group

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
optional
BOOLEAN

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

Endpoint

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

Rounding

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

Common Rounding

Read rounding

Returns a single rounding by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/rounding/read.json
Common Rounding

List roundings

Returns a list of all roundings.

Endpoint

GET /api/v1/rounding/list.json
Common Rounding

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
optional
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
Common Rounding

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
optional
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
Common Rounding

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
Common  

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.).

Common Sequence number

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_ARTICLE, INVENTORY_ASSET, JOURNAL, ORDER, PERSON.

categoryIdcategoryId
optional
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).

datedate
optional
DATE

An optional date, which will influence the next sequence number to be generated.

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

Endpoint

GET /api/v1/sequencenumber/read.json
Common Sequence number

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_ARTICLE, INVENTORY_ASSET, JOURNAL, ORDER, PERSON.

categoryIdcategoryId
optional
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).

datedate
optional
DATE

An optional date, which will influence the next sequence number to be generated.

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

Endpoint

GET /api/v1/sequencenumber/get
Common Sequence number

List sequence numbers

Returns a list of all sequence numbers.

Endpoint

GET /api/v1/sequencenumber/list.json
Common Sequence number

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
optional
NUMBER

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

currentInfiniteNumbercurrentInfiniteNumber
optional
NUMBER

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

currentMonthlyNumbercurrentMonthlyNumber
optional
NUMBER

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

currentYearlyNumbercurrentYearlyNumber
optional
NUMBER

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

dailyNumberDigitsdailyNumberDigits
optional
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
optional
NUMBER

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

infiniteNumberDigitsinfiniteNumberDigits
optional
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.

isSkipExistingisSkipExisting
optional
BOOLEAN

Automatically skip existing sequence numbers? Example: If the next number is 500, but 500 already exists, it will increment the sequence number until a free one is found (max. 100 tries). Possible values: true, false.

monthDigitsmonthDigits
optional
NUMBER

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

monthlyNumberDigitsmonthlyNumberDigits
optional
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
optional
NUMBER

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

yearlyNumberDigitsyearlyNumberDigits
optional
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
Common Sequence number

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
optional
NUMBER

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

currentInfiniteNumbercurrentInfiniteNumber
optional
NUMBER

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

currentMonthlyNumbercurrentMonthlyNumber
optional
NUMBER

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

currentYearlyNumbercurrentYearlyNumber
optional
NUMBER

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

dailyNumberDigitsdailyNumberDigits
optional
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
optional
NUMBER

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

infiniteNumberDigitsinfiniteNumberDigits
optional
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.

isSkipExistingisSkipExisting
optional
BOOLEAN

Automatically skip existing sequence numbers? Example: If the next number is 500, but 500 already exists, it will increment the sequence number until a free one is found (max. 100 tries). Possible values: true, false.

monthDigitsmonthDigits
optional
NUMBER

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

monthlyNumberDigitsmonthlyNumberDigits
optional
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
optional
NUMBER

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

yearlyNumberDigitsyearlyNumberDigits
optional
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
Common Sequence number

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
Common  

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.

Common Tax rate

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
Common Tax rate

List tax rates

Returns a list of all tax rates.

Endpoint

GET /api/v1/tax/list.json
Common Tax rate

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:50

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
optional
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
optional
TEXT
MAX:50

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
optional
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
optional
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
Common Tax rate

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:50

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
optional
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
optional
TEXT
MAX:50

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
optional
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
optional
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
Common Tax rate

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
Common  

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).

Common Text template

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
Common Text template

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, ORDER_ITEM.

Endpoint

GET /api/v1/text/list.json
Common Text template

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, ORDER_ITEM.

isDefaultisDefault
optional
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
optional
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
Common Text template

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, ORDER_ITEM.

isDefaultisDefault
optional
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
optional
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
Common Text template

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
 

File

The following API endpoints are for managing files. To upload a new file, you use the Prepare files endpoint instead of the Create file endpoint. See Examples for a tutorial on how to upload a file.

File

Get file contents

Returns the contents (binary) of a single file by ID. Note that this will redirect to the actual file URL, as the CashCtrl main server does not deliver files. Be sure to handle redirects when using this endpoint. See example.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/file/get
File

Read file metadata

Returns the metadata of a single file by ID. Does not contain the file binary.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/file/read.json
File

List files

Returns a list of files.

Parameters

archivedarchived
optional
BOOLEAN

Get archived files (only active files otherwise). Defaults to false. Possible values: true, false.

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

mimeTypesmimeTypes
optional
CSV

Filter the file list by these mime types (comma-separated). For example, use image/* to filter by images only.

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

withoutSubwithoutSub
optional
BOOLEAN

Flag to exclude files in sub-categories. Defaults to false. Possible values: true, false.

Endpoint

GET /api/v1/file/list.json
File

Export to Excel

Returns an Excel file of the files list.

Parameters

archivedarchived
optional
BOOLEAN

Get archived files (only active files otherwise). Defaults to false. Possible values: true, false.

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

mimeTypesmimeTypes
optional
CSV

Filter the file list by these mime types (comma-separated). For example, use image/* to filter by images only.

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

withoutSubwithoutSub
optional
BOOLEAN

Flag to exclude files in sub-categories. Defaults to false. Possible values: true, false.

Endpoint

GET /api/v1/file/list.xlsx
File

Export to CSV

Returns a CSV file of the files list.

Parameters

archivedarchived
optional
BOOLEAN

Get archived files (only active files otherwise). Defaults to false. Possible values: true, false.

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

mimeTypesmimeTypes
optional
CSV

Filter the file list by these mime types (comma-separated). For example, use image/* to filter by images only.

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

withoutSubwithoutSub
optional
BOOLEAN

Flag to exclude files in sub-categories. Defaults to false. Possible values: true, false.

Endpoint

GET /api/v1/file/list.csv
File

Export to PDF

Returns a PDF file of the files list.

Parameters

archivedarchived
optional
BOOLEAN

Get archived files (only active files otherwise). Defaults to false. Possible values: true, false.

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

mimeTypesmimeTypes
optional
CSV

Filter the file list by these mime types (comma-separated). For example, use image/* to filter by images only.

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

withoutSubwithoutSub
optional
BOOLEAN

Flag to exclude files in sub-categories. Defaults to false. Possible values: true, false.

Endpoint

GET /api/v1/file/list.pdf
File

Prepare files

Prepares one or multiple files for uploading. This is the starting point for uploading files to CashCtrl. In this step, you only provide file metadata, not the actual file. Returns a list of file IDs and write URLs. Use the write URL to upload the file binary (using the PUT method). See the Examples for a tutorial on how to upload a file (prepare put persist).

Parameters

filesfiles
optional
JSON

The files to prepare.

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

mimeTypemimeType
mandatory
TEXT

The mime type (content type) of the file. E.g. "application/pdf" for PDFs.

namename
mandatory
TEXT

The file name. Must be a valid file name, but doesn't have to be unique.

categoryIdcategoryId
optional
NUMBER

The ID of the category to add the file in.

sizesize
optional
NUMBER

The size of the file. This helps to determine early if the storage quota is exceeded or not. However, the actual file size will be determined later upon persisting the file.

Endpoint

POST /api/v1/file/prepare.json
File

Persist files

Persists one or multiple temporary files that have been prepared and uploaded. See Prepare files endpoint.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/file/persist.json
File

Create file

Creates a new file. This endpoint cannot be used to upload a new file. See Prepare files endpoint. This endpoint makes an uploaded file permanent. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
TEXT

The ID of the uploaded temporary file. See Prepare files endpoint.

namename
mandatory
TEXT
MAX:255

The file name.

categoryIdcategoryId
optional
NUMBER

The ID of the category. See File category.

customcustom
optional
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
optional
TEXT
MAX:240

A description for the file.

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>

notesnotes
optional
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.

Endpoint

POST /api/v1/file/create.json
File

Update file

Updates an existing file (only metadata, not binary). Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the file to update.

namename
mandatory
TEXT
MAX:255

The file name.

categoryIdcategoryId
optional
NUMBER

The ID of the category. See File category.

customcustom
optional
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
optional
TEXT
MAX:240

A description for the file.

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>

notesnotes
optional
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.

replaceWithreplaceWith
optional
NUMBER

Optionally replace the file binary (contents) with the binary from another file. Set the file ID here. That file must be a temporary file (not persisted yet). See Prepare files endpoint.

Endpoint

POST /api/v1/file/update.json
File

Delete files

Deletes one or multiple files. This first archives the files (moves them to the recycle bin), unless force is set. Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

forceforce
optional
BOOLEAN

Force permanent deletion of file (do not archive first). Possible values: true, false.

Endpoint

POST /api/v1/file/delete.json
File

Categorize files

Assigns one or multiple files 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/file/categorize.json
File

Empty archive

Deletes all files that have been archived (moved to the recycle bin). Returns either a success or error message.

Endpoint

POST /api/v1/file/empty_archive.json
File

Restore files

Restores one or multiple files that have been archived (moved to recycle bin). Returns either a success or error message.

Parameters

idsids
mandatory
CSV

The IDs of the selected entries, comma-separated.

Endpoint

POST /api/v1/file/restore.json
File  

File category

The following API endpoints are for managing file categories.

File File category

Read category

Returns a single category by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/file/category/read.json
File File category

List categories

Returns a list of all categories.

Endpoint

GET /api/v1/file/category/list.json
File File category

Get tree of categories

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

Parameters

idid
optional
NUMBER

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

Endpoint

GET /api/v1/file/category/tree.json
File File category

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.

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>

parentIdparentId
optional
NUMBER

The ID of the parent category.

Endpoint

POST /api/v1/file/category/create.json
File File category

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.

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>

parentIdparentId
optional
NUMBER

The ID of the parent category.

Endpoint

POST /api/v1/file/category/update.json
File File category

Delete categories

Deletes one or multiple existing categories. 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/file/category/delete.json
Inventory  

Article

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

Inventory Article

Read article

Returns a single article by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/inventory/article/read.json
Inventory Article

List articles

Returns a list of articles.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyRestockonlyRestock
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

Flag to include only articles with images. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/article/list.json
Inventory Article

Export to Excel

Returns an Excel file of the entries list.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyRestockonlyRestock
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

Flag to include only articles with images. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/article/list.xlsx
Inventory Article

Export to CSV

Returns a CSV file of the entries list.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyRestockonlyRestock
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

Flag to include only articles with images. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/article/list.csv
Inventory Article

Export to PDF

Returns a PDF file of the entries list.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyRestockonlyRestock
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

Flag to include only articles with images. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/inventory/article/list.pdf
Inventory Article

Create article

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

Parameters

namename
mandatory
TEXT
MAX:240

The name of the article.

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>

binLocationbinLocation
optional
TEXT

The place within the building (e.g. A15, B04, C11, etc.) to locate the article. See locationId. isStockArticle must be true, ignored otherwise.

categoryIdcategoryId
optional
NUMBER

The ID of the category. See Article category.

currencyIdcurrencyId
optional
NUMBER

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

customcustom
optional
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
optional
TEXT

A description of the article.

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
optional
BOOLEAN

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

isPurchasePriceGrossisPurchasePriceGross
optional
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
optional
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
optional
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
optional
NUMBER

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

locationIdlocationId
optional
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. isStockArticle must be true, ignored otherwise.

maxStockmaxStock
optional
NUMBER

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

minStockminStock
optional
NUMBER

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

notesnotes
optional
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
optional
TEXT
MAX:50

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

salesPricesalesPrice
optional
NUMBER

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

sequenceNumberIdsequenceNumberId
optional
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
optional
NUMBER

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

unitIdunitId
optional
TEXT

The ID of the unit (like pcs., meters, liters, etc.). See Units.

Endpoint

POST /api/v1/inventory/article/create.json
Inventory Article

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:240

The name of the article.

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>

binLocationbinLocation
optional
TEXT

The place within the building (e.g. A15, B04, C11, etc.) to locate the article. See locationId. isStockArticle must be true, ignored otherwise.

categoryIdcategoryId
optional
NUMBER

The ID of the category. See Article category.

currencyIdcurrencyId
optional
NUMBER

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

customcustom
optional
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
optional
TEXT

A description of the article.

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
optional
BOOLEAN

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

isPurchasePriceGrossisPurchasePriceGross
optional
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
optional
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
optional
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
optional
NUMBER

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

locationIdlocationId
optional
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. isStockArticle must be true, ignored otherwise.

maxStockmaxStock
optional
NUMBER

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

minStockminStock
optional
NUMBER

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

notesnotes
optional
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
optional
TEXT
MAX:50

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

salesPricesalesPrice
optional
NUMBER

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

sequenceNumberIdsequenceNumberId
optional
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
optional
NUMBER

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

unitIdunitId
optional
TEXT

The ID of the unit (like pcs., meters, liters, etc.). See Units.

Endpoint

POST /api/v1/inventory/article/update.json
Inventory Article

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/article/delete.json
Inventory Article

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/article/categorize.json
Inventory Article

Update attachments

Updates the file attachments of an article. Use the File API to upload a file and then use the file ID here. Returns either a success or error message.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

fileIdsfileIds
optional
CSV

A list of file IDs, comma-separated. Leave empty to remove all attachments. Use the File API to upload a file and then use the file ID here.

Endpoint

POST /api/v1/inventory/article/update_attachments.json
Inventory  

Article category

The following API endpoints are for managing article categories.

Inventory Article category

Read category

Returns a single category by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/inventory/article/category/read.json
Inventory Article category

List categories

Returns a list of all categories.

Endpoint

GET /api/v1/inventory/article/category/list.json
Inventory Article category

Get tree of categories

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

Parameters

idid
optional
NUMBER

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

Endpoint

GET /api/v1/inventory/article/category/tree.json
Inventory Article category

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.

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>

allocationsallocations
optional
JSON

Allocations to cost centers for all articles in this category. These will be used in order items, when selecting the article. If allocations are set here, they override any allocations that would be automatically made by the corresponding sales/purchase account.

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

shareshare
mandatory
NUMBER

Allocation share. This can be a percentage or just a share number.

toCostCenterIdtoCostCenterId
mandatory
NUMBER

ID of cost center to allocate to. See Cost center.

parentIdparentId
optional
NUMBER

The ID of the parent category.

purchaseAccountIdpurchaseAccountId
optional
NUMBER

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

salesAccountIdsalesAccountId
optional
NUMBER

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

sequenceNrIdsequenceNrId
optional
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/article/category/create.json
Inventory Article category

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.

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>

allocationsallocations
optional
JSON

Allocations to cost centers for all articles in this category. These will be used in order items, when selecting the article. If allocations are set here, they override any allocations that would be automatically made by the corresponding sales/purchase account.

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

shareshare
mandatory
NUMBER

Allocation share. This can be a percentage or just a share number.

toCostCenterIdtoCostCenterId
mandatory
NUMBER

ID of cost center to allocate to. See Cost center.

parentIdparentId
optional
NUMBER

The ID of the parent category.

purchaseAccountIdpurchaseAccountId
optional
NUMBER

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

salesAccountIdsalesAccountId
optional
NUMBER

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

sequenceNrIdsequenceNrId
optional
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/article/category/update.json
Inventory Article category

Delete categories

Deletes one or multiple existing categories. 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/article/category/delete.json
Inventory  

Fixed asset

The following API endpoints are for managing fixed assets.

Inventory Fixed asset

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
Inventory Fixed asset

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
optional
NUMBER

The ID of the category to filter by.

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

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

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

onlyWithoutDeprTypeonlyWithoutDeprType
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

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

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
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

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

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

onlyWithoutDeprTypeonlyWithoutDeprType
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

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

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
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

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

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

onlyWithoutDeprTypeonlyWithoutDeprType
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

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

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
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

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

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

onlyWithoutDeprTypeonlyWithoutDeprType
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

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

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:240

The name of the fixed asset.

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>

purchasePricepurchasePrice
mandatory
NUMBER

The initial purchase price of the fixed asset.

categoryIdcategoryId
optional
NUMBER

The ID of the category. See Fixed asset category.

customcustom
optional
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
optional
DATE

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

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

deprAccountIddeprAccountId
optional
NUMBER

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

deprDurationdeprDuration
optional
NUMBER

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

deprSalvageValuedeprSalvageValue
optional
NUMBER

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

deprTypedeprType
optional
TEXT

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

descriptiondescription
optional
TEXT
MAX:512

A description of the fixed asset.

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>

disposalDebitIddisposalDebitId
optional
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
optional
TEXT

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

initialValueinitialValue
optional
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
optional
NUMBER

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

notesnotes
optional
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
optional
TEXT
MAX:50

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

purchaseCreditIdpurchaseCreditId
optional
NUMBER

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

purchaseTaxIdpurchaseTaxId
optional
NUMBER

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

purchaseTypepurchaseType
optional
TEXT

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

saleAmountsaleAmount
optional
NUMBER

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

saleCreditIdsaleCreditId
optional
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
optional
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
optional
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
optional
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
Inventory Fixed asset

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:240

The name of the fixed asset.

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>

purchasePricepurchasePrice
mandatory
NUMBER

The initial purchase price of the fixed asset.

categoryIdcategoryId
optional
NUMBER

The ID of the category. See Fixed asset category.

customcustom
optional
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
optional
DATE

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

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

deprAccountIddeprAccountId
optional
NUMBER

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

deprDurationdeprDuration
optional
NUMBER

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

deprSalvageValuedeprSalvageValue
optional
NUMBER

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

deprTypedeprType
optional
TEXT

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

descriptiondescription
optional
TEXT
MAX:512

A description of the fixed asset.

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>

disposalDebitIddisposalDebitId
optional
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
optional
TEXT

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

initialValueinitialValue
optional
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
optional
NUMBER

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

notesnotes
optional
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
optional
TEXT
MAX:50

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

purchaseCreditIdpurchaseCreditId
optional
NUMBER

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

purchaseTaxIdpurchaseTaxId
optional
NUMBER

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

purchaseTypepurchaseType
optional
TEXT

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

saleAmountsaleAmount
optional
NUMBER

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

saleCreditIdsaleCreditId
optional
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
optional
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
optional
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
optional
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
Inventory Fixed asset

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
Inventory Fixed asset

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
Inventory Fixed asset

Update attachments

Updates the file attachments of a fixed asset. Use the File API to upload a file and then use the file ID here. Returns either a success or error message.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

fileIdsfileIds
optional
CSV

A list of file IDs, comma-separated. Leave empty to remove all attachments. Use the File API to upload a file and then use the file ID here.

Endpoint

POST /api/v1/inventory/asset/update_attachments.json
Inventory  

Fixed asset category

The following API endpoints are for managing fixed asset categories.

Inventory Fixed asset category

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
Inventory Fixed asset category

List categories

Returns a list of all categories.

Endpoint

GET /api/v1/inventory/asset/category/list.json
Inventory Fixed asset category

Get tree of categories

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

Parameters

idid
optional
NUMBER

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

Endpoint

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

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.

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>

parentIdparentId
optional
NUMBER

The ID of the parent category.

Endpoint

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

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.

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>

parentIdparentId
optional
NUMBER

The ID of the parent category.

Endpoint

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

Delete categories

Deletes one or multiple existing categories. 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
Inventory  

Import

The following API endpoints are for importing articles from a file, either a vCard, Excel or CSV file.

Inventory Import

Create import

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

Parameters

fileIdfileId
mandatory
NUMBER

File to import. Valid formats: Excel and CSV. Max. size: 5 MB. Use the File API to upload a file and then use the file ID here.

categoryIdcategoryId
optional
NUMBER

Category for all new articles, overriding imported categories.

Endpoint

POST /api/v1/inventory/article/import/create.json
Inventory Import

Define mapping

Defines the mapping from Excel / CSV column header names to CashCtrl fields. See List mapping fields endpoint for a list of field names. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

Import session ID from the Create endpoint.

mappingmapping
mandatory
JSON

Mapping from columns (Excel/CSV) to fields in CashCtrl.

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

fromfrom
mandatory
TEXT

Column header name in Excel/CSV.

toto
mandatory
TEXT

Field name in CashCtrl. See List mapping fields endpoint for a list of field names.

Endpoint

POST /api/v1/inventory/article/import/mapping.json
Inventory Import

List mapping fields

Lists the fields available in CashCtrl for mapping. Used in the Define mapping endpoint.

Endpoint

GET /api/v1/inventory/article/import/mapping_combo.json
Inventory Import

Preview import

Previews the imported articles. Returns a list of articles that will be imported. This step can be omitted.

Parameters

idid
mandatory
NUMBER

Import session ID from the Create endpoint.

Endpoint

GET /api/v1/inventory/article/import/preview.json
Inventory Import

Execute import

Executes the importing of articles from the import session.

Parameters

idid
mandatory
NUMBER

Import session ID from the Create endpoint.

indexesindexes
optional
CSV

Index numbers of articles to import, comma-separated. All other articles are ignored. You can get the indexes from the JSON response of the Preview endpoint. Omit this parameter to import all articles.

Endpoint

POST /api/v1/inventory/article/import/execute.json
Inventory  

Unit

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

Inventory Unit

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
Inventory Unit

List units

Returns a list of all units.

Endpoint

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

Create unit

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

Parameters

namename
optional
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
Inventory Unit

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
optional
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
Inventory Unit

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).

Journal

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
Journal

List journal entries

Returns a list of journal entries.

Parameters

accountIdaccountId
optional
NUMBER

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyCollectiveonlyCollective
optional
BOOLEAN

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

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyImportedonlyImported
optional
BOOLEAN

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

onlyManualonlyManual
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyUntaxedonlyUntaxed
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

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

Export to Excel

Returns an Excel file of the entries list.

Parameters

accountIdaccountId
optional
NUMBER

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

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyCollectiveonlyCollective
optional
BOOLEAN

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

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyImportedonlyImported
optional
BOOLEAN

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

onlyManualonlyManual
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyUntaxedonlyUntaxed
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/journal/list.xlsx
Journal

Export to CSV

Returns a CSV file of the entries list.

Parameters

accountIdaccountId
optional
NUMBER

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

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyCollectiveonlyCollective
optional
BOOLEAN

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

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyImportedonlyImported
optional
BOOLEAN

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

onlyManualonlyManual
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyUntaxedonlyUntaxed
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/journal/list.csv
Journal

Export to PDF

Returns a PDF file of the entries list.

Parameters

accountIdaccountId
optional
NUMBER

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

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyCollectiveonlyCollective
optional
BOOLEAN

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

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyImportedonlyImported
optional
BOOLEAN

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

onlyManualonlyManual
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyUntaxedonlyUntaxed
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/journal/list.pdf
Journal

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 book 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.

allocationsallocations
optional
JSON

Allocations to cost centers, if there is either an expense or revenue account.

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

shareshare
mandatory
NUMBER

Allocation share. This can be a percentage or just a share number.

toCostCenterIdtoCostCenterId
mandatory
NUMBER

ID of cost center to allocate to. See Cost center.

associateIdassociateId
optional
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
optional
NUMBER

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

currencyRatecurrencyRate
optional
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
optional
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
optional
DATE

The date of the book entry.

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

daysBeforedaysBefore
optional
NUMBER

The next book entry will be created X days before the start date. Leave empty or set to 0 to have the next book entry created on the start date itself. See recurrence parameter.

endDateendDate
optional
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.

itemsitems
optional
JSON

Items for the collective book entry (Sammelbuchung). Omit 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
optional
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
optional
NUMBER

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

debitdebit
optional
NUMBER

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

descriptiondescription
optional
TEXT

The description of the item.

taxIdtaxId
optional
NUMBER

The ID of the tax rate. See Tax rates.

notesnotes
optional
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.

notifyEmailnotifyEmail
optional
TEXT

The e-mail address to send a notification to. See notifyType parameter.

notifyPersonIdnotifyPersonId
optional
NUMBER

The ID of the person to send a notification to. See notifyType parameter.

notifyTypenotifyType
optional
TEXT

Whether or not to send a notification e-mail when book entries have been created. Leave empty to not send any notification. Possible values: NONE, USER, PERSON, RESPONSIBLE_PERSON, EMAIL.

notifyUserIdnotifyUserId
optional
NUMBER

The ID of the user to send a notification to. See notifyType parameter. Note: User must be in this organization.

recurrencerecurrence
optional
TEXT

The interval of how often the book entry should be automatically repeated. Leave empty to not repeat the book entry (or to remove recurrence). Possible values: MONTHLY, WEEKLY, DAILY, YEARLY, SEMESTRAL, QUARTERLY, BI_MONTHLY, BI_WEEKLY.

referencereference
optional
TEXT
MAX:100

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

sequenceNumberIdsequenceNumberId
optional
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.

startDatestartDate
optional
DATE

The start date for the recurrence. This is the date when the book entry will be repeated next.

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

taxIdtaxId
optional
NUMBER

The ID of the tax rate. See Tax rates.

titletitle
optional
TEXT
MAX:250

The description of the book entry.

Endpoint

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

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 book 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.

allocationsallocations
optional
JSON

Allocations to cost centers, if there is either an expense or revenue account.

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

shareshare
mandatory
NUMBER

Allocation share. This can be a percentage or just a share number.

toCostCenterIdtoCostCenterId
mandatory
NUMBER

ID of cost center to allocate to. See Cost center.

associateIdassociateId
optional
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
optional
NUMBER

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

currencyRatecurrencyRate
optional
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
optional
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
optional
DATE

The date of the book entry.

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

daysBeforedaysBefore
optional
NUMBER

The next book entry will be created X days before the start date. Leave empty or set to 0 to have the next book entry created on the start date itself. See recurrence parameter.

endDateendDate
optional
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.

itemsitems
optional
JSON

Items for the collective book entry (Sammelbuchung). Omit 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
optional
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
optional
NUMBER

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

debitdebit
optional
NUMBER

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

descriptiondescription
optional
TEXT

The description of the item.

taxIdtaxId
optional
NUMBER

The ID of the tax rate. See Tax rates.

notesnotes
optional
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.

notifyEmailnotifyEmail
optional
TEXT

The e-mail address to send a notification to. See notifyType parameter.

notifyPersonIdnotifyPersonId
optional
NUMBER

The ID of the person to send a notification to. See notifyType parameter.

notifyTypenotifyType
optional
TEXT

Whether or not to send a notification e-mail when book entries have been created. Leave empty to not send any notification. Possible values: NONE, USER, PERSON, RESPONSIBLE_PERSON, EMAIL.

notifyUserIdnotifyUserId
optional
NUMBER

The ID of the user to send a notification to. See notifyType parameter. Note: User must be in this organization.

recurrencerecurrence
optional
TEXT

The interval of how often the book entry should be automatically repeated. Leave empty to not repeat the book entry (or to remove recurrence). Possible values: MONTHLY, WEEKLY, DAILY, YEARLY, SEMESTRAL, QUARTERLY, BI_MONTHLY, BI_WEEKLY.

referencereference
optional
TEXT
MAX:100

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

sequenceNumberIdsequenceNumberId
optional
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.

startDatestartDate
optional
DATE

The start date for the recurrence. This is the date when the book entry will be repeated next.

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

taxIdtaxId
optional
NUMBER

The ID of the tax rate. See Tax rates.

titletitle
optional
TEXT
MAX:250

The description of the book entry.

Endpoint

POST /api/v1/journal/update.json
Journal

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
Journal

Update attachments

Updates the file attachments of a journal entry. Use the File API to upload a file and then use the file ID here. Returns either a success or error message.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

fileIdsfileIds
optional
CSV

A list of file IDs, comma-separated. Leave empty to remove all attachments. Use the File API to upload a file and then use the file ID here.

Endpoint

POST /api/v1/journal/update_attachments.json
Journal

Update recurrence

Updates the recurrence of an existing book entry by journal ID. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

The ID of the journal book entry.

daysBeforedaysBefore
optional
NUMBER

The next book entry will be created X days before the start date. Leave empty or set to 0 to have the next book entry created on the start date itself. See recurrence parameter.

endDateendDate
optional
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.

notifyEmailnotifyEmail
optional
TEXT

The e-mail address to send a notification to. See notifyType parameter.

notifyPersonIdnotifyPersonId
optional
NUMBER

The ID of the person to send a notification to. See notifyType parameter.

notifyTypenotifyType
optional
TEXT

Whether or not to send a notification e-mail when book entries have been created. Leave empty to not send any notification. Possible values: NONE, USER, PERSON, RESPONSIBLE_PERSON, EMAIL.

notifyUserIdnotifyUserId
optional
NUMBER

The ID of the user to send a notification to. See notifyType parameter. Note: User must be in this organization.

recurrencerecurrence
optional
TEXT

The interval of how often the book entry should be automatically repeated. Leave empty to not repeat the book entry (or to remove recurrence). Possible values: MONTHLY, WEEKLY, DAILY, YEARLY, SEMESTRAL, QUARTERLY, BI_MONTHLY, BI_WEEKLY.

startDatestartDate
optional
DATE

The start date for the recurrence. This is the date when the book entry will be repeated next.

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

Endpoint

POST /api/v1/journal/update_recurrence.json
Journal  

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.

Journal Import

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
Journal Import

List imports

Returns a list of imports.

Parameters

dirdir
optional
TEXT

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

fiscalPeriodIdfiscalPeriodId
optional
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
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

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

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

mappingsmappings
mandatory
JSON

Mappings from columns (Excel/CSV) or fixed values to fields in CashCtrl.
Make sure that you set either the fixed value or the column value for the respective field.
e.g. columnAmount or fixedAmount

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

allocationsallocations
optional
JSON

Allocations to cost centers, if there is either an expense or revenue account.

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

shareshare
mandatory
NUMBER

Allocation share. This can be a percentage or just a share number.

toCostCenterIdtoCostCenterId
mandatory
NUMBER

ID of cost center to allocate to. See Cost center.

columnAmountcolumnAmount
optional
TEXT

The name of the amount column in the (Excel/CSV) file.

columnAssociateNamecolumnAssociateName
optional
TEXT

The name of the associate column in the (Excel/CSV) file.

columnCreditNamecolumnCreditName
optional
TEXT

The name of the credit column in the (Excel/CSV) file.

columnCurrencyCodecolumnCurrencyCode
optional
TEXT

The name of the currency column in the (Excel/CSV) file.

columnCurrencyRatecolumnCurrencyRate
optional
TEXT

The name of the currency rate column in the (Excel/CSV) file.

columnDatecolumnDate
optional
TEXT

The name of the date column in the (Excel/CSV) file.

columnDebitNamecolumnDebitName
optional
TEXT

The name of the debit column in the (Excel/CSV) file.

columnDescriptioncolumnDescription
optional
TEXT

The name of the description column in the (Excel/CSV) file.

columnNotescolumnNotes
optional
TEXT

The name of the notes column in the (Excel/CSV) file.

columnReferenceReceiptcolumnReferenceReceipt
optional
TEXT

The name of the reference receipt column in the (Excel/CSV) file.

columnTaxRatecolumnTaxRate
optional
TEXT

The name of the tax rate column in the (Excel/CSV) file.

conditionsconditions
optional
JSON

Book entry import conditions.

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

compareMethodcompareMethod
mandatory
TEXT

The type of comparison between mappingColumn value and compareValue. Possible values: EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS, GREATER_THAN, LESS_THAN, GREATER_OR_EQUALS, LESS_OR_EQUALS.

compareValuecompareValue
mandatory
TEXT

The value with which the mappingColumn value is compared.

mappingColumnmappingColumn
mandatory
TEXT

The name of the column in the (Excel/CSV) file.

customfieldscustomfields
optional
JSON

Book entry customfield mappings.

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

customFieldIdcustomFieldId
mandatory
TEXT

The ID of the customfield to which the specified column or fixed value should be assigned.

fixedValuefixedValue
optional
TEXT

The fixed value

mappingColumnmappingColumn
optional
TEXT

The name of the column in the (Excel/CSV) file.

fixedAmountfixedAmount
optional
NUMBER

The fixed amount of the book entry (e.g. 125.50).

fixedAssociateIdfixedAssociateId
optional
TEXT

The fixed 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.

fixedCreditIdfixedCreditId
optional
NUMBER

The fixed ID of the account on the credit side. See Account.

fixedCurrencyCodeIdfixedCurrencyCodeId
optional
NUMBER

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

fixedCurrencyRatefixedCurrencyRate
optional
NUMBER

The fixed 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.

fixedDatefixedDate
optional
DATE

The fixed date of the book entry.

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

fixedDebitIdfixedDebitId
optional
NUMBER

The fixed ID of the account on the debit side. See Account.

fixedDescriptionfixedDescription
optional
TEXT
MAX:250

The fixed description of the book entry.

fixedNotesfixedNotes
optional
TEXT

The fixed notes of the book entry.

fixedReferenceReceiptfixedReferenceReceipt
optional
TEXT
MAX:100

A fixed optional reference / receipt for the book entry.

fixedTaxRateIdfixedTaxRateId
optional
NUMBER

The fixed ID of the tax rate. See Tax rates.

fileIdfileId
optional
NUMBER

File to import. Valid formats: camt.052, camt.053, camt.054, MT940, Excel, CSV and any of these formats within a ZIP or TAR file. Max. size: 5 MB. Use the File API to upload a file and then use the file ID here.

isForceSequenceNumberisForceSequenceNumber
optional
BOOLEAN

Force the use of sequence numbers? Otherwise imports the reference number if exists. Defaults to false Possible values: true, false.

targetAccountIdtargetAccountId
optional
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
Journal Import

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
Journal  

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).

Journal Import entry

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
Journal Import entry

List import entries

Returns a list of import entries.

Parameters

importIdimportId
mandatory
NUMBER

The ID of the journal import.

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

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

Export to Excel

Returns an Excel file of the entries list.

Parameters

importIdimportId
mandatory
NUMBER

The ID of the journal import.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

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

Export to CSV

Returns a CSV file of the entries list.

Parameters

importIdimportId
mandatory
NUMBER

The ID of the journal import.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

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

Export to PDF

Returns a PDF file of the entries list.

Parameters

importIdimportId
mandatory
NUMBER

The ID of the journal import.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

Endpoint

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

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.

allocationsallocations
optional
JSON

Allocations to cost centers, if there is either an expense or revenue account.

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

shareshare
mandatory
NUMBER

Allocation share. This can be a percentage or just a share number.

toCostCenterIdtoCostCenterId
mandatory
NUMBER

ID of cost center to allocate to. See Cost center.

associateIdassociateId
optional
TEXT

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

currencyIdcurrencyId
optional
NUMBER

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

currencyRatecurrencyRate
optional
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
optional
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
optional
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
optional
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
optional
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
optional
TEXT
MAX:100

An optional reference / receipt for the book entry.

taxIdtaxId
optional
NUMBER

The ID of the tax rate. See Tax rates.

titletitle
optional
TEXT
MAX:250

The description of the book entry.

Endpoint

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

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
Journal Import entry

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
Journal Import entry

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
Journal Import entry

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
Meta  

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.

Meta Fiscal period

Read fiscal period

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

Parameters

idid
optional
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
Meta Fiscal period

List fiscal periods

Returns a list of all fiscal periods.

Endpoint

GET /api/v1/fiscalperiod/list.json
Meta Fiscal period

Create fiscal period

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

Parameters

endend
optional
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
optional
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
optional
TEXT
MAX:30

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

startstart
optional
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
optional
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
Meta Fiscal period

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
optional
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
optional
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
optional
TEXT
MAX:30

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

startstart
optional
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
optional
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
Meta Fiscal period

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

POST /api/v1/fiscalperiod/switch.json
Meta Fiscal period

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
Meta Fiscal period

Get result

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

Parameters

idid
optional
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
Meta Fiscal period

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
Meta Fiscal period

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
Meta Fiscal period

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.

Parameters

datedate
optional
DATE

Optional booking date. Leave empty to use the last day of the current fiscal period (see Switch fiscal period).

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

Endpoint

GET /api/v1/fiscalperiod/exchangediff.json
Meta Fiscal period

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).

datedate
optional
DATE

Optional booking date. Leave empty to use the last day of the current fiscal period (see Switch fiscal period).

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

Endpoint

POST /api/v1/fiscalperiod/bookexchangediff.json
Meta Fiscal period

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
Meta Fiscal period

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
Meta  

Fiscal period task

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

Meta Fiscal period task

List tasks

Returns a list of tasks.

Endpoint

GET /api/v1/fiscalperiod/task/list.json
Meta Fiscal period task

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
Meta Fiscal period task

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
Meta  

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.

Meta Location

Read location

Returns a single location by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/location/read.json
Meta Location

List locations

Returns a list of all locations.

Endpoint

GET /api/v1/location/list.json
Meta Location

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
optional
TEXT
MAX:250

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

bicbic
optional
TEXT
MAX:11

The BIC (Business Identifier Code) of your bank.

citycity
optional
TEXT
MAX:100

The town / city of the location.

countrycountry
optional
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
optional
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
optional
TEXT
MAX:32

The IBAN (International Bank Account Number).

isInactiveisInactive
optional
BOOLEAN

Mark the location as inactive. Inactive locations are greyed out and are no longer suggested. Possible values: true, false.

logoFileIdlogoFileId
optional
NUMBER

The company logo. Supported types: JPG, GIF, PNG. Max. size: 400KB. Max. resolution: 2500x2500px. Use the File API to upload a file and then use the file ID here.

orgNameorgName
optional
TEXT
MAX:250

The name of the company.

qrFirstDigitsqrFirstDigits
optional
NUMBER
MAX:8

The first few digits of the Swiss QR reference (0 by default). This is specific to Switzerland.

qrIbanqrIban
optional
TEXT
MAX:32

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

typetype
optional
TEXT

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

vatUidvatUid
optional
TEXT
MAX:32

The UID (VAT no.) of the company.

zipzip
optional
TEXT
MAX:10

The postal code of the location.

Endpoint

POST /api/v1/location/create.json
Meta Location

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
optional
TEXT
MAX:250

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

bicbic
optional
TEXT
MAX:11

The BIC (Business Identifier Code) of your bank.

citycity
optional
TEXT
MAX:100

The town / city of the location.

countrycountry
optional
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
optional
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
optional
TEXT
MAX:32

The IBAN (International Bank Account Number).

isInactiveisInactive
optional
BOOLEAN

Mark the location as inactive. Inactive locations are greyed out and are no longer suggested. Possible values: true, false.

logoFileIdlogoFileId
optional
NUMBER

The company logo. Supported types: JPG, GIF, PNG. Max. size: 400KB. Max. resolution: 2500x2500px. Use the File API to upload a file and then use the file ID here.

orgNameorgName
optional
TEXT
MAX:250

The name of the company.

qrFirstDigitsqrFirstDigits
optional
NUMBER
MAX:8

The first few digits of the Swiss QR reference (0 by default). This is specific to Switzerland.

qrIbanqrIban
optional
TEXT
MAX:32

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

typetype
optional
TEXT

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

vatUidvatUid
optional
TEXT
MAX:32

The UID (VAT no.) of the company.

zipzip
optional
TEXT
MAX:10

The postal code of the location.

Endpoint

POST /api/v1/location/update.json
Meta Location

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
Meta  

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.

Meta Organization

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
Meta  

Settings

The following API endpoints are for managing general settings.

Meta Settings

Read settings

Returns all settings.

Endpoint

GET /api/v1/setting/read.json
Meta Settings

Get setting value

Returns a specific setting value.

Parameters

namename
mandatory
TEXT

The name of the setting.

Endpoint

GET /api/v1/setting/get
Meta Settings

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 to get a list of available settings, and then update the ones you would like to update. You can also define your own settings, but text-only.

Endpoint

POST /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.

Order

Read order

Returns a single order by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/order/read.json
Order

List orders

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

Parameters

categoryIdcategoryId
optional
NUMBER

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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.

groupIdgroupId
optional
NUMBER

The ID of the order group (dossier) to filter by.

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyOpenonlyOpen
optional
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
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

statusIdstatusId
optional
NUMBER

The ID of the order status to filter by.

typetype
optional
TEXT

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

Endpoint

GET /api/v1/order/list.json
Order

Export to Excel

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

Parameters

categoryIdcategoryId
optional
NUMBER

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

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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.

groupIdgroupId
optional
NUMBER

The ID of the order group (dossier) to filter by.

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyOpenonlyOpen
optional
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
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

statusIdstatusId
optional
NUMBER

The ID of the order status to filter by.

typetype
optional
TEXT

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

Endpoint

GET /api/v1/order/list.xlsx
Order

Export to CSV

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

Parameters

categoryIdcategoryId
optional
NUMBER

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

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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.

groupIdgroupId
optional
NUMBER

The ID of the order group (dossier) to filter by.

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyOpenonlyOpen
optional
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
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

statusIdstatusId
optional
NUMBER

The ID of the order status to filter by.

typetype
optional
TEXT

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

Endpoint

GET /api/v1/order/list.csv
Order

Export to PDF

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

Parameters

categoryIdcategoryId
optional
NUMBER

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

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

fiscalPeriodIdfiscalPeriodId
optional
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.

groupIdgroupId
optional
NUMBER

The ID of the order group (dossier) to filter by.

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyCostCentersonlyCostCenters
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyOpenonlyOpen
optional
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
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

statusIdstatusId
optional
NUMBER

The ID of the order status to filter by.

typetype
optional
TEXT

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

Endpoint

GET /api/v1/order/list.pdf
Order

Create order

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

Parameters

associateIdassociateId
mandatory
CSV

The IDs of one or multiple business partners (customers / vendors), comma-separated. If you enter multiple IDs it will create a separate document for each business partner. 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
optional
NUMBER

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

currencyIdcurrencyId
optional
NUMBER

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

currencyRatecurrencyRate
optional
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
optional
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.

daysBeforedaysBefore
optional
NUMBER

The next order will be created X days before the start date. Leave empty or set to 0 to have the next order created on the start date itself. See recurrence parameter.

descriptiondescription
optional
TEXT
MAX:200

A description of the order document.

discountPercentagediscountPercentage
optional
NUMBER
MIN:0.0
MAX:100.0

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

dueDaysdueDays
optional
NUMBER

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

endDateendDate
optional
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
optional
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). This is overridden by previousId (if both are set).

isDisplayItemGrossisDisplayItemGross
optional
BOOLEAN

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

itemsitems
optional
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).

allocationsallocations
optional
JSON

Allocations to cost centers, if there is either an expense or revenue account.

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

shareshare
mandatory
NUMBER

Allocation share. This can be a percentage or just a share number.

toCostCenterIdtoCostCenterId
mandatory
NUMBER

ID of cost center to allocate to. See Cost center.

articleNrarticleNr
optional
TEXT

The article number.

descriptiondescription
optional
TEXT

A description of the item.

discountPercentagediscountPercentage
optional
NUMBER

Discount percentage for the item price.

inventoryIdinventoryId
optional
NUMBER

The ID of the inventory article. See Inventory.

quantityquantity
optional
NUMBER

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

taxIdtaxId
optional
NUMBER

The ID of the tax rate. See Tax rates.

typetype
optional
TEXT

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

unitIdunitId
optional
TEXT

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

languagelanguage
optional
TEXT

The language of the document. Possible values: DE, EN, FR, IT.

notesnotes
optional
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.

notifyEmailnotifyEmail
optional
TEXT

The e-mail address to send a notification to. See notifyType parameter.

notifyPersonIdnotifyPersonId
optional
NUMBER

The ID of the person to send a notification to. See notifyType parameter.

notifyTypenotifyType
optional
TEXT

Whether to send a notification e-mail when orders have been created or not. Leave empty to not send any notification. Possible values: NONE, USER, PERSON, RESPONSIBLE_PERSON, EMAIL.

notifyUserIdnotifyUserId
optional
NUMBER

The ID of the user to send a notification to. See notifyType parameter. Note: User must be in this organization.

nrnr
optional
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
optional
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. See also groupId. This will override groupId (if both are set).

recurrencerecurrence
optional
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
optional
TEXT

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

roundingIdroundingId
optional
NUMBER

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

sequenceNumberIdsequenceNumberId
optional
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
optional
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
optional
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
Order

Update order

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

Parameters

associateIdassociateId
mandatory
NUMBER

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
optional
NUMBER

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

currencyIdcurrencyId
optional
NUMBER

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

currencyRatecurrencyRate
optional
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
optional
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.

daysBeforedaysBefore
optional
NUMBER

The next order will be created X days before the start date. Leave empty or set to 0 to have the next order created on the start date itself. See recurrence parameter.

descriptiondescription
optional
TEXT
MAX:200

A description of the order document.

discountPercentagediscountPercentage
optional
NUMBER
MIN:0.0
MAX:100.0

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

dueDaysdueDays
optional
NUMBER

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

endDateendDate
optional
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
optional
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). This is overridden by previousId (if both are set).

isDisplayItemGrossisDisplayItemGross
optional
BOOLEAN

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

itemsitems
optional
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).

allocationsallocations
optional
JSON

Allocations to cost centers, if there is either an expense or revenue account.

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

shareshare
mandatory
NUMBER

Allocation share. This can be a percentage or just a share number.

toCostCenterIdtoCostCenterId
mandatory
NUMBER

ID of cost center to allocate to. See Cost center.

articleNrarticleNr
optional
TEXT

The article number.

descriptiondescription
optional
TEXT

A description of the item.

discountPercentagediscountPercentage
optional
NUMBER

Discount percentage for the item price.

inventoryIdinventoryId
optional
NUMBER

The ID of the inventory article. See Inventory.

quantityquantity
optional
NUMBER

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

taxIdtaxId
optional
NUMBER

The ID of the tax rate. See Tax rates.

typetype
optional
TEXT

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

unitIdunitId
optional
TEXT

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

languagelanguage
optional
TEXT

The language of the document. Possible values: DE, EN, FR, IT.

notesnotes
optional
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.

notifyEmailnotifyEmail
optional
TEXT

The e-mail address to send a notification to. See notifyType parameter.

notifyPersonIdnotifyPersonId
optional
NUMBER

The ID of the person to send a notification to. See notifyType parameter.

notifyTypenotifyType
optional
TEXT

Whether to send a notification e-mail when orders have been created or not. Leave empty to not send any notification. Possible values: NONE, USER, PERSON, RESPONSIBLE_PERSON, EMAIL.

notifyUserIdnotifyUserId
optional
NUMBER

The ID of the user to send a notification to. See notifyType parameter. Note: User must be in this organization.

nrnr
optional
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
optional
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. See also groupId. This will override groupId (if both are set).

recurrencerecurrence
optional
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
optional
TEXT

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

roundingIdroundingId
optional
NUMBER

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

sequenceNumberIdsequenceNumberId
optional
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
optional
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
optional
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
Order

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
Order

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
Order

Update status

Updates the status of an existing order by order ID. Returns either a success or multiple error messages (for each issue).

Parameters

idsids
mandatory
CSV

The IDs of one or multiple orders, comma-separated.

statusIdstatusId
mandatory
NUMBER

The ID of the new status.

Endpoint

POST /api/v1/order/update_status.json
Order

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.

daysBeforedaysBefore
optional
NUMBER

The next order will be created X days before the start date. Leave empty or set to 0 to have the next order created on the start date itself. See recurrence parameter.

endDateendDate
optional
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.

notifyEmailnotifyEmail
optional
TEXT

The e-mail address to send a notification to. See notifyType parameter.

notifyPersonIdnotifyPersonId
optional
NUMBER

The ID of the person to send a notification to. See notifyType parameter.

notifyTypenotifyType
optional
TEXT

Whether or not to send a notification e-mail when orders have been created. Leave empty to not send any notification. Possible values: NONE, USER, PERSON, RESPONSIBLE_PERSON, EMAIL.

notifyUserIdnotifyUserId
optional
NUMBER

The ID of the user to send a notification to. See notifyType parameter. Note: User must be in this organization.

recurrencerecurrence
optional
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
optional
DATE

The start date for the recurrence. This is the date when the order will be repeated next.

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

Endpoint

POST /api/v1/order/update_recurrence.json
Order

Continue as

Continue an order as another order (e.g. continue an offer as an invoice). Returns either a success or multiple error messages (for each issue).

Parameters

categoryIdcategoryId
mandatory
NUMBER

The ID of the target category.

idsids
mandatory
CSV

The IDs of one or multiple orders to continue, comma-separated.

associateIdassociateId
optional
TEXT

The ID of the business partner (customer / vendor). Mandatory only if changing between sales and purchase order. See Person.

datedate
optional
DATE

The date of the order. Leave empty to use today.

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

notesnotes
optional
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.

statusIdstatusId
optional
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/continue.json
Order

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
Order

Add to dossier

Adds one or multiple orders to a dossier.

Parameters

groupIdgroupId
mandatory
NUMBER

The ID of the group.

idsids
mandatory
CSV

The IDs of the orders to add/remove, comma-separated.

Endpoint

POST /api/v1/order/dossier_add.json
Order

Remove from dossier

Removes one or multiple orders from a dossier.

Parameters

groupIdgroupId
mandatory
NUMBER

The ID of the group.

idsids
mandatory
CSV

The IDs of the orders to add/remove, comma-separated.

Endpoint

POST /api/v1/order/dossier_remove.json
Order

Update attachments

Updates the file attachments of an order. Use the File API to upload a file and then use the file ID here. Returns either a success or error message.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

fileIdsfileIds
optional
CSV

A list of file IDs, comma-separated. Leave empty to remove all attachments. Use the File API to upload a file and then use the file ID here.

Endpoint

POST /api/v1/order/update_attachments.json
Order  

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).

Order Book entry

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
Order Book entry

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
Order Book entry

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.

orderIdsorderIds
mandatory
CSV

The IDs of one or multiple orders, comma-separated. See Order.

amountamount
optional
NUMBER

The amount of the book entry (e.g. 125.50). Leave empty to use open amount of order.

currencyIdcurrencyId
optional
NUMBER

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

currencyRatecurrencyRate
optional
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
optional
DATE

The date of the book entry.

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

descriptiondescription
optional
TEXT
MAX:200

The description of the book entry.

referencereference
optional
TEXT

An optional reference / receipt for the book entry.

taxIdtaxId
optional
NUMBER

The ID of the tax rate. See Tax rates.

templateIdtemplateId
optional
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
Order Book entry

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.

idid
mandatory
NUMBER

The ID of the book entry to update.

amountamount
optional
NUMBER

The amount of the book entry (e.g. 125.50). Leave empty to use open amount of order.

currencyIdcurrencyId
optional
NUMBER

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

currencyRatecurrencyRate
optional
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
optional
DATE

The date of the book entry.

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

descriptiondescription
optional
TEXT
MAX:200

The description of the book entry.

referencereference
optional
TEXT

An optional reference / receipt for the book entry.

taxIdtaxId
optional
NUMBER

The ID of the tax rate. See Tax rates.

templateIdtemplateId
optional
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
Order Book entry

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
Order  

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.

Order Category

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
Order Category

List categories

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

Parameters

fiscalPeriodIdfiscalPeriodId
optional
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
optional
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
Order Category

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
optional
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 an underscore and the actual ID of the category or book template (e.g. BOOK_TEMPLATE_10).

isAddStockisAddStock
optional
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
optional
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
optional
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
optional
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.

addressTypeaddressType
optional
TEXT

Which address of the recipient to use in the order document. Defaults to MAIN. Possible values: MAIN, INVOICE, DELIVERY, OTHER.

bookTemplatesbookTemplates
optional
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
optional
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
optional
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
optional
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
optional
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
optional
NUMBER

The due days used by default for order objects in this category. The order date + due days equals the due date.

fileIdfileId
optional
NUMBER

An optional PDF document whose pages are added at the end of the order document. Supported type: PDF. Max. size: 500KB. Use the File API to upload a file and then use the file ID here.

footerfooter
optional
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
optional
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
optional
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
optional
BOOLEAN

Whether order item totals are displayed as gross (including tax) or net. Defaults to false. Possible values: true, false.

isDisplayPricesisDisplayPrices
optional
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
optional
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
optional
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
optional
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
optional
TEXT

The ID of the responsible person (Sachbearbeiter) used for order objects in this category. See Person.

roundingIdroundingId
optional
NUMBER

The ID of the rounding used for order objects in this category. See Rounding.

sentStatusIdsentStatusId
optional
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
optional
NUMBER

The ID of the sequence number used for order objects in this category. See Sequence number.

templateIdtemplateId
optional
NUMBER

The ID of the document template used for order objects in this category. See Document template.

typetype
optional
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
Order Category

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
optional
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 an underscore and the actual ID of the category or book template (e.g. BOOK_TEMPLATE_10).

isAddStockisAddStock
optional
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
optional
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
optional
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
optional
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.

addressTypeaddressType
optional
TEXT

Which address of the recipient to use in the order document. Defaults to MAIN. Possible values: MAIN, INVOICE, DELIVERY, OTHER.

bookTemplatesbookTemplates
optional
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
optional
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
optional
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
optional
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
optional
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
optional
NUMBER

The due days used by default for order objects in this category. The order date + due days equals the due date.

fileIdfileId
optional
NUMBER

An optional PDF document whose pages are added at the end of the order document. Supported type: PDF. Max. size: 500KB. Use the File API to upload a file and then use the file ID here.

footerfooter
optional
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
optional
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
optional
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
optional
BOOLEAN

Whether order item totals are displayed as gross (including tax) or net. Defaults to false. Possible values: true, false.

isDisplayPricesisDisplayPrices
optional
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
optional
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
optional
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
optional
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
optional
TEXT

The ID of the responsible person (Sachbearbeiter) used for order objects in this category. See Person.

roundingIdroundingId
optional
NUMBER

The ID of the rounding used for order objects in this category. See Rounding.

sentStatusIdsentStatusId
optional
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
optional
NUMBER

The ID of the sequence number used for order objects in this category. See Sequence number.

templateIdtemplateId
optional
NUMBER

The ID of the document template used for order objects in this category. See Document template.

typetype
optional
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
Order Category

Delete categories

Deletes one or multiple existing categories. 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
Order Category

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
optional
BOOLEAN

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

typetype
optional
TEXT

The type of category. Defaults to SALES. Possible values: SALES, PURCHASE.

Endpoint

POST /api/v1/order/category/reorder.json
Order Category

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
Order  

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.

Order Document

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
Order Document

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
Order Document

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
Order Document

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.

orderIdsorderIds
mandatory
CSV

The IDs of the orders to send as mail, comma-separated. See Order.

isCopyToMeisCopyToMe
optional
BOOLEAN

Send a copy to me? (the sender, see mailFrom) Possible values: true, false.

mailBccmailBcc
optional
TEXT

The BCC (blind carbon copy) e-mail address. You can enter multiple addresses comma-separated.

mailCcmailCc
optional
TEXT

The CC (carbon copy) e-mail address. You can enter multiple addresses comma-separated.

mailTomailTo
optional
TEXT

The recipient e-mail address. You can enter multiple addresses comma-separated. Leave empty to use the default e-mail address of the business associate.

sentStatusIdsentStatusId
optional
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
Order Document

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.

fileIdfileId
optional
NUMBER

An optional PDF document whose pages are added at the end of the order document. Supported type: PDF. Max. size: 500KB. Use the File API to upload a file and then use the file ID here.

footerfooter
optional
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
optional
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
optional
BOOLEAN

Whether order item totals are displayed as gross (including tax) or net. Defaults to false. Possible values: true, false.

isFileReplacementisFileReplacement
optional
BOOLEAN

Replace the generated order document with the attached PDF file? (see fileId) Possible values: true, false.

languagelanguage
optional
TEXT

The language of the document. Possible values: DE, EN, FR, IT.

orgAddressorgAddress
optional
TEXT
MAX:255

The sender address formatted with line breaks.

orgLocationIdorgLocationId
optional
NUMBER

The ID of the sender location. See Location.

recipientAddressrecipientAddress
optional
TEXT
MAX:255

The recipient address formatted with line breaks.

recipientAddressIdrecipientAddressId
optional
NUMBER

The ID of the recipient address (person address). See Person.

templateIdtemplateId
optional
NUMBER

The ID of the document template. See Document template.

Endpoint

POST /api/v1/order/document/update.json
Order  

Document template

The following API endpoints are for managing document templates. Document templates define the look and feel of the Order document.

Order Document template

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
Order Document template

List templates

Returns a list of all templates.

Endpoint

GET /api/v1/order/template/list.json
Order Document template

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
optional
CSS

The CSS stylesheet for the template.

footerfooter
optional
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
optional
HTML

The HTML and Apache Velocity template.

isDefaultisDefault
optional
BOOLEAN

Mark the template as the default template to use. Defaults to false. Possible values: true, false.

isDisplayDocumentNameisDisplayDocumentName
optional
BOOLEAN

Display document name/title? Defaults to true. Possible values: true, false.

isDisplayItemArticleNrisDisplayItemArticleNr
optional
BOOLEAN

Display article no. for items? Defaults to true. Possible values: true, false.

isDisplayItemPriceRoundedisDisplayItemPriceRounded
optional
BOOLEAN

Display item prices rounded? Defaults to true. Possible values: true, false.

isDisplayItemTaxisDisplayItemTax
optional
BOOLEAN

Display tax for items? Defaults to false. Possible values: true, false.

isDisplayItemUnitisDisplayItemUnit
optional
BOOLEAN

Display unit for items? Defaults to true. Possible values: true, false.

isDisplayLogoisDisplayLogo
optional
BOOLEAN

Display logo? Defaults to true. Possible values: true, false.

isDisplayOrgAddressInWindowisDisplayOrgAddressInWindow
optional
BOOLEAN

Display (your) organization address in window? Defaults to true. Possible values: true, false.

isDisplayPageNrisDisplayPageNr
optional
BOOLEAN

Display page numbers? Defaults to true. Possible values: true, false.

isDisplayPaymentsisDisplayPayments
optional
BOOLEAN

Display payments? Defaults to true. Possible values: true, false.

isDisplayPosNrisDisplayPosNr
optional
BOOLEAN

Display item numbering? Defaults to true. Possible values: true, false.

isDisplayRecipientNrisDisplayRecipientNr
optional
BOOLEAN

Display recipient number (customer/vendor no.)? Defaults to true. Possible values: true, false.

isDisplayResponsiblePersonisDisplayResponsiblePerson
optional
BOOLEAN

Display responsible person (Sachbearbeiter)? Defaults to true. Possible values: true, false.

isDisplayZeroTaxisDisplayZeroTax
optional
BOOLEAN

Display zero tax (with a value of 0.00)? Defaults to false. Possible values: true, false.

isOverwriteCssisOverwriteCss
optional
BOOLEAN

Overwrite default CSS? Only relevant if system-template, otherwise your own CSS is always used. Possible values: true, false.

isOverwriteHtmlisOverwriteHtml
optional
BOOLEAN

Overwrite default HTML? Only relevant if system-template, otherwise your own HTML is always used. Possible values: true, false.

isQrEmptyAmountisQrEmptyAmount
optional
BOOLEAN

Leave amount empty in the QR code? Otherwise the open amount is used in the QR code. Possible values: true, false.

isQrNoLinesisQrNoLines
optional
BOOLEAN

Display QR invoice without any lines? Dashed lines with scissors by default. Possible values: true, false.

isQrNoReferenceNrisQrNoReferenceNr
optional
BOOLEAN

Display QR invoice without reference number? Generates reference number by default. Possible values: true, false.

letterPaperFileIdletterPaperFileId
optional
NUMBER

An optional letter paper to embed on every page (behind the text). Supported type: PDF. Max. size: 500KB. Use the File API to upload a file and then use the file ID here.

logoHeightlogoHeight
optional
NUMBER
MIN:0.1
MAX:9.0

The height of the logo in centimeters.

pageSizepageSize
optional
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
Order Document template

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
optional
CSS

The CSS stylesheet for the template.

footerfooter
optional
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
optional
HTML

The HTML and Apache Velocity template.

isDefaultisDefault
optional
BOOLEAN

Mark the template as the default template to use. Defaults to false. Possible values: true, false.

isDisplayDocumentNameisDisplayDocumentName
optional
BOOLEAN

Display document name/title? Defaults to true. Possible values: true, false.

isDisplayItemArticleNrisDisplayItemArticleNr
optional
BOOLEAN

Display article no. for items? Defaults to true. Possible values: true, false.

isDisplayItemPriceRoundedisDisplayItemPriceRounded
optional
BOOLEAN

Display item prices rounded? Defaults to true. Possible values: true, false.

isDisplayItemTaxisDisplayItemTax
optional
BOOLEAN

Display tax for items? Defaults to false. Possible values: true, false.

isDisplayItemUnitisDisplayItemUnit
optional
BOOLEAN

Display unit for items? Defaults to true. Possible values: true, false.

isDisplayLogoisDisplayLogo
optional
BOOLEAN

Display logo? Defaults to true. Possible values: true, false.

isDisplayOrgAddressInWindowisDisplayOrgAddressInWindow
optional
BOOLEAN

Display (your) organization address in window? Defaults to true. Possible values: true, false.

isDisplayPageNrisDisplayPageNr
optional
BOOLEAN

Display page numbers? Defaults to true. Possible values: true, false.

isDisplayPaymentsisDisplayPayments
optional
BOOLEAN

Display payments? Defaults to true. Possible values: true, false.

isDisplayPosNrisDisplayPosNr
optional
BOOLEAN

Display item numbering? Defaults to true. Possible values: true, false.

isDisplayRecipientNrisDisplayRecipientNr
optional
BOOLEAN

Display recipient number (customer/vendor no.)? Defaults to true. Possible values: true, false.

isDisplayResponsiblePersonisDisplayResponsiblePerson
optional
BOOLEAN

Display responsible person (Sachbearbeiter)? Defaults to true. Possible values: true, false.

isDisplayZeroTaxisDisplayZeroTax
optional
BOOLEAN

Display zero tax (with a value of 0.00)? Defaults to false. Possible values: true, false.

isOverwriteCssisOverwriteCss
optional
BOOLEAN

Overwrite default CSS? Only relevant if system-template, otherwise your own CSS is always used. Possible values: true, false.

isOverwriteHtmlisOverwriteHtml
optional
BOOLEAN

Overwrite default HTML? Only relevant if system-template, otherwise your own HTML is always used. Possible values: true, false.

isQrEmptyAmountisQrEmptyAmount
optional
BOOLEAN

Leave amount empty in the QR code? Otherwise the open amount is used in the QR code. Possible values: true, false.

isQrNoLinesisQrNoLines
optional
BOOLEAN

Display QR invoice without any lines? Dashed lines with scissors by default. Possible values: true, false.

isQrNoReferenceNrisQrNoReferenceNr
optional
BOOLEAN

Display QR invoice without reference number? Generates reference number by default. Possible values: true, false.

letterPaperFileIdletterPaperFileId
optional
NUMBER

An optional letter paper to embed on every page (behind the text). Supported type: PDF. Max. size: 500KB. Use the File API to upload a file and then use the file ID here.

logoHeightlogoHeight
optional
NUMBER
MIN:0.1
MAX:9.0

The height of the logo in centimeters.

pageSizepageSize
optional
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
Order Document template

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.

Person

Read person

Returns a single person by ID.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

Endpoint

GET /api/v1/person/read.json
Person

List people

Returns a list of people.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

Flag to include only people with images. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/person/list.json
Person

Export to Excel

Returns an Excel file of the people list.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

Flag to include only people with images. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/person/list.xlsx
Person

Export to CSV

Returns a CSV file of the people list.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

Flag to include only people with images. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/person/list.csv
Person

Export to PDF

Returns a PDF file of the people list.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

Flag to include only people with images. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/person/list.pdf
Person

Export to vCard

Returns a vCard file containing a list of people.

Parameters

categoryIdcategoryId
optional
NUMBER

The ID of the category to filter by.

columnscolumns
optional
CSV

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

dirdir
optional
TEXT

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

filterfilter
optional
JSON

An array of filters to filter the list. All filters must match (AND).

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

comparisoncomparison
optional
TEXT

Comparison type. Possible values: eq, like, gt, lt.

fieldfield
optional
TEXT

The name of the column to filter by.

valuevalue
optional
TEXT

Text to filter by, or a JSON array of multiple values (OR).

limitlimit
optional
NUMBER

The number of entries to retrieve. Defaults to 100.

onlyActiveonlyActive
optional
BOOLEAN

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

onlyNotesonlyNotes
optional
BOOLEAN

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

onlyWithImagesonlyWithImages
optional
BOOLEAN

Flag to include only people with images. Defaults to false. Possible values: true, false.

onlyWithoutCategoryonlyWithoutCategory
optional
BOOLEAN

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

queryquery
optional
TEXT

Fulltext search query.

sortsort
optional
TEXT

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

startstart
optional
NUMBER

The starting entry. Defaults to 0.

Endpoint

GET /api/v1/person/list.vcf
Person

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
optional
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
optional
TEXT

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

citycity
optional
TEXT

The town / city of the address.

countrycountry
optional
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
optional
TEXT

The postal code of the address.

altNamealtName
optional
TEXT
MAX:100

An alternative name for this person (for organizational chart).

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>

bicbic
optional
TEXT
MAX:11

The BIC (Business Identifier Code) of the person's bank.

categoryIdcategoryId
optional
NUMBER

The ID of the category. See Person category.

colorcolor
optional
TEXT

The color to use for this person in the organizational chart. Leave empty for white. Possible values: BLUE, GREEN, RED, YELLOW, ORANGE, BLACK, GRAY, BROWN, VIOLET, PINK.

contactscontacts
optional
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.).

typetype
mandatory
TEXT

The type of contact information. Possible values: EMAIL_INVOICE, EMAIL_WORK, EMAIL_PRIVATE, PHONE_RECEPTION, PHONE_WORK, PHONE_PRIVATE, MOBILE_WORK, MOBILE_PRIVATE, FAX, WEBSITE, MESSENGER, OTHER.

customcustom
optional
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
optional
DATE

The person's date of birth.

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

departmentdepartment
optional
TEXT
MAX:100

The department of the person within the company.

discountPercentagediscountPercentage
optional
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
optional
TEXT
MAX:32

The IBAN (International Bank Account Number) of the person.

industryindustry
optional
TEXT
MAX:100

The industry of the company or the trade/vocation of the person.

isInactiveisInactive
optional
BOOLEAN

Mark the person as inactive. The person will be greyed out and no longer suggested. Defaults to false. Possible values: true, false.

languagelanguage
optional
TEXT

The main language of the person. May be used for documents. Possible values: DE, EN, FR, IT.

notesnotes
optional
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
optional
TEXT
MAX:50

The person number (e.g. customer no.).

positionposition
optional
TEXT
MAX:100

The position (job title) of the person within the company.

sequenceNumberIdsequenceNumberId
optional
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.

superiorIdsuperiorId
optional
NUMBER

The superior of this person (for organizational chart).

titleIdtitleId
optional
NUMBER

The person's title (e.g. 'Mr.', 'Mrs.', 'Dr.'). See Person title.

vatUidvatUid
optional
TEXT
MAX:32

The UID (VAT no.) of the company.

Endpoint

POST /api/v1/person/create.json
Person

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
optional
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
optional
TEXT

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

citycity
optional
TEXT

The town / city of the address.

countrycountry
optional
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
optional
TEXT

The postal code of the address.

altNamealtName
optional
TEXT
MAX:100

An alternative name for this person (for organizational chart).

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>

bicbic
optional
TEXT
MAX:11

The BIC (Business Identifier Code) of the person's bank.

categoryIdcategoryId
optional
NUMBER

The ID of the category. See Person category.

colorcolor
optional
TEXT

The color to use for this person in the organizational chart. Leave empty for white. Possible values: BLUE, GREEN, RED, YELLOW, ORANGE, BLACK, GRAY, BROWN, VIOLET, PINK.

contactscontacts
optional
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.).

typetype
mandatory
TEXT

The type of contact information. Possible values: EMAIL_INVOICE, EMAIL_WORK, EMAIL_PRIVATE, PHONE_RECEPTION, PHONE_WORK, PHONE_PRIVATE, MOBILE_WORK, MOBILE_PRIVATE, FAX, WEBSITE, MESSENGER, OTHER.

customcustom
optional
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
optional
DATE

The person's date of birth.

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

departmentdepartment
optional
TEXT
MAX:100

The department of the person within the company.

discountPercentagediscountPercentage
optional
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
optional
TEXT
MAX:32

The IBAN (International Bank Account Number) of the person.

industryindustry
optional
TEXT
MAX:100

The industry of the company or the trade/vocation of the person.

isInactiveisInactive
optional
BOOLEAN

Mark the person as inactive. The person will be greyed out and no longer suggested. Defaults to false. Possible values: true, false.

languagelanguage
optional
TEXT

The main language of the person. May be used for documents. Possible values: DE, EN, FR, IT.

notesnotes
optional
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
optional
TEXT
MAX:50

The person number (e.g. customer no.).

positionposition
optional
TEXT
MAX:100

The position (job title) of the person within the company.

sequenceNumberIdsequenceNumberId
optional
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.

superiorIdsuperiorId
optional
NUMBER

The superior of this person (for organizational chart).

titleIdtitleId
optional
NUMBER

The person's title (e.g. 'Mr.', 'Mrs.', 'Dr.'). See Person title.

vatUidvatUid
optional
TEXT
MAX:32

The UID (VAT no.) of the company.

Endpoint

POST /api/v1/person/update.json
Person

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
Person

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
Person

Update attachments

Updates the file attachments of a person. Use the File API to upload a file and then use the file ID here. Returns either a success or error message.

Parameters

idid
mandatory
NUMBER

The ID of the entry.

fileIdsfileIds
optional
CSV

A list of file IDs, comma-separated. Leave empty to remove all attachments. Use the File API to upload a file and then use the file ID here.

Endpoint

POST /api/v1/person/update_attachments.json
Person  

Category

The following API endpoints are for managing person categories (e.g. 'Customers', 'Vendors', 'Employees').

Person Category

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
Person Category

List categories

Returns a list of all categories.

Endpoint

GET /api/v1/person/category/list.json
Person Category

Get tree of categories

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

Parameters

idid
optional
NUMBER

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

Endpoint

GET /api/v1/person/category/tree.json
Person Category

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.

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>

discountPercentagediscountPercentage
optional
NUMBER
MIN:0.0
MAX:100.0

Discount percentage for people in this category, which may be used for orders.

parentIdparentId
optional
NUMBER

The ID of the parent category.

sequenceNrIdsequenceNrId
optional
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
Person Category

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.

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>

discountPercentagediscountPercentage
optional
NUMBER
MIN:0.0
MAX:100.0

Discount percentage for people in this category, which may be used for orders.

parentIdparentId
optional
NUMBER

The ID of the parent category.

sequenceNrIdsequenceNrId
optional
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
Person Category

Delete categories

Deletes one or multiple existing categories. 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
Person  

Import

The following API endpoints are for importing people from a file, either a vCard, Excel or CSV file.

Person Import

Create import

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

Parameters

fileIdfileId
mandatory
NUMBER

File to import. Valid formats: vCard, Excel and CSV. Max. size: 5 MB. Use the File API to upload a file and then use the file ID here.

categoryIdcategoryId
optional
NUMBER

Category for all new people, overriding imported categories.

Endpoint

POST /api/v1/person/import/create.json
Person Import

Define mapping

Defines the mapping from Excel / CSV column header names to CashCtrl fields. This step is not needed for vCards. See List mapping fields endpoint for a list of field names. Returns either a success or multiple error messages (for each issue).

Parameters

idid
mandatory
NUMBER

Import session ID from the Create endpoint.

mappingmapping
mandatory
JSON

Mapping from columns (Excel/CSV) to fields in CashCtrl.

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

fromfrom
mandatory
TEXT

Column header name in Excel/CSV.

toto
mandatory
TEXT

Field name in CashCtrl. See List mapping fields endpoint for a list of field names.

Endpoint

POST /api/v1/person/import/mapping.json
Person Import

List mapping fields

Lists the fields available in CashCtrl for mapping. Used in the Define mapping endpoint.

Endpoint

GET /api/v1/person/import/mapping_combo.json
Person Import

Preview import

Previews the imported people. Returns a list of people that will be imported. This step can be omitted.

Parameters

idid
mandatory
NUMBER

Import session ID from the Create endpoint.

Endpoint

GET /api/v1/person/import/preview.json
Person Import

Execute import

Executes the importing of people from the import session.

Parameters

idid
mandatory
NUMBER

Import session ID from the Create endpoint.

indexesindexes
optional
CSV

Index numbers of people to import, comma-separated. All other people are ignored. You can get the indexes from the JSON response of the Preview endpoint. Omit this parameter to import all people.

Endpoint

POST /api/v1/person/import/execute.json
Person  

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.

Person Title

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
Person Title

List titles

Returns a list of all titles.

Endpoint

GET /api/v1/person/title/list.json
Person Title

Create title

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

Parameters

namename
mandatory
TEXT
MAX:50

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
optional
TEXT

The person's biological gender (male or female). Possible values: MALE, FEMALE.

sentencesentence
optional
TEXT
MAX:250

The letter salutation (e.g. 'Dear Mr.', etc.). May be used in mail.

Endpoint

POST /api/v1/person/title/create.json
Person Title

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:50

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
optional
TEXT

The person's biological gender (male or female). Possible values: MALE, FEMALE.

sentencesentence
optional
TEXT
MAX:250

The letter salutation (e.g. 'Dear Mr.', etc.). May be used in mail.

Endpoint

POST /api/v1/person/title/update.json
Person Title

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
 

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.

Report

Get tree of reports

Returns a tree of all instanced reports containing sets and elements.

Endpoint

GET /api/v1/report/tree.json
Report  

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.

Report Element

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
Report Element

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: JOURNAL, BALANCE, PLS, STAGGERED, COST_CENTER_PLS, COST_CENTER_BALANCE, COST_CENTER_ALLOCATION, COST_CENTER_TARGET, COST_CENTER_STATEMENTS, CHART_OF_ACCOUNTS, OPEN_DEBTORS, OPEN_CREDITORS, ORG_CHART, SALES_TAX, TARGET, RESULT_BY_ARTICLE_PER_PERSON, EXPENSE_BY_PERSON, REVENUE_BY_PERSON, REVENUE_BY_RESPONSIBLE_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.

columnscolumns
optional
JSON

Columns to display, for reports with dynamic columns (not every report).

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

titletitle
mandatory
TEXT

The title / heading of the column.

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>

calculationcalculation
optional
TEXT

The value of a custom column can be calculated with variables from other columns. Example: "$price * $quantity". Only if fieldName is empty, ignored otherwise.

fieldNamefieldName
optional
TEXT

Name of an existing field (e.g. 'firstName', 'lastName') or a custom field (e.g. 'customField24'). Leave empty to create a custom calculation column.

variablevariable
optional
TEXT

An optional variable name for use in further calculations. Must be alphanumeric and start with a '$'. Example: $myVariable. Only if fieldName is empty, ignored otherwise.

configconfig
optional
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 {...}.

fileIdfileId
optional
NUMBER

File associated with the report element (e.g. image for the 'Text & Image' report).

isHideTitleisHideTitle
optional
BOOLEAN

Hide title of the report. Defaults to false. Possible values: true, false.

isPageBreakisPageBreak
optional
BOOLEAN

Page break before the report (for PDF). Defaults to false. Possible values: true, false.

namename
optional
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
optional
NUMBER

Optional ID of a report set, to include this element in the set.

texttext
optional
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
Report Element

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: JOURNAL, BALANCE, PLS, STAGGERED, COST_CENTER_PLS, COST_CENTER_BALANCE, COST_CENTER_ALLOCATION, COST_CENTER_TARGET, COST_CENTER_STATEMENTS, CHART_OF_ACCOUNTS, OPEN_DEBTORS, OPEN_CREDITORS, ORG_CHART, SALES_TAX, TARGET, RESULT_BY_ARTICLE_PER_PERSON, EXPENSE_BY_PERSON, REVENUE_BY_PERSON, REVENUE_BY_RESPONSIBLE_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.

columnscolumns
optional
JSON

Columns to display, for reports with dynamic columns (not every report).

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

titletitle
mandatory
TEXT

The title / heading of the column.

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>

calculationcalculation
optional
TEXT

The value of a custom column can be calculated with variables from other columns. Example: "$price * $quantity". Only if fieldName is empty, ignored otherwise.

fieldNamefieldName
optional
TEXT

Name of an existing field (e.g. 'firstName', 'lastName') or a custom field (e.g. 'customField24'). Leave empty to create a custom calculation column.

variablevariable
optional
TEXT

An optional variable name for use in further calculations. Must be alphanumeric and start with a '$'. Example: $myVariable. Only if fieldName is empty, ignored otherwise.

configconfig
optional
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 {...}.

fileIdfileId
optional
NUMBER

File associated with the report element (e.g. image for the 'Text & Image' report).

isHideTitleisHideTitle
optional
BOOLEAN

Hide title of the report. Defaults to false. Possible values: true, false.

isPageBreakisPageBreak
optional
BOOLEAN

Page break before the report (for PDF). Defaults to false. Possible values: true, false.

namename
optional
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
optional
NUMBER

Optional ID of a report set, to include this element in the set.

texttext
optional
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
Report Element

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
Report Element

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
optional
BOOLEAN

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

Endpoint

POST /api/v1/report/element/reorder.json
Report Element

Read JSON data

Returns the JSON data of a single element by ID for the given time period.

Parameters

elementIdelementId
mandatory
NUMBER

The ID of the element.

endDateendDate
optional
DATE

The end date of the report period.

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

fiscalPeriodfiscalPeriod
optional
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
optional
TEXT

The language of the report.

sortsort
optional
TEXT

The column to sort the list by.

startDatestartDate
optional
DATE

The start date of the report period.

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

Endpoint

GET /api/v1/report/element/data.json
Report Element

Read HTML data

Returns the HTML data of a single element by ID for the given time period.

Parameters

elementIdelementId
mandatory
NUMBER

The ID of the element.

endDateendDate
optional
DATE

The end date of the report period.

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

fiscalPeriodfiscalPeriod
optional
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
optional
TEXT

The language of the report.

sortsort
optional
TEXT

The column to sort the list by.

startDatestartDate
optional
DATE

The start date of the report period.

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

Endpoint

GET /api/v1/report/element/data.html
Report Element

Read meta data

Returns the JSON 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
optional
DATE

The end date of the report period.

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

fiscalPeriodfiscalPeriod
optional
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
optional
TEXT

The language of the report.

sortsort
optional
TEXT

The column to sort the list by.

startDatestartDate
optional
DATE

The start date of the report period.

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

Endpoint

GET /api/v1/report/element/meta.json
Report Element

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
optional
DATE

The end date of the report period.

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

fiscalPeriodfiscalPeriod
optional
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
optional
TEXT

The language of the report.

sortsort
optional
TEXT

The column to sort the list by.

startDatestartDate
optional
DATE

The start date of the report period.

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

Endpoint

GET /api/v1/report/element/download.pdf
Report Element

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
optional
DATE

The end date of the report period.

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

fiscalPeriodfiscalPeriod
optional
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
optional
TEXT

The language of the report.

sortsort
optional
TEXT

The column to sort the list by.

startDatestartDate
optional
DATE

The start date of the report period.

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

Endpoint

GET /api/v1/report/element/download.csv
Report Element

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
optional
DATE

The end date of the report period.

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

fiscalPeriodfiscalPeriod
optional
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
optional
TEXT

The language of the report.

sortsort
optional
TEXT

The column to sort the list by.

startDatestartDate
optional
DATE

The start date of the report period.

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

Endpoint

GET /api/v1/report/element/download.xlsx
Report  

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.

Report Set

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
Report Set

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
optional
JSON

Configuration options.

This is a JSON object {...} with the following parameters:

isDisplayFooterisDisplayFooter
optional
BOOLEAN

Display the footer on the PDF? Defaults to true. Possible values: true, false.

isDisplayHeaderisDisplayHeader
optional
BOOLEAN

Display the header on the PDF? Defaults to true. Possible values: true, false.

isDisplayLogoisDisplayLogo
optional
BOOLEAN

Display the logo? Defaults to true. Possible values: true, false.

isDisplayPeriodInTitleisDisplayPeriodInTitle
optional
BOOLEAN

Display the time period in the title? Defaults to true. Possible values: true, false.

isDisplayTitleisDisplayTitle
optional
BOOLEAN

Display the title? Defaults to true. Possible values: true, false.

locationIdlocationId
optional
NUMBER

The location to be used for the logo and relevant placeholders in the text.

logoHeightlogoHeight
optional
NUMBER

The height of the logo in centimeters, as displayed on the report document (PDF).

pageSizepageSize
optional
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.

responsiblePersonIdresponsiblePersonId
optional
NUMBER

The responsible person (used for placeholders in the text).

texttext
optional
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
Report Set

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
optional
JSON

Configuration options.

This is a JSON object {...} with the following parameters:

isDisplayFooterisDisplayFooter
optional
BOOLEAN

Display the footer on the PDF? Defaults to true. Possible values: true, false.

isDisplayHeaderisDisplayHeader
optional
BOOLEAN

Display the header on the PDF? Defaults to true. Possible values: true, false.

isDisplayLogoisDisplayLogo
optional
BOOLEAN

Display the logo? Defaults to true. Possible values: true, false.

isDisplayPeriodInTitleisDisplayPeriodInTitle
optional
BOOLEAN

Display the time period in the title? Defaults to true. Possible values: true, false.

isDisplayTitleisDisplayTitle
optional
BOOLEAN

Display the title? Defaults to true. Possible values: true, false.

locationIdlocationId
optional
NUMBER

The location to be used for the logo and relevant placeholders in the text.

logoHeightlogoHeight
optional
NUMBER

The height of the logo in centimeters, as displayed on the report document (PDF).

pageSizepageSize
optional
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.

responsiblePersonIdresponsiblePersonId
optional
NUMBER

The responsible person (used for placeholders in the text).

texttext
optional
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
Report Set

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
Report Set

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
optional
BOOLEAN

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

Endpoint

POST /api/v1/report/set/reorder.json
Report Set

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
optional
DATE

The end date of the report period.

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

fiscalPeriodfiscalPeriod
optional
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
optional
TEXT

The language of the report.

sortsort
optional
TEXT

The column to sort the list by.

startDatestartDate
optional
DATE

The start date of the report period.

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

Endpoint

GET /api/v1/report/set/meta.json
Report Set

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
optional
DATE

The end date of the report period.

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

fiscalPeriodfiscalPeriod
optional
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
optional
TEXT

The language of the report.

sortsort
optional
TEXT

The column to sort the list by.

startDatestartDate
optional
DATE

The start date of the report period.

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

Endpoint

GET /api/v1/report/set/download.pdf
Report Set

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
optional
DATE

The end date of the report period.

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

fiscalPeriodfiscalPeriod
optional
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
optional
TEXT

The language of the report.

sortsort
optional
TEXT

The column to sort the list by.

startDatestartDate
optional
DATE

The start date of the report period.

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

Endpoint

GET /api/v1/report/set/download.csv
Report Set

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
optional
DATE

The end date of the report period.

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

fiscalPeriodfiscalPeriod
optional
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
optional
TEXT

The language of the report.

sortsort
optional
TEXT

The column to sort the list by.

startDatestartDate
optional
DATE

The start date of the report period.

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

Endpoint

GET /api/v1/report/set/download.xlsx
Report Set

Download annual report

Downloads the PDF file for the annual report (balance sheet and profit and loss statement by default).

Parameters

fiscalPeriodIdfiscalPeriodId
optional
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