API docs by Redocly

De Roos API (1.1.0)

Download OpenAPI specification:

De Roos: support@eenvoudigfactureren.freshdesk.com URL: https://deroos.dkpa.be

OpenAPI description for the v1 REST API.

The De Roos API provides programmatic access to invoices, clients, payments, documents and bookkeeping workflows.

It can be used to build custom integrations, automations, dashboards, AI assistants and accounting workflows on top of the De Roos platform.

All endpoints require authentication using API credentials generated within the De Roos application.

See the API changelog for changes that can affect API integrations.

Getting Started

The De Roos API allows developers to integrate invoicing, clients, bookkeeping workflows and financial data directly into their own applications and automations.

The API follows REST-style principles and primarily exchanges data using JSON. XML responses remain available for backwards compatibility, but JSON is strongly recommended for all modern integrations.

Base URL

Current environment:

https://deroos.dkpa.be/api/v1

Authentication

All API requests require authentication.

The API supports:

  • API key authentication
  • HTTP Basic authentication
  • OAuth2 authentication

API credentials can be generated within the De Roos application.

Response Formats

This specification focuses on JSON request and response formats. While XML remains available for backwards compatibility, JSON is recommended for all new integrations. Set Accept: application/json explicitly when consuming the API, because requests without an explicit response format may still default to XML for backwards compatibility.

The API supports multiple response formats:

  • JSON
  • XML
  • CSV
  • HTML (limited endpoints)

JSON is recommended for all API integrations.

Preferred approach:

Accept: application/json

Some endpoints also support the format query parameter:

?format=json

If no format is explicitly specified, endpoints default to XML for backwards compatibility.

Pagination

Collection endpoints support pagination using the following parameters:

Parameter Description
skip Number of records to skip
take Maximum number of records to return

Example:

GET /clients?skip=0&take=100

Sorting

Many collection endpoints support sorting using the sort parameter.

Examples:

?sort=name
?sort=-created_at
?sort=name,-created_at

Use - before a field name for descending order.

Filtering

Many list endpoints support filtering on top-level fields using the filter parameter.

Syntax:

field operator value

Supported operators:

Operator Alternative operator Description
= __eq__ Equals
!= __ne__ Not equals
<= __le__ Less than or equal
>= __ge__ Greater than or equal
< __lt__ Less than
> __gt__ Greater than
=~ __ct__ Contains

Examples:

?filter=city__eq__Brussels
?filter=status%3Dpaid
?filter=total%3E100

Multiple filters can typically be combined using commas.

Field Selection

To reduce payload size and improve performance, many endpoints support field selection using the fields parameter.

Example:

?fields=name,email

This returns only the requested fields in the response.

Some endpoints support free-text searching using the search parameter.

Example:

?search=restaurant

Search terms should be URL-encoded when necessary.

Errors

Errors are returned using standard HTTP status codes.

Typical responses include:

Status Meaning
200 Success
201 Resource created
400 Invalid request
401 Authentication required
403 Access denied
404 Resource not found
422 Validation error
500 Internal server error

Rate Limits

Clients should avoid excessive request rates and unnecessary polling.

Where possible:

  • use pagination
  • request only required fields
  • cache responses
  • avoid repeated full synchronizations

Recommendations

For the best integration experience:

  • Prefer JSON responses
  • Always send Accept: application/json
  • Use field selection to minimize payload size
  • Use pagination for large datasets
  • Avoid relying on undocumented response fields
  • Treat unknown properties as forward-compatible additions

Clients

List clients

Supports JSON, XML, CSV, and HTML responses for client listings. Prefer Accept: application/json for API usage. If no format is specified the API defaults to XML for backwards compatibility.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1
count
string

Presence flag that switches the request to count mode. Trigger it by sending ?count without a value.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
Example
[
  • {
    }
]

Create a client

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
external_client_id
string

External client identifier from a third-party system.

number
string

Optional client number.

name
required
string

Client name.

attention
string

Attention line for the client.

street
string

Street and house number of the billing address.

street2
string

Second billing address line.

postal_code
string

Postal code of the billing address.

city
string

City of the billing address.

country
string

Country name. Prefer country_code when available.

country_code
string

Two-letter uppercase country code of the billing address.

object

Delivery address of the client.

object

Site or work location address of the client.

tax_code
string

VAT number of the client.

boolean or string

Marks the VAT number registration as pending.

company_id
string

Company registration number of the client.

peppol_id
string

Peppol identifier of the client.

email_address
string

Primary email address of the client.

phone_number
string

Primary phone number of the client.

website
string
Deprecated

Website URL of the client.

private_note
string

Private internal note in plain text.

private_note_html
string

Private internal note in HTML format.

default_days_invoice_due
integer

Default payment term in days for new invoices.

default_days_quote_valid
integer

Default validity period in days for new quotes.

default_tax_category
integer
Enum: 0 1 2 3

Default VAT category for new documents.

default_tax_category_special_status
string

VAT exemption code used together with default_tax_category 0.

default_tax_country_code
string

ISO country code used for OSS VAT handling.

default_discount_percentage
number

Default discount percentage for new documents.

boolean or string

Enables cash discount by default for new invoices.

default_cash_discount_percentage
number

Default cash discount percentage for new invoices.

default_cash_discount_days_valid
integer

Default validity period in days for the cash discount.

default_structured_message
string

Default structured message for new invoices.

boolean or string

Enables automatic reminders by default for new invoices.

default_language
string
Enum: "" "dutch" "french" "english" "german"

Default language for new documents. An empty string uses the account language.

default_currency
string

Default currency code for new documents.

default_note
string

Default plain-text note added to new documents.

default_note_html
string

Default HTML note added to new documents.

default_note_position
string
Enum: "top" "bottom" "replace"

Position of the default note relative to the account's standard note.

default_invoices_layout_id
integer

Default layout id for new invoices.

default_receipts_layout_id
integer

Default layout id for new receipts.

default_quotes_layout_id
integer

Default layout id for new quotes.

default_orders_layout_id
integer

Default layout id for new orders.

default_paymentrequests_layout_id
integer

Default layout id for new payment requests.

default_deliveries_layout_id
integer

Default layout id for new deliveries.

default_customdocuments_layout_id
integer

Default layout id for new custom documents.

object

SEPA direct debit mandate information for this client.

Array of objects (CustomValueWrite)

Extra custom field values for this client.

Responses

Request samples

Content type
application/json
{
  • "external_client_id": "CRM-00092",
  • "number": "C-00092",
  • "name": "Acme BV",
  • "attention": "Finance department",
  • "street": "Industrielaan 15",
  • "street2": "Gebouw B",
  • "postal_code": "9000",
  • "city": "Gent",
  • "country_code": "BE",
  • "tax_code": "BE0123456789",
  • "email_address": "boekhouding@acme.example",
  • "phone_number": "+3291234567",
  • "default_days_invoice_due": 30,
  • "default_language": "dutch"
}

Response samples

Content type
application/json
{
  • "success": "client created",
  • "uri": "https://deroos.dkpa.be/api/v1/clients/92",
  • "client_id": 92
}

Bulk process clients

Sends the bulk client flow through the regular /clients API operation.

You can use the same bulk payload in two ways:

  • send it to /clients with header X-Action: bulk
  • send it to /clients/bulk without that header

The X-Action: bulk header is optional on /clients/bulk.

Send at most 100 clients per call. Processing is atomic: if one item fails, no clients are created or updated.

Include client_id to partially update an existing client. Omitted fields are left unchanged, matching Partially update a client. Omit client_id to create a new client.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

X-Action
string
Value: "bulk"

Action override used by the implementation for bulk operations.

Request Body schema: application/json
required
required
Array of objects (ClientBulkItem) [ 1 .. 100 ] items

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "success": "clients processed"
}

Batch process clients

Processes a list of batch actions.

This endpoint currently supports only delete actions with a required client_id. Send X-Document-Persistence: enforce to prevent deleting clients that still have linked documents or projects.

Processing is atomic: if one action fails, no clients are deleted.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

X-Document-Persistence
string
Value: "enforce"

Optional delete safety mode. Send enforce to prevent removing clients that still have linked documents or projects.

Request Body schema: application/json
required
required
Array of objects (ClientBatchDeleteAction) [ 1 .. 100 ] items

Responses

Request samples

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

Response samples

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

Get a client

Supports JSON, XML, CSV, and HTML responses for a single client resource. Prefer Accept: application/json for API usage. If no format is specified the API defaults to XML for backwards compatibility.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
{
  • "client_id": 92,
  • "uri": "https://deroos.dkpa.be/api/v1/clients/92",
  • "external_client_id": "CRM-00092",
  • "number": "C-00092",
  • "name": "Acme BV",
  • "attention": "Finance department",
  • "street": "Industrielaan 15",
  • "street2": "Gebouw B",
  • "postal_code": "9000",
  • "city": "Gent",
  • "country": "Belgium",
  • "country_code": "BE",
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "tax_code": "BE0123456789",
  • "tax_code_registration_pending": false,
  • "company_id": "0123456789",
  • "peppol_id": "0208:0123456789",
  • "email_address": "boekhouding@acme.example",
  • "phone_number": "+3291234567",
  • "state": "active",
  • "private_note": "Pays on time.",
  • "private_note_html": "<p>Pays on time.</p>",
  • "last_activity": "2026-05-28 11:33:45",
  • "default_days_invoice_due": 30,
  • "default_days_quote_valid": 14,
  • "default_tax_category": 1,
  • "default_discount_percentage": 5,
  • "default_cash_discount_active": false,
  • "default_cash_discount_percentage": 1.5,
  • "default_cash_discount_days_valid": 8,
  • "default_structured_message": "342485986564",
  • "default_automatic_reminders": true,
  • "default_language": "dutch",
  • "default_currency": "EUR",
  • "default_note": "Preferred customer",
  • "default_note_html": "<p>Preferred customer</p>",
  • "default_note_position": "replace",
  • "default_invoices_layout_id": 8001,
  • "default_quotes_layout_id": 8002,
  • "default_paymentrequests_layout_id": 8003,
  • "sepa_collection": {
    },
  • "invoice_count": 12,
  • "receipt_count": 2,
  • "quote_count": 1,
  • "order_count": 0,
  • "paymentrequest_count": 3,
  • "delivery_count": 0,
  • "customdocument_count": 0,
  • "subscription_count": 1,
  • "project_count": 4,
  • "custom_values": [
    ],
  • "contacts": [
    ]
}

Partially update a client

Only the fields you send are updated. Any fields you omit keep their existing value.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
external_client_id
string

External client identifier from a third-party system.

number
string

Optional client number.

name
required
string

Client name.

attention
string

Attention line for the client.

street
string

Street and house number of the billing address.

street2
string

Second billing address line.

postal_code
string

Postal code of the billing address.

city
string

City of the billing address.

country
string

Country name. Prefer country_code when available.

country_code
string

Two-letter uppercase country code of the billing address.

object

Delivery address of the client.

object

Site or work location address of the client.

tax_code
string

VAT number of the client.

boolean or string

Marks the VAT number registration as pending.

company_id
string

Company registration number of the client.

peppol_id
string

Peppol identifier of the client.

email_address
string

Primary email address of the client.

phone_number
string

Primary phone number of the client.

website
string
Deprecated

Website URL of the client.

private_note
string

Private internal note in plain text.

private_note_html
string

Private internal note in HTML format.

default_days_invoice_due
integer

Default payment term in days for new invoices.

default_days_quote_valid
integer

Default validity period in days for new quotes.

default_tax_category
integer
Enum: 0 1 2 3

Default VAT category for new documents.

default_tax_category_special_status
string

VAT exemption code used together with default_tax_category 0.

default_tax_country_code
string

ISO country code used for OSS VAT handling.

default_discount_percentage
number

Default discount percentage for new documents.

boolean or string

Enables cash discount by default for new invoices.

default_cash_discount_percentage
number

Default cash discount percentage for new invoices.

default_cash_discount_days_valid
integer

Default validity period in days for the cash discount.

default_structured_message
string

Default structured message for new invoices.

boolean or string

Enables automatic reminders by default for new invoices.

default_language
string
Enum: "" "dutch" "french" "english" "german"

Default language for new documents. An empty string uses the account language.

default_currency
string

Default currency code for new documents.

default_note
string

Default plain-text note added to new documents.

default_note_html
string

Default HTML note added to new documents.

default_note_position
string
Enum: "top" "bottom" "replace"

Position of the default note relative to the account's standard note.

default_invoices_layout_id
integer

Default layout id for new invoices.

default_receipts_layout_id
integer

Default layout id for new receipts.

default_quotes_layout_id
integer

Default layout id for new quotes.

default_orders_layout_id
integer

Default layout id for new orders.

default_paymentrequests_layout_id
integer

Default layout id for new payment requests.

default_deliveries_layout_id
integer

Default layout id for new deliveries.

default_customdocuments_layout_id
integer

Default layout id for new custom documents.

object

SEPA direct debit mandate information for this client.

Array of objects (CustomValueWrite)

Extra custom field values for this client.

Responses

Request samples

Content type
application/json
{
  • "external_client_id": "CRM-00092",
  • "number": "C-00092",
  • "name": "Acme BV",
  • "attention": "Finance department",
  • "street": "Industrielaan 15",
  • "street2": "Gebouw B",
  • "postal_code": "9000",
  • "city": "Gent",
  • "country_code": "BE",
  • "tax_code": "BE0123456789",
  • "email_address": "boekhouding@acme.example",
  • "phone_number": "+3291234567",
  • "default_days_invoice_due": 30,
  • "default_language": "dutch"
}

Response samples

Content type
application/json
{
  • "success": "client updated"
}

Update a client

Replaces the client data with the values from the request body.

Fields you do not send are not preserved and may be reset to their default or empty value. Use Partially update a client if you only want to change specific fields and keep the others unchanged.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
external_client_id
string

External client identifier from a third-party system.

number
string

Optional client number.

name
required
string

Client name.

attention
string

Attention line for the client.

street
string

Street and house number of the billing address.

street2
string

Second billing address line.

postal_code
string

Postal code of the billing address.

city
string

City of the billing address.

country
string

Country name. Prefer country_code when available.

country_code
string

Two-letter uppercase country code of the billing address.

object

Delivery address of the client.

object

Site or work location address of the client.

tax_code
string

VAT number of the client.

boolean or string

Marks the VAT number registration as pending.

company_id
string

Company registration number of the client.

peppol_id
string

Peppol identifier of the client.

email_address
string

Primary email address of the client.

phone_number
string

Primary phone number of the client.

website
string
Deprecated

Website URL of the client.

private_note
string

Private internal note in plain text.

private_note_html
string

Private internal note in HTML format.

default_days_invoice_due
integer

Default payment term in days for new invoices.

default_days_quote_valid
integer

Default validity period in days for new quotes.

default_tax_category
integer
Enum: 0 1 2 3

Default VAT category for new documents.

default_tax_category_special_status
string

VAT exemption code used together with default_tax_category 0.

default_tax_country_code
string

ISO country code used for OSS VAT handling.

default_discount_percentage
number

Default discount percentage for new documents.

boolean or string

Enables cash discount by default for new invoices.

default_cash_discount_percentage
number

Default cash discount percentage for new invoices.

default_cash_discount_days_valid
integer

Default validity period in days for the cash discount.

default_structured_message
string

Default structured message for new invoices.

boolean or string

Enables automatic reminders by default for new invoices.

default_language
string
Enum: "" "dutch" "french" "english" "german"

Default language for new documents. An empty string uses the account language.

default_currency
string

Default currency code for new documents.

default_note
string

Default plain-text note added to new documents.

default_note_html
string

Default HTML note added to new documents.

default_note_position
string
Enum: "top" "bottom" "replace"

Position of the default note relative to the account's standard note.

default_invoices_layout_id
integer

Default layout id for new invoices.

default_receipts_layout_id
integer

Default layout id for new receipts.

default_quotes_layout_id
integer

Default layout id for new quotes.

default_orders_layout_id
integer

Default layout id for new orders.

default_paymentrequests_layout_id
integer

Default layout id for new payment requests.

default_deliveries_layout_id
integer

Default layout id for new deliveries.

default_customdocuments_layout_id
integer

Default layout id for new custom documents.

object

SEPA direct debit mandate information for this client.

Array of objects (CustomValueWrite)

Extra custom field values for this client.

Responses

Request samples

Content type
application/json
{
  • "external_client_id": "CRM-00092",
  • "number": "C-00092",
  • "name": "Acme BV",
  • "attention": "Finance department",
  • "street": "Industrielaan 15",
  • "street2": "Gebouw B",
  • "postal_code": "9000",
  • "city": "Gent",
  • "country_code": "BE",
  • "tax_code": "BE0123456789",
  • "email_address": "boekhouding@acme.example",
  • "phone_number": "+3291234567",
  • "default_days_invoice_due": 30,
  • "default_language": "dutch"
}

Response samples

Content type
application/json
{
  • "success": "client updated"
}

Delete a client

Warning: deleting a client also removes linked documents and projects.

Send X-Document-Persistence: enforce to prevent deleting a client that still has linked documents or projects.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

X-Document-Persistence
string
Value: "enforce"

Optional delete safety mode. Send enforce to prevent removing clients that still have linked documents or projects.

Responses

Response samples

Content type
application/json
{
  • "success": "client removed"
}

List client contacts

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a client contact

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
contact_name
required
string

Contact name or label.

email_address
string

Contact email address.

phone_number
string

Contact phone number.

Responses

Request samples

Content type
application/json
{
  • "contact_name": "Els Peeters",
  • "email_address": "els.peeters@acme.example",
  • "phone_number": "+32475123456"
}

Response samples

Content type
application/json
{
  • "success": "contact created",
  • "uri": "https://deroos.dkpa.be/api/v1/clients/92/contacts/14",
  • "contact_id": 14
}

Get a client contact

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
contactId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "contact_id": 14,
  • "uri": "https://deroos.dkpa.be/api/v1/clients/92/contacts/14",
  • "contact_name": "Els Peeters",
  • "email_address": "els.peeters@acme.example",
  • "phone_number": "+32475123456"
}

Partially update a client contact

Only the fields you send are updated. Any fields you omit keep their existing value.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
contactId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
contact_name
required
string

Contact name or label.

email_address
string

Contact email address.

phone_number
string

Contact phone number.

Responses

Request samples

Content type
application/json
{
  • "contact_name": "Els Peeters",
  • "email_address": "els.peeters@acme.example",
  • "phone_number": "+32475123456"
}

Response samples

Content type
application/json
{
  • "success": "contact updated"
}

Update a client contact

Replaces the client contact data with the values from the request body.

Fields you do not send are not preserved and may be reset to their default or empty value. Use Partially update a client contact if you only want to change specific fields and keep the others unchanged.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
contactId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
contact_name
required
string

Contact name or label.

email_address
string

Contact email address.

phone_number
string

Contact phone number.

Responses

Request samples

Content type
application/json
{
  • "contact_name": "Els Peeters",
  • "email_address": "els.peeters@acme.example",
  • "phone_number": "+32475123456"
}

Response samples

Content type
application/json
{
  • "success": "contact updated"
}

Delete a client contact

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
contactId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "contact removed"
}

List client details Deprecated

Deprecated. Prefer custom_values on the client resource for new integrations.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a client detail Deprecated

Deprecated. Prefer custom_values on the client resource for new integrations.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
name
required
string

Detail name.

value
required
string

Detail value.

Responses

Request samples

Content type
application/json
{
  • "name": "customer_group",
  • "value": "wholesale"
}

Response samples

Content type
application/json
{}

Get a client detail Deprecated

Deprecated. Prefer custom_values on the client resource for new integrations.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
detailId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "detail_id": 7,
  • "uri": "https://deroos.dkpa.be/api/v1/clients/92/details/7",
  • "name": "customer_group",
  • "value": "wholesale"
}

Partially update a client detail Deprecated

Deprecated. Prefer custom_values on the client resource for new integrations.

Only the fields you send are updated. Any fields you omit keep their existing value.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
detailId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
name
required
string

Detail name.

value
required
string

Detail value.

Responses

Request samples

Content type
application/json
{
  • "name": "customer_group",
  • "value": "wholesale"
}

Response samples

Content type
application/json
{
  • "success": "detail updated"
}

Update a client detail Deprecated

Deprecated. Prefer custom_values on the client resource for new integrations.

Replaces the client detail data with the values from the request body.

Fields you do not send are not preserved and may be reset to their default or empty value. Use Partially update a client detail if you only want to change specific fields and keep the others unchanged.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
detailId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
name
required
string

Detail name.

value
required
string

Detail value.

Responses

Request samples

Content type
application/json
{
  • "name": "customer_group",
  • "value": "wholesale"
}

Response samples

Content type
application/json
{
  • "success": "detail updated"
}

Delete a client detail Deprecated

Deprecated. Prefer custom_values on the client resource for new integrations.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
clientId
required
integer
detailId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "detail removed"
}

Invoices

List invoices

Supports fields, search, paging, sorting, and document-specific filters such as client, status, date, tags, or number. Response formats are limited to JSON, XML, CSV, and HTML on the collection endpoint.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1
count
string

Presence flag that switches the request to count mode. Trigger it by sending ?count without a value.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
Example
[
  • {
    }
]

Create an invoice

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
external_invoice_id
string

External identifier managed by the integrating system.

client_id
required
integer

Internal id of the client linked to the invoice.

client_name
string

Client name to store directly on the invoice.

client_attention
string

Attention line to store on the invoice.

layout_id
integer

Layout id to use when rendering the invoice.

number
string

Invoice number. If omitted, a new number is generated automatically. The value must be unique across all invoices in the account.

object

Billing address to store on the invoice.

object or null

Delivery address to store on the invoice.

object or null

Site or work location address to store on the invoice.

reference
string

Free reference stored on the invoice.

date
string <date>

Main invoice date. If omitted, the current date is used.

date_delivery
string <date>

Taxable date of the invoice. If omitted, it falls back to date.

status
string
Value: "concept"

Optional mode switch. Send concept to create an invoice concept instead of an open invoice.

days_due
integer

Payment term in days. If omitted, the client or account default is used. Use 0 when no due date should be set.

currency
string

ISO currency code used on the invoice.

exchange_rate
string

Exchange rate used to convert the invoice currency to EUR.

boolean or string

Whether VAT converted to EUR should be shown on the invoice.

language
string

Language used to render the invoice.

discount_percentage
number

Global discount percentage applied to the invoice.

item_discount
string
Enum: "none" "percentage" "amount"

How line discounts are represented on the invoice.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the invoice. Allowed values are item and total. The default is total.

boolean or string

Whether the supplied amounts already include VAT.

tax_rate_1
number

First VAT rate configured on the invoice.

tax_rate_2
number

Second VAT rate configured on the invoice.

tax_rate_3
number

Third VAT rate configured on the invoice.

note
string

Plain-text note shown on the invoice.

note_html
string

HTML version of the note shown on the invoice.

Array of objects (CustomValueWrite)

Custom field values to store on the invoice.

structured_message
string

Structured payment reference of the invoice.

boolean or string

Whether a structured payment reference should be generated automatically.

cash_discount_percentage
number

Financial discount percentage applied to the invoice.

cash_discount_days_valid
integer

Number of days the financial discount remains valid.

tax_country_code
string

ISO country code used for OSS VAT handling.

boolean or string

Whether automatic reminders should be enabled for the invoice.

outstanding_balance
number

Outstanding balance to store on the invoice.

Array of objects (DocumentFileWrite)

Files to attach to the invoice.

required
Array of objects or objects (DocumentItemWrite)

Invoice lines to store on the invoice.

Array of objects (PaymentWrite)

Payments to create together with the invoice.

Array of objects (InvoiceCostWrite)

Reminder costs to create together with the invoice.

Array of objects (RemarkWrite)

Remarks to create together with the invoice.

Responses

Request samples

Content type
application/json
{
  • "client_id": 92,
  • "external_invoice_id": "Invoice-2026-0001",
  • "layout_id": 8001,
  • "reference": "REF-1001",
  • "date": "2026-05-28",
  • "date_delivery": "2026-05-28",
  • "days_due": 30,
  • "currency": "EUR",
  • "language": "dutch",
  • "discount_percentage": 5,
  • "item_discount": "none",
  • "tax_calculation": "total",
  • "tax_included": "no",
  • "cash_discount_percentage": 2,
  • "cash_discount_days_valid": 8,
  • "tax_country_code": "BE",
  • "structured_message": "123456789012",
  • "automatic_reminders": "yes",
  • "note": "25 EUR kosten bij laattijdige betalingen.",
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "items": [
    ],
  • "files": [
    ],
  • "custom_values": [
    ],
  • "payments": [
    ],
  • "costs": [
    ],
  • "remarks": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "invoice created",
  • "invoice_id": 3003,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/3003"
}

Get an invoice

Supports JSON, XML, CSV, HTML, and PDF for a single invoice. The format query parameter additionally accepts ubl, efff, peppol, peppolbis3, and ublbe only on this endpoint.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
required
integer or string

Internal invoice id, or a +-separated list of invoice ids.

query Parameters
format
string
Enum: "xml" "json" "csv" "html" "pdf" "ubl" "efff" "peppol" "peppolbis3" "ublbe"

Optional response format override for a single invoice. Prefer the Accept header instead, typically Accept: application/json for API integrations.

Special formats:

  • pdf: returns a PDF file in binary format
  • ubl and ublbe: both return the invoice in UBL.BE format
  • peppol and peppolbis3: both return the invoice in standard Peppol BIS 3 format
  • efff: returns the deprecated eFFF format

All special formats above are only available when requesting one invoice.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html" "application/pdf"

Preferred way to request the response format for a single document resource. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility. application/pdf is only available when requesting one document.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
{
  • "invoice_id": 3003,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/3003",
  • "external_invoice_id": "Invoice-0983984",
  • "client_id": 1001,
  • "client_uri": "https://deroos.dkpa.be/api/v1/clients/1001",
  • "client_name": "IT Services BVBA",
  • "client_attention": "Dienst administratie",
  • "type": "invoice",
  • "number": "INV2012-001",
  • "layout_id": 8001,
  • "reference": "ID123456789",
  • "date": "2012-02-15",
  • "date_delivery": "2012-02-15",
  • "status": "open",
  • "days_due": 10,
  • "days_overdue": 0,
  • "date_overdue": "2012-02-25",
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "discount_percentage": 5,
  • "cash_discount_percentage": 2,
  • "cash_discount_days_valid": 8,
  • "cash_discount_date_valid": "2012-02-23",
  • "item_discount": "none",
  • "currency": "EUR",
  • "exchange_rate": "1",
  • "language": "dutch",
  • "tax_calculation": "total",
  • "tax_included": "no",
  • "items": [
    ],
  • "discount_total_without_tax": "10.00",
  • "total_refundable_deposit": "0.00",
  • "total_without_tax": "190.00",
  • "tax_rate_1": 21,
  • "total_tax_1": "42.00",
  • "tax_rate_2": 12,
  • "total_tax_2": "0.00",
  • "tax_rate_3": 6,
  • "total_tax_3": "0.00",
  • "discount_total_with_tax": "12.10",
  • "total_with_tax": "229.90",
  • "total_costs": "5.00",
  • "total_paid": "25.00",
  • "structured_message": "278781035591",
  • "automatic_reminders": true,
  • "note": "25 EUR kosten bij laattijdige betalingen.",
  • "note_html": "<p>25 EUR kosten bij laattijdige betalingen.</p>",
  • "last_activity": "2018-05-03 11:33:45",
  • "custom_values": [
    ],
  • "files": [
    ],
  • "tags": [
    ],
  • "payments": [
    ],
  • "costs": [
    ],
  • "remarks": [
    ],
  • "events": [
    ]
}

Partially update an invoice

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
external_invoice_id
string

External identifier managed by the integrating system.

client_id
integer

Internal id of the client linked to the invoice.

client_name
string

Client name to store directly on the invoice.

client_attention
string

Attention line to store on the invoice.

layout_id
integer

Layout id to use when rendering the invoice.

number
string

Invoice number. If omitted, a new number is generated automatically. The value must be unique across all invoices in the account.

object

Billing address to store on the invoice.

object or null

Delivery address to store on the invoice.

object or null

Site or work location address to store on the invoice.

reference
string

Free reference stored on the invoice.

date
string <date>

Main invoice date. If omitted, the current date is used.

date_delivery
string <date>

Taxable date of the invoice. If omitted, it falls back to date.

days_due
integer

Payment term in days. If omitted, the client or account default is used. Use 0 when no due date should be set.

currency
string

ISO currency code used on the invoice.

exchange_rate
string

Exchange rate used to convert the invoice currency to EUR.

boolean or string

Whether VAT converted to EUR should be shown on the invoice.

language
string

Language used to render the invoice.

discount_percentage
number

Global discount percentage applied to the invoice.

item_discount
string
Enum: "none" "percentage" "amount"

How line discounts are represented on the invoice.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the invoice. Allowed values are item and total. The default is total.

boolean or string

Whether the supplied amounts already include VAT.

tax_rate_1
number

First VAT rate configured on the invoice.

tax_rate_2
number

Second VAT rate configured on the invoice.

tax_rate_3
number

Third VAT rate configured on the invoice.

note
string

Plain-text note shown on the invoice.

note_html
string

HTML version of the note shown on the invoice.

Array of objects (CustomValueWrite)

Custom field values to store on the invoice.

structured_message
string

Structured payment reference of the invoice.

boolean or string

Whether a structured payment reference should be generated automatically.

cash_discount_percentage
number

Financial discount percentage applied to the invoice.

cash_discount_days_valid
integer

Number of days the financial discount remains valid.

tax_country_code
string

ISO country code used for OSS VAT handling.

boolean or string

Whether automatic reminders should be enabled for the invoice.

outstanding_balance
number

Outstanding balance to store on the invoice.

Array of objects (DocumentFileWrite)

Files to attach to the invoice.

Array of objects or objects (DocumentItemWrite)

Invoice lines to store on the invoice.

Array of objects (PaymentWrite)

Payments to create together with the invoice.

Array of objects (InvoiceCostWrite)

Reminder costs to create together with the invoice.

Array of objects (RemarkWrite)

Remarks to create together with the invoice.

Responses

Request samples

Content type
application/json
{
  • "reference": "REF-1001-UPDATED",
  • "date_delivery": "2026-05-30",
  • "note": "Updated remark for this invoice",
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update an invoice

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
external_invoice_id
string

External identifier managed by the integrating system.

client_id
integer

Internal id of the client linked to the invoice.

client_name
string

Client name to store directly on the invoice.

client_attention
string

Attention line to store on the invoice.

layout_id
integer

Layout id to use when rendering the invoice.

number
string

Invoice number. If omitted, a new number is generated automatically. The value must be unique across all invoices in the account.

object

Billing address to store on the invoice.

object or null

Delivery address to store on the invoice.

object or null

Site or work location address to store on the invoice.

reference
string

Free reference stored on the invoice.

date
string <date>

Main invoice date. If omitted, the current date is used.

date_delivery
string <date>

Taxable date of the invoice. If omitted, it falls back to date.

days_due
integer

Payment term in days. If omitted, the client or account default is used. Use 0 when no due date should be set.

currency
string

ISO currency code used on the invoice.

exchange_rate
string

Exchange rate used to convert the invoice currency to EUR.

boolean or string

Whether VAT converted to EUR should be shown on the invoice.

language
string

Language used to render the invoice.

discount_percentage
number

Global discount percentage applied to the invoice.

item_discount
string
Enum: "none" "percentage" "amount"

How line discounts are represented on the invoice.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the invoice. Allowed values are item and total. The default is total.

boolean or string

Whether the supplied amounts already include VAT.

tax_rate_1
number

First VAT rate configured on the invoice.

tax_rate_2
number

Second VAT rate configured on the invoice.

tax_rate_3
number

Third VAT rate configured on the invoice.

note
string

Plain-text note shown on the invoice.

note_html
string

HTML version of the note shown on the invoice.

Array of objects (CustomValueWrite)

Custom field values to store on the invoice.

structured_message
string

Structured payment reference of the invoice.

boolean or string

Whether a structured payment reference should be generated automatically.

cash_discount_percentage
number

Financial discount percentage applied to the invoice.

cash_discount_days_valid
integer

Number of days the financial discount remains valid.

tax_country_code
string

ISO country code used for OSS VAT handling.

boolean or string

Whether automatic reminders should be enabled for the invoice.

outstanding_balance
number

Outstanding balance to store on the invoice.

Array of objects (DocumentFileWrite)

Files to attach to the invoice.

Array of objects or objects (DocumentItemWrite)

Invoice lines to store on the invoice.

Array of objects (PaymentWrite)

Payments to create together with the invoice.

Array of objects (InvoiceCostWrite)

Reminder costs to create together with the invoice.

Array of objects (RemarkWrite)

Remarks to create together with the invoice.

Responses

Request samples

Content type
application/json
{
  • "external_invoice_id": "Invoice-2026-0001",
  • "client_id": 92,
  • "client_name": "ACME BV",
  • "client_attention": "Dienst administratie",
  • "layout_id": 8001,
  • "number": "INV2026-0001",
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "REF-1001",
  • "date": "2026-05-28",
  • "date_delivery": "2026-05-28",
  • "days_due": 30,
  • "currency": "EUR",
  • "exchange_rate": "1",
  • "show_tax_for_exchange_rate": "no",
  • "language": "dutch",
  • "discount_percentage": 5,
  • "item_discount": "none",
  • "tax_calculation": "total",
  • "tax_included": "no",
  • "tax_rate_1": 21,
  • "tax_rate_2": 12,
  • "tax_rate_3": 6,
  • "note": "25 EUR kosten bij laattijdige betalingen.",
  • "note_html": "<p>25 EUR kosten bij laattijdige betalingen.</p>",
  • "custom_values": [
    ],
  • "structured_message": "123456789012",
  • "generate_structured_message": "no",
  • "cash_discount_percentage": 2,
  • "cash_discount_days_valid": 8,
  • "tax_country_code": "BE",
  • "automatic_reminders": "yes",
  • "outstanding_balance": 179.9,
  • "files": [
    ],
  • "items": [
    ],
  • "payments": [
    ],
  • "costs": [
    ],
  • "remarks": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete an invoice

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List invoice items

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an invoice item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "item created",
  • "item_id": 4004,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/3003/items/4004"
}

Get an invoice item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "item_id": 3,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/items/3",
  • "type": "item",
  • "description": "Consulting",
  • "description_html": "<p>Consulting</p>",
  • "amount": "100.00",
  • "amount_with_tax": "121.00",
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "total_without_tax": "200.00",
  • "total_with_tax": "242.00",
  • "general_ledger_account": "700000",
  • "custom_values": [
    ]
}

Partially update an invoice item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "quantity": 3,
  • "description": "Updated line description"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update an invoice item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete an invoice item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List invoice payments

Returns the payments registered on the invoice.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an invoice payment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
One of
date
string <date>

Payment date in YYYY-MM-DD format.

amount
required
number

Payment amount.

method
string
Enum: "transfer" "cash" "debitcard" "creditcard" "directcollection" "online" "bancontact" "ideal" "giftcard" "bitcoin" "internal" "paypal" "payconiq" "cashdiscount" "difference" "ecocheque" ""

Payment method. Possible values are transfer, cash, debitcard, creditcard, directcollection, online, bancontact, ideal, giftcard, bitcoin, internal, paypal, payconiq, cashdiscount, difference, and ecocheque. Use an empty string when no method is stored.

description
string

Free description stored on the payment.

boolean or string

Whether the remaining open amount should be used. Allowed values are a boolean or yes/no.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-20",
  • "amount": 121,
  • "method": "transfer",
  • "description": "Payment received"
}

Response samples

Content type
application/json
{
  • "success": "payment created",
  • "payment_id": 9,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/payments/9"
}

Get an invoice payment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

paymentId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "payment_id": 9,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/payments/9",
  • "date": "2026-05-20",
  • "amount": 121,
  • "method": "transfer",
  • "description": "Advance payment",
  • "allocation_id": 123,
  • "banktransaction_id": 456,
  • "banktransaction_number": "2026/00012",
  • "source": "banktransaction"
}

Partially update an invoice payment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

paymentId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Payment date in YYYY-MM-DD format.

amount
number

Payment amount.

method
string
Enum: "transfer" "cash" "debitcard" "creditcard" "directcollection" "online" "bancontact" "ideal" "giftcard" "bitcoin" "internal" "paypal" "payconiq" "cashdiscount" "difference" "ecocheque" ""

Payment method. Possible values are transfer, cash, debitcard, creditcard, directcollection, online, bancontact, ideal, giftcard, bitcoin, internal, paypal, payconiq, cashdiscount, difference, and ecocheque. Use an empty string when no method is stored.

description
string

Free description stored on the payment.

boolean or string

Whether the remaining open amount should be used. Allowed values are a boolean or yes/no.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-20",
  • "amount": 121,
  • "method": "transfer",
  • "description": "Payment received"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update an invoice payment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

paymentId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Payment date in YYYY-MM-DD format.

amount
number

Payment amount.

method
string
Enum: "transfer" "cash" "debitcard" "creditcard" "directcollection" "online" "bancontact" "ideal" "giftcard" "bitcoin" "internal" "paypal" "payconiq" "cashdiscount" "difference" "ecocheque" ""

Payment method. Possible values are transfer, cash, debitcard, creditcard, directcollection, online, bancontact, ideal, giftcard, bitcoin, internal, paypal, payconiq, cashdiscount, difference, and ecocheque. Use an empty string when no method is stored.

description
string

Free description stored on the payment.

boolean or string

Whether the remaining open amount should be used. Allowed values are a boolean or yes/no.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-20",
  • "amount": 121,
  • "method": "transfer",
  • "description": "Payment received"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

List invoice remarks

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an invoice remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
One of
date
string <date>

Remark date in YYYY-MM-DD format.

description
required
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "remark created",
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5"
}

Get an invoice remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5",
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Partially update an invoice remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update an invoice remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete an invoice remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List invoice events

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an invoice event

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

eventId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
Example
{
  • "event_id": 17,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/events/17",
  • "date": "2026-05-21",
  • "type": "email sent",
  • "content": "Please find your invoice attached.",
  • "recipients": [
    ]
}

List invoice files

Files are attachments linked to the invoice.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

skip
integer >= 0
take
integer >= 1
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an invoice file

Files are attachments linked to the invoice.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42",
  • "filename": "terms.pdf",
  • "content_type": "application/pdf",
  • "role": "attachment",
  • "created": "2026-05-05 12:12:12"
}

Partially update an invoice file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update an invoice file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete an invoice file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Download an invoice file

Files are attachments linked to the invoice.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "error": "client_id unknown"
}

Upload an invoice attachment

Upload the attachment as multipart/form-data, not as a JSON request body. Files are attachments linked to the invoice.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: multipart/form-data
required
file
required
string <binary>
role
string
Enum: "attachment" "internal_document" "merged_document"

Functional role of the attachment. Possible values are attachment, internal_document, and merged_document.

Responses

Response samples

Content type
application/json
{
  • "success": "file created",
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42"
}

List invoice costs

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an invoice cost

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Date of the reminder cost in YYYY-MM-DD format.

description
string

Description of the reminder cost.

amount
number

Amount of the reminder cost.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-28",
  • "description": "First reminder fee",
  • "amount": 15
}

Response samples

Content type
application/json
{
  • "success": "cost created",
  • "cost_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/costs/42"
}

Get an invoice cost

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

costId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "cost_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/costs/42",
  • "date": "2026-05-28",
  • "description": "First reminder fee",
  • "amount": "15.00"
}

Partially update an invoice cost

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

costId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Date of the reminder cost in YYYY-MM-DD format.

description
string

Description of the reminder cost.

amount
number

Amount of the reminder cost.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-28",
  • "description": "First reminder fee",
  • "amount": 15
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update an invoice cost

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

costId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Date of the reminder cost in YYYY-MM-DD format.

description
string

Description of the reminder cost.

amount
number

Amount of the reminder cost.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-28",
  • "description": "First reminder fee",
  • "amount": 15
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete an invoice cost

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

costId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Send an invoice by email

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
required
Array of strings or integers non-empty

Recipients. Each value can be an email address, a client contact id, or one of main_contact, first_contact, all_contacts, myself, or account_owner.

string or (Array of strings or integers)
Deprecated

Deprecated alias for recipients. Use recipients in new integrations.

subject
string

Email subject. If omitted, the configured default subject is used.

message
string

Plain-text email message. If omitted, the configured default message is used.

message_html
string

HTML email message. Use this instead of message when sending rich text.

Array of objects

Additional temporary uploads to attach. Upload each file first through POST /uploads and provide its returned upload_id here.

Responses

Request samples

Content type
application/json
{
  • "recipients": [
    ],
  • "subject": "Document 2026-0001",
  • "message": "Please find your document attached."
}

Response samples

Content type
application/json
{
  • "success": "email sent",
  • "email_addresses": [
    ]
}

Send an invoice to customer

Try the supplied delivery methods in their JSON member order and stop after the first successful delivery. Available methods are email, Peppol, and postal mail.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
required
object non-empty

Delivery methods to try, in the order in which their keys occur in the JSON object. The API stops after the first successful method. Supported methods are email, peppol, and postalmail.

Peppol requires an active Peppol integration. Postal mail requires a Mail-IT-Wize integration.

Responses

Request samples

Content type
application/json
{
  • "methods": {
    }
}

Response samples

Content type
application/json
Example
{
  • "success": "email sent",
  • "email_addresses": [
    ]
}

Send an invoice by postal mail

A Mail-IT-Wize integration must be configured before this call can be used.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
address_type
string
Default: "billing"
Enum: "billing" "delivery" "site"

Address of the document recipient to use for postal delivery.

send_registered
boolean
Default: false

Set to true to send the postal mail as registered mail.

document_type
string
Default: "document"
Enum: "document" "duplicate" "reminder" "reminder_summary"

Document variant to send.

Responses

Request samples

Content type
application/json
{
  • "address_type": "billing",
  • "send_registered": true,
  • "document_type": "document"
}

Response samples

Content type
application/json
{
  • "success": "sent to post office"
}

Send an invoice to accounting

An accounting integration must be configured before this call can be used.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
mark_as_sent
boolean
Default: false

Set to true to mark the invoice as sent without transmitting it to the configured accounting integration.

Responses

Request samples

Content type
application/json
{
  • "mark_as_sent": false
}

Response samples

Content type
application/json
{
  • "success": "invoice sent"
}

Send an invoice through Peppol

The Peppol integration must be configured and activated before this call can be used.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
optional
purchase_order
string

Optional purchase order reference to include in the Peppol document.

Array of objects

Optional temporary uploads to include with the Peppol delivery. Upload each file first through POST /uploads.

Responses

Request samples

Content type
application/json
{
  • "purchase_order": "PO-7781",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "invoice sent"
}

Request a direct collection for an invoice

Request a direct debit for the outstanding invoice amount.

A Mollie integration must be configured before this call can be used. The client must already have given permission for direct collection through a valid Mollie mandate.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "direct collection requested"
}

Receipts

List receipts

Supports fields, search, paging, sorting, and document-specific filters such as client, status, date, tags, or number. Response formats are limited to JSON, XML, CSV, and HTML on the collection endpoint.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1
count
string

Presence flag that switches the request to count mode. Trigger it by sending ?count without a value.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
Example
[
  • {
    }
]

Create a receipt

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
external_receipt_id
string

External identifier managed by the integrating system.

client_id
required
integer

Internal id of the client linked to the receipt.

client_name
string

Client name to store directly on the receipt.

client_attention
string

Attention line to store on the receipt.

layout_id
integer

Layout id to use when rendering the receipt.

number
string

Receipt number. If omitted, a number is generated automatically.

object

Billing address to store on the receipt.

object or null

Delivery address to store on the receipt.

object or null

Site or work location address to store on the receipt.

reference
string

Free reference stored on the receipt.

date
string <date>

Main receipt date. If omitted, the current date is used.

language
string

Language used to render the receipt.

discount_percentage
number

Global discount percentage applied to the receipt.

item_discount
string
Enum: "none" "percentage" "amount"

How line discounts are represented on the receipt.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the receipt. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

tax_rate_1
number

First VAT rate configured on the receipt.

tax_rate_2
number

Second VAT rate configured on the receipt.

tax_rate_3
number

Third VAT rate configured on the receipt.

tax_country_code
string

ISO country code used for OSS VAT handling.

note
string

Plain-text note shown on the receipt.

note_html
string

HTML version of the note shown on the receipt.

Array of objects (CustomValueWrite)

Custom field values to store on the receipt.

Array of objects (DocumentFileWrite)

Files to attach to the receipt.

required
Array of objects or objects (DocumentItemWrite)

Receipt lines to store on the receipt.

Array of objects (PaymentWrite)

Payments to create together with the receipt.

Array of objects (RemarkWrite)

Remarks to create together with the receipt.

status
string
Value: "concept"

Optional mode switch. Send concept to create a receipt concept instead of an open receipt.

Responses

Request samples

Content type
application/json
{
  • "client_id": 92,
  • "external_receipt_id": "RECEIPT-2026-0051",
  • "layout_id": 8001,
  • "number": "2026-0051",
  • "reference": "COUNTER-051",
  • "date": "2026-05-01",
  • "language": "dutch",
  • "discount_percentage": 5,
  • "item_discount": "none",
  • "tax_calculation": "total",
  • "tax_included": "yes",
  • "tax_rate_1": 21,
  • "tax_country_code": "BE",
  • "note": "Paid at the counter.",
  • "items": [
    ],
  • "payments": [
    ],
  • "remarks": [
    ],
  • "status": "concept"
}

Response samples

Content type
application/json
{
  • "success": "receipt created",
  • "receipt_id": 501,
  • "uri": "https://deroos.dkpa.be/api/v1/receipts/501"
}

Get a receipt

Supports JSON, XML, CSV, HTML, and PDF for a single receipt.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
required
integer or string

Internal document id, or a +-separated list of document ids.

query Parameters
format
string
Enum: "xml" "json" "csv" "html" "pdf"

Optional response format override for a single document resource. Prefer the Accept header instead, typically Accept: application/json for API integrations. pdf is only available when requesting one document.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html" "application/pdf"

Preferred way to request the response format for a single document resource. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility. application/pdf is only available when requesting one document.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
{
  • "receipt_id": 501,
  • "uri": "https://deroos.dkpa.be/api/v1/receipts/501",
  • "external_receipt_id": "EXT-501",
  • "client_id": 92,
  • "client_uri": "https://deroos.dkpa.be/api/v1/clients/92",
  • "client_name": "ACME BV",
  • "client_attention": "Finance",
  • "type": "receipt",
  • "number": "2026-0051",
  • "layout_id": 8001,
  • "reference": "REF-0001",
  • "date": "2026-05-01",
  • "status": "open",
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "discount_percentage": 5,
  • "item_discount": "none",
  • "language": "dutch",
  • "tax_calculation": "total",
  • "tax_included": "no",
  • "tax_country_code": "BE",
  • "items": [
    ],
  • "discount_total_without_tax": "5.00",
  • "total_refundable_deposit": "0.00",
  • "total_without_tax": "95.00",
  • "tax_rate_1": 21,
  • "total_tax_1": "19.95",
  • "tax_rate_2": 12,
  • "total_tax_2": "0.00",
  • "tax_rate_3": 6,
  • "total_tax_3": "0.00",
  • "discount_total_with_tax": "6.05",
  • "total_with_tax": "114.95",
  • "total_paid": "114.95",
  • "note": "Paid at the counter.",
  • "note_html": "<p>Paid at the counter.</p>",
  • "created": "2026-05-01 10:15:00",
  • "last_activity": "2026-05-01 10:16:12",
  • "custom_values": [
    ],
  • "files": [
    ],
  • "tags": [
    ],
  • "payments": [
    ],
  • "remarks": [
    ],
  • "events": [
    ]
}

Partially update a receipt

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
external_receipt_id
string

External identifier managed by the integrating system.

client_id
required
integer

Internal id of the client linked to the receipt.

client_name
string

Client name to store directly on the receipt.

client_attention
string

Attention line to store on the receipt.

layout_id
integer

Layout id to use when rendering the receipt.

number
string

Receipt number. If omitted, a number is generated automatically.

object

Billing address to store on the receipt.

object or null

Delivery address to store on the receipt.

object or null

Site or work location address to store on the receipt.

reference
string

Free reference stored on the receipt.

date
string <date>

Main receipt date. If omitted, the current date is used.

language
string

Language used to render the receipt.

discount_percentage
number

Global discount percentage applied to the receipt.

item_discount
string
Enum: "none" "percentage" "amount"

How line discounts are represented on the receipt.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the receipt. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

tax_rate_1
number

First VAT rate configured on the receipt.

tax_rate_2
number

Second VAT rate configured on the receipt.

tax_rate_3
number

Third VAT rate configured on the receipt.

tax_country_code
string

ISO country code used for OSS VAT handling.

note
string

Plain-text note shown on the receipt.

note_html
string

HTML version of the note shown on the receipt.

Array of objects (CustomValueWrite)

Custom field values to store on the receipt.

Array of objects (DocumentFileWrite)

Files to attach to the receipt.

required
Array of objects or objects (DocumentItemWrite)

Receipt lines to store on the receipt.

Array of objects (PaymentWrite)

Payments to create together with the receipt.

Array of objects (RemarkWrite)

Remarks to create together with the receipt.

Responses

Request samples

Content type
application/json
{
  • "client_id": 92,
  • "external_receipt_id": "RECEIPT-2026-0051",
  • "layout_id": 8001,
  • "number": "2026-0051",
  • "reference": "COUNTER-051",
  • "date": "2026-05-01",
  • "language": "dutch",
  • "discount_percentage": 5,
  • "item_discount": "none",
  • "tax_calculation": "total",
  • "tax_included": "yes",
  • "tax_rate_1": 21,
  • "tax_country_code": "BE",
  • "note": "Paid at the counter.",
  • "items": [
    ],
  • "payments": [
    ],
  • "remarks": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a receipt

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
external_receipt_id
string

External identifier managed by the integrating system.

client_id
required
integer

Internal id of the client linked to the receipt.

client_name
string

Client name to store directly on the receipt.

client_attention
string

Attention line to store on the receipt.

layout_id
integer

Layout id to use when rendering the receipt.

number
string

Receipt number. If omitted, a number is generated automatically.

object

Billing address to store on the receipt.

object or null

Delivery address to store on the receipt.

object or null

Site or work location address to store on the receipt.

reference
string

Free reference stored on the receipt.

date
string <date>

Main receipt date. If omitted, the current date is used.

language
string

Language used to render the receipt.

discount_percentage
number

Global discount percentage applied to the receipt.

item_discount
string
Enum: "none" "percentage" "amount"

How line discounts are represented on the receipt.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the receipt. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

tax_rate_1
number

First VAT rate configured on the receipt.

tax_rate_2
number

Second VAT rate configured on the receipt.

tax_rate_3
number

Third VAT rate configured on the receipt.

tax_country_code
string

ISO country code used for OSS VAT handling.

note
string

Plain-text note shown on the receipt.

note_html
string

HTML version of the note shown on the receipt.

Array of objects (CustomValueWrite)

Custom field values to store on the receipt.

Array of objects (DocumentFileWrite)

Files to attach to the receipt.

required
Array of objects or objects (DocumentItemWrite)

Receipt lines to store on the receipt.

Array of objects (PaymentWrite)

Payments to create together with the receipt.

Array of objects (RemarkWrite)

Remarks to create together with the receipt.

Responses

Request samples

Content type
application/json
{
  • "client_id": 92,
  • "external_receipt_id": "RECEIPT-2026-0051",
  • "layout_id": 8001,
  • "number": "2026-0051",
  • "reference": "COUNTER-051",
  • "date": "2026-05-01",
  • "language": "dutch",
  • "discount_percentage": 5,
  • "item_discount": "none",
  • "tax_calculation": "total",
  • "tax_included": "yes",
  • "tax_rate_1": 21,
  • "tax_country_code": "BE",
  • "note": "Paid at the counter.",
  • "items": [
    ],
  • "payments": [
    ],
  • "remarks": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a receipt

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List receipt items

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a receipt item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "receipt item created",
  • "item_id": 4004,
  • "uri": "https://deroos.dkpa.be/api/v1/receipts/3003/items/4004"
}

Get a receipt item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "item_id": 3,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/items/3",
  • "type": "item",
  • "description": "Consulting",
  • "description_html": "<p>Consulting</p>",
  • "amount": "100.00",
  • "amount_with_tax": "121.00",
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "total_without_tax": "200.00",
  • "total_with_tax": "242.00",
  • "general_ledger_account": "700000",
  • "custom_values": [
    ]
}

Partially update a receipt item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "quantity": 3,
  • "description": "Updated line description"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a receipt item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a receipt item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List receipt payments

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a receipt payment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
One of
date
string <date>

Payment date in YYYY-MM-DD format.

amount
required
number

Payment amount.

method
string
Enum: "transfer" "cash" "debitcard" "creditcard" "directcollection" "online" "bancontact" "ideal" "giftcard" "bitcoin" "internal" "paypal" "payconiq" "cashdiscount" "difference" "ecocheque" ""

Payment method. Possible values are transfer, cash, debitcard, creditcard, directcollection, online, bancontact, ideal, giftcard, bitcoin, internal, paypal, payconiq, cashdiscount, difference, and ecocheque. Use an empty string when no method is stored.

description
string

Free description stored on the payment.

boolean or string

Whether the remaining open amount should be used. Allowed values are a boolean or yes/no.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-20",
  • "amount": 121,
  • "method": "transfer",
  • "description": "Payment received"
}

Response samples

Content type
application/json
{
  • "success": "payment created",
  • "payment_id": 9,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/payments/9"
}

Get a receipt payment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

paymentId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "payment_id": 9,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/payments/9",
  • "date": "2026-05-20",
  • "amount": 121,
  • "method": "transfer",
  • "description": "Advance payment",
  • "allocation_id": 123,
  • "banktransaction_id": 456,
  • "banktransaction_number": "2026/00012",
  • "source": "banktransaction"
}

Partially update a receipt payment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

paymentId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Payment date in YYYY-MM-DD format.

amount
number

Payment amount.

method
string
Enum: "transfer" "cash" "debitcard" "creditcard" "directcollection" "online" "bancontact" "ideal" "giftcard" "bitcoin" "internal" "paypal" "payconiq" "cashdiscount" "difference" "ecocheque" ""

Payment method. Possible values are transfer, cash, debitcard, creditcard, directcollection, online, bancontact, ideal, giftcard, bitcoin, internal, paypal, payconiq, cashdiscount, difference, and ecocheque. Use an empty string when no method is stored.

description
string

Free description stored on the payment.

boolean or string

Whether the remaining open amount should be used. Allowed values are a boolean or yes/no.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-20",
  • "amount": 121,
  • "method": "transfer",
  • "description": "Payment received"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a receipt payment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

paymentId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Payment date in YYYY-MM-DD format.

amount
number

Payment amount.

method
string
Enum: "transfer" "cash" "debitcard" "creditcard" "directcollection" "online" "bancontact" "ideal" "giftcard" "bitcoin" "internal" "paypal" "payconiq" "cashdiscount" "difference" "ecocheque" ""

Payment method. Possible values are transfer, cash, debitcard, creditcard, directcollection, online, bancontact, ideal, giftcard, bitcoin, internal, paypal, payconiq, cashdiscount, difference, and ecocheque. Use an empty string when no method is stored.

description
string

Free description stored on the payment.

boolean or string

Whether the remaining open amount should be used. Allowed values are a boolean or yes/no.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-20",
  • "amount": 121,
  • "method": "transfer",
  • "description": "Payment received"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

List receipt remarks

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a receipt remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
One of
date
string <date>

Remark date in YYYY-MM-DD format.

description
required
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "remark created",
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5"
}

Get a receipt remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5",
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Partially update a receipt remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a receipt remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a receipt remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List receipt events

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a receipt event

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

eventId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
Example
{
  • "event_id": 17,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/events/17",
  • "date": "2026-05-21",
  • "type": "email sent",
  • "content": "Please find your invoice attached.",
  • "recipients": [
    ]
}

List receipt files

Files are attachments linked to the receipt.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

skip
integer >= 0
take
integer >= 1
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a receipt file

Files are attachments linked to the receipt.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42",
  • "filename": "terms.pdf",
  • "content_type": "application/pdf",
  • "role": "attachment",
  • "created": "2026-05-05 12:12:12"
}

Partially update a receipt file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a receipt file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a receipt file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Download a receipt file

Files are attachments linked to the receipt.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "error": "client_id unknown"
}

Upload a receipt attachment

Upload the attachment as multipart/form-data, not as a JSON request body. Files are attachments linked to the receipt.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: multipart/form-data
required
file
required
string <binary>
role
string
Enum: "attachment" "internal_document" "merged_document"

Functional role of the attachment. Possible values are attachment, internal_document, and merged_document.

Responses

Response samples

Content type
application/json
{
  • "success": "file created",
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42"
}

Send a receipt by email

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
required
Array of strings or integers non-empty

Recipients. Each value can be an email address, a client contact id, or one of main_contact, first_contact, all_contacts, myself, or account_owner.

string or (Array of strings or integers)
Deprecated

Deprecated alias for recipients. Use recipients in new integrations.

subject
string

Email subject. If omitted, the configured default subject is used.

message
string

Plain-text email message. If omitted, the configured default message is used.

message_html
string

HTML email message. Use this instead of message when sending rich text.

Array of objects

Additional temporary uploads to attach. Upload each file first through POST /uploads and provide its returned upload_id here.

Responses

Request samples

Content type
application/json
{
  • "recipients": [
    ],
  • "subject": "Document 2026-0001",
  • "message": "Please find your document attached."
}

Response samples

Content type
application/json
{
  • "success": "email sent",
  • "email_addresses": [
    ]
}

Send a receipt by postal mail

A Mail-IT-Wize integration must be configured before this call can be used.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
address_type
string
Default: "billing"
Enum: "billing" "delivery" "site"

Address of the document recipient to use for postal delivery.

send_registered
boolean
Default: false

Set to true to send the postal mail as registered mail.

Responses

Request samples

Content type
application/json
{
  • "address_type": "billing",
  • "send_registered": true
}

Response samples

Content type
application/json
{
  • "success": "sent to post office"
}

Quotes

List quotes

Supports fields, search, paging, sorting, and document-specific filters such as client, status, date, tags, or number. Response formats are limited to JSON, XML, CSV, and HTML on the collection endpoint.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1
count
string

Presence flag that switches the request to count mode. Trigger it by sending ?count without a value.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
Example
[
  • {
    }
]

Create a quote

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
external_quote_id
string

External identifier managed by the integrating system.

client_id
required
integer

Internal id of the client linked to the quote.

client_name
string

Client name to store directly on the quote.

client_attention
string

Attention line to store on the quote.

layout_id
integer

Layout id to use when rendering the quote.

object

Billing address to store on the quote.

object or null

Delivery address to store on the quote.

object or null

Site or work location address to store on the quote.

reference
string

Free reference stored on the quote.

date
string <date>

Main quote date.

date_delivery
string <date>

Delivery or performance date linked to the quote.

days_valid
integer

Validity period of the quote in days.

date_expires
string <date>

Explicit expiration date of the quote.

deposit_paid
number

Deposit amount already paid for the quote.

currency
string

ISO currency code used on the quote.

exchange_rate
string

Exchange rate used to convert the quote currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the quote.

language
string

Language used to render the quote.

discount_percentage
number

Global discount percentage applied to the quote.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the quote. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the quote.

note_html
string

HTML version of the note shown on the quote.

Array of objects (CustomValueWrite)

Custom field values to store on the quote.

Array of objects (DocumentFileWrite)

Files to attach to the quote.

required
Array of objects or objects (DocumentItemWrite)

Quote lines to store on the quote.

status
string
Enum: "concept" "open" "accepted" "rejected"

Initial status of the quote. Use concept to create a quote concept.

Responses

Request samples

Content type
application/json
{
  • "external_quote_id": "QUOTE-2019-00058",
  • "client_id": 22,
  • "layout_id": 8001,
  • "reference": "REF-0001",
  • "date": "2019-05-06",
  • "days_valid": 30,
  • "currency": "EUR",
  • "exchange_rate": "1",
  • "show_tax_for_exchange_rate": "no",
  • "language": "dutch",
  • "discount_percentage": 5,
  • "tax_calculation": "total",
  • "tax_included": "no",
  • "note": "Valid for 30 days.",
  • "billing_address": {
    },
  • "items": [
    ],
  • "custom_values": [
    ],
  • "files": [
    ],
  • "status": "concept"
}

Response samples

Content type
application/json
{
  • "success": "quote created",
  • "quote_id": 11,
  • "uri": "https://deroos.dkpa.be/api/v1/quotes/11"
}

Get a quote

Supports JSON, XML, CSV, HTML, and PDF for a single quote.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
required
integer or string

Internal document id, or a +-separated list of document ids.

query Parameters
format
string
Enum: "xml" "json" "csv" "html" "pdf"

Optional response format override for a single document resource. Prefer the Accept header instead, typically Accept: application/json for API integrations. pdf is only available when requesting one document.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html" "application/pdf"

Preferred way to request the response format for a single document resource. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility. application/pdf is only available when requesting one document.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
{
  • "quote_id": 11,
  • "uri": "https://deroos.dkpa.be/api/v1/quotes/11",
  • "external_quote_id": "EXT-001",
  • "client_id": 22,
  • "client_uri": "https://deroos.dkpa.be/api/v1/clients/22",
  • "client_name": "ACME BV",
  • "client_attention": "Finance",
  • "type": "quote",
  • "number": "2019-00058",
  • "layout_id": 8001,
  • "reference": "REF-0001",
  • "date": "2019-05-06",
  • "deposit_paid": "0.00",
  • "status": "open",
  • "days_valid": 30,
  • "date_expires": "2019-06-04",
  • "currency": "EUR",
  • "exchange_rate": "1",
  • "show_tax_for_exchange_rate": "no",
  • "language": "dutch",
  • "discount_percentage": 5,
  • "item_discount": "none",
  • "tax_calculation": "total",
  • "tax_included": "no",
  • "tax_country_code": "BE",
  • "billing_address": {
    },
  • "delivery_address": null,
  • "site_address": null,
  • "items": [
    ],
  • "discount_total_without_tax": "5.00",
  • "total_refundable_deposit": "0.00",
  • "total_without_tax": "95.00",
  • "tax_rate_1": 21,
  • "total_tax_1": "19.95",
  • "total_with_tax": "114.95",
  • "note": "Valid for 30 days.",
  • "note_html": "<p>Valid for 30 days.</p>",
  • "created": "2019-05-06 10:15:00",
  • "last_activity": "2019-05-07 09:30:00",
  • "custom_values": [
    ],
  • "files": [
    ],
  • "tags": [
    ],
  • "remarks": [
    ],
  • "events": [
    ]
}

Partially update a quote

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
status
string
Enum: "open" "accepted" "rejected"

Status to apply to the quote. concept cannot be used for updates.

external_quote_id
string

External identifier managed by the integrating system.

client_id
required
integer

Internal id of the client linked to the quote.

client_name
string

Client name to store directly on the quote.

client_attention
string

Attention line to store on the quote.

layout_id
integer

Layout id to use when rendering the quote.

object

Billing address to store on the quote.

object or null

Delivery address to store on the quote.

object or null

Site or work location address to store on the quote.

reference
string

Free reference stored on the quote.

date
string <date>

Main quote date.

date_delivery
string <date>

Delivery or performance date linked to the quote.

days_valid
integer

Validity period of the quote in days.

date_expires
string <date>

Explicit expiration date of the quote.

deposit_paid
number

Deposit amount already paid for the quote.

currency
string

ISO currency code used on the quote.

exchange_rate
string

Exchange rate used to convert the quote currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the quote.

language
string

Language used to render the quote.

discount_percentage
number

Global discount percentage applied to the quote.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the quote. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the quote.

note_html
string

HTML version of the note shown on the quote.

Array of objects (CustomValueWrite)

Custom field values to store on the quote.

Array of objects (DocumentFileWrite)

Files to attach to the quote.

required
Array of objects or objects (DocumentItemWrite)

Quote lines to store on the quote.

Responses

Request samples

Content type
application/json
{
  • "status": "open",
  • "external_quote_id": "QUOTE-2019-00058",
  • "client_id": 22,
  • "layout_id": 8001,
  • "reference": "REF-0001",
  • "date": "2019-05-06",
  • "days_valid": 30,
  • "currency": "EUR",
  • "exchange_rate": "1",
  • "show_tax_for_exchange_rate": "no",
  • "language": "dutch",
  • "discount_percentage": 5,
  • "tax_calculation": "total",
  • "tax_included": "no",
  • "note": "Valid for 30 days.",
  • "billing_address": {
    },
  • "items": [
    ],
  • "custom_values": [
    ],
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a quote

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
status
string
Enum: "open" "accepted" "rejected"

Status to apply to the quote. concept cannot be used for updates.

external_quote_id
string

External identifier managed by the integrating system.

client_id
required
integer

Internal id of the client linked to the quote.

client_name
string

Client name to store directly on the quote.

client_attention
string

Attention line to store on the quote.

layout_id
integer

Layout id to use when rendering the quote.

object

Billing address to store on the quote.

object or null

Delivery address to store on the quote.

object or null

Site or work location address to store on the quote.

reference
string

Free reference stored on the quote.

date
string <date>

Main quote date.

date_delivery
string <date>

Delivery or performance date linked to the quote.

days_valid
integer

Validity period of the quote in days.

date_expires
string <date>

Explicit expiration date of the quote.

deposit_paid
number

Deposit amount already paid for the quote.

currency
string

ISO currency code used on the quote.

exchange_rate
string

Exchange rate used to convert the quote currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the quote.

language
string

Language used to render the quote.

discount_percentage
number

Global discount percentage applied to the quote.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the quote. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the quote.

note_html
string

HTML version of the note shown on the quote.

Array of objects (CustomValueWrite)

Custom field values to store on the quote.

Array of objects (DocumentFileWrite)

Files to attach to the quote.

required
Array of objects or objects (DocumentItemWrite)

Quote lines to store on the quote.

Responses

Request samples

Content type
application/json
{
  • "status": "open",
  • "external_quote_id": "QUOTE-2019-00058",
  • "client_id": 22,
  • "layout_id": 8001,
  • "reference": "REF-0001",
  • "date": "2019-05-06",
  • "days_valid": 30,
  • "currency": "EUR",
  • "exchange_rate": "1",
  • "show_tax_for_exchange_rate": "no",
  • "language": "dutch",
  • "discount_percentage": 5,
  • "tax_calculation": "total",
  • "tax_included": "no",
  • "note": "Valid for 30 days.",
  • "billing_address": {
    },
  • "items": [
    ],
  • "custom_values": [
    ],
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a quote

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List quote items

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a quote item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "quote item created",
  • "item_id": 4004,
  • "uri": "https://deroos.dkpa.be/api/v1/quotes/3003/items/4004"
}

Get a quote item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "item_id": 3,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/items/3",
  • "type": "item",
  • "description": "Consulting",
  • "description_html": "<p>Consulting</p>",
  • "amount": "100.00",
  • "amount_with_tax": "121.00",
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "total_without_tax": "200.00",
  • "total_with_tax": "242.00",
  • "general_ledger_account": "700000",
  • "custom_values": [
    ]
}

Partially update a quote item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "quantity": 3,
  • "description": "Updated line description"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a quote item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a quote item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List quote remarks

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a quote remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
One of
date
string <date>

Remark date in YYYY-MM-DD format.

description
required
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "remark created",
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5"
}

Get a quote remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5",
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Partially update a quote remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a quote remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a quote remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List quote events

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a quote event

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

eventId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
Example
{
  • "event_id": 17,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/events/17",
  • "date": "2026-05-21",
  • "type": "email sent",
  • "content": "Please find your invoice attached.",
  • "recipients": [
    ]
}

List quote files

Files are attachments linked to the quote.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

skip
integer >= 0
take
integer >= 1
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a quote file

Files are attachments linked to the quote.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42",
  • "filename": "terms.pdf",
  • "content_type": "application/pdf",
  • "role": "attachment",
  • "created": "2026-05-05 12:12:12"
}

Partially update a quote file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a quote file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a quote file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Download a quote file

Files are attachments linked to the quote.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "error": "client_id unknown"
}

Upload a quote attachment

Upload the attachment as multipart/form-data, not as a JSON request body. Files are attachments linked to the quote.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: multipart/form-data
required
file
required
string <binary>
role
string
Enum: "attachment" "internal_document" "merged_document"

Functional role of the attachment. Possible values are attachment, internal_document, and merged_document.

Responses

Response samples

Content type
application/json
{
  • "success": "file created",
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42"
}

Send a quote by email

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
required
Array of strings or integers non-empty

Recipients. Each value can be an email address, a client contact id, or one of main_contact, first_contact, all_contacts, myself, or account_owner.

string or (Array of strings or integers)
Deprecated

Deprecated alias for recipients. Use recipients in new integrations.

subject
string

Email subject. If omitted, the configured default subject is used.

message
string

Plain-text email message. If omitted, the configured default message is used.

message_html
string

HTML email message. Use this instead of message when sending rich text.

Array of objects

Additional temporary uploads to attach. Upload each file first through POST /uploads and provide its returned upload_id here.

Responses

Request samples

Content type
application/json
{
  • "recipients": [
    ],
  • "subject": "Document 2026-0001",
  • "message": "Please find your document attached."
}

Response samples

Content type
application/json
{
  • "success": "email sent",
  • "email_addresses": [
    ]
}

Send a quote by postal mail

A Mail-IT-Wize integration must be configured before this call can be used.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
address_type
string
Default: "billing"
Enum: "billing" "delivery" "site"

Address of the document recipient to use for postal delivery.

send_registered
boolean
Default: false

Set to true to send the postal mail as registered mail.

Responses

Request samples

Content type
application/json
{
  • "address_type": "billing",
  • "send_registered": true
}

Response samples

Content type
application/json
{
  • "success": "sent to post office"
}

Orders

List orders

Supports fields, search, paging, sorting, and document-specific filters such as client, status, date, tags, or number. Response formats are limited to JSON, XML, CSV, and HTML on the collection endpoint.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1
count
string

Presence flag that switches the request to count mode. Trigger it by sending ?count without a value.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
Example
[
  • {
    }
]

Create an order

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the order.

client_name
string

Client name to store directly on the order.

client_attention
string

Attention line to store on the order.

layout_id
integer

Layout id to use when rendering the order.

object

Billing address to store on the order.

object or null

Delivery address to store on the order.

object or null

Site or work location address to store on the order.

reference
string

Free reference stored on the order.

date
string <date>

Main order date.

status
string
Enum: "open" "late" "cancelled" "completed" "create_invoice" "partial"

Current status of the order.

currency
string

ISO currency code used on the order.

exchange_rate
string

Exchange rate used to convert the order currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the order.

language
string

Language used to render the order.

discount_percentage
number

Global discount percentage applied to the order.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the order. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the order.

note_html
string

HTML version of the note shown on the order.

Array of objects (CustomValueWrite)

Custom field values to store on the order.

external_order_id
string

External identifier managed by the integrating system.

Array of objects (DocumentFileWrite)

Files to attach to the order.

required
Array of objects or objects (DocumentItemWrite)

Order lines to store on the order.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "status": "open",
  • "currency": "string",
  • "exchange_rate": "string",
  • "show_tax_for_exchange_rate": "string",
  • "language": "string",
  • "discount_percentage": 0,
  • "tax_calculation": "item",
  • "tax_included": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_order_id": "string",
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "order created",
  • "order_id": 301,
  • "uri": "https://deroos.dkpa.be/api/v1/orders/301"
}

Get an order

Supports JSON, XML, CSV, HTML, and PDF for a single order.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
required
integer or string

Internal document id, or a +-separated list of document ids.

query Parameters
format
string
Enum: "xml" "json" "csv" "html" "pdf"

Optional response format override for a single document resource. Prefer the Accept header instead, typically Accept: application/json for API integrations. pdf is only available when requesting one document.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html" "application/pdf"

Preferred way to request the response format for a single document resource. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility. application/pdf is only available when requesting one document.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
{
  • "order_id": 301,
  • "uri": "https://deroos.dkpa.be/api/v1/orders/301",
  • "external_order_id": "EXT-301",
  • "client_id": 22,
  • "client_uri": "https://deroos.dkpa.be/api/v1/clients/22",
  • "client_name": "ACME BV",
  • "client_attention": "Finance",
  • "type": "order",
  • "number": "2026-0301",
  • "layout_id": 8001,
  • "reference": "REF-0301",
  • "date": "2026-05-10",
  • "days_delivery": 14,
  • "date_delivery": "2026-05-24",
  • "days_late": 0,
  • "deposit_paid": "0.00",
  • "status": "partial",
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "discount_percentage": 5,
  • "item_discount": "percentage",
  • "currency": "EUR",
  • "exchange_rate": "1",
  • "show_tax_for_exchange_rate": "no",
  • "language": "dutch",
  • "tax_calculation": "total",
  • "tax_included": "no",
  • "tax_country_code": "BE",
  • "items": [
    ],
  • "discount_total_without_tax": "10.00",
  • "total_refundable_deposit": "0.00",
  • "total_without_tax": "190.00",
  • "tax_rate_1": 21,
  • "total_tax_1": "39.90",
  • "tax_rate_2": 6,
  • "total_tax_2": "0.00",
  • "tax_rate_3": 0,
  • "total_tax_3": "0.00",
  • "discount_total_with_tax": "12.10",
  • "total_with_tax": "229.90",
  • "note": "Deliver in the morning.",
  • "note_html": "<p>Deliver in the morning.</p>",
  • "created": "2026-05-10 09:15:00",
  • "last_activity": "2026-05-11 08:30:00",
  • "custom_values": [
    ],
  • "files": [
    ],
  • "tags": [
    ],
  • "remarks": [
    ],
  • "events": [
    ]
}

Partially update an order

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the order.

client_name
string

Client name to store directly on the order.

client_attention
string

Attention line to store on the order.

layout_id
integer

Layout id to use when rendering the order.

object

Billing address to store on the order.

object or null

Delivery address to store on the order.

object or null

Site or work location address to store on the order.

reference
string

Free reference stored on the order.

date
string <date>

Main order date.

status
string
Enum: "open" "late" "cancelled" "completed" "create_invoice" "partial"

Current status of the order.

currency
string

ISO currency code used on the order.

exchange_rate
string

Exchange rate used to convert the order currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the order.

language
string

Language used to render the order.

discount_percentage
number

Global discount percentage applied to the order.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the order. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the order.

note_html
string

HTML version of the note shown on the order.

Array of objects (CustomValueWrite)

Custom field values to store on the order.

external_order_id
string

External identifier managed by the integrating system.

Array of objects (DocumentFileWrite)

Files to attach to the order.

required
Array of objects or objects (DocumentItemWrite)

Order lines to store on the order.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "status": "open",
  • "currency": "string",
  • "exchange_rate": "string",
  • "show_tax_for_exchange_rate": "string",
  • "language": "string",
  • "discount_percentage": 0,
  • "tax_calculation": "item",
  • "tax_included": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_order_id": "string",
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update an order

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the order.

client_name
string

Client name to store directly on the order.

client_attention
string

Attention line to store on the order.

layout_id
integer

Layout id to use when rendering the order.

object

Billing address to store on the order.

object or null

Delivery address to store on the order.

object or null

Site or work location address to store on the order.

reference
string

Free reference stored on the order.

date
string <date>

Main order date.

status
string
Enum: "open" "late" "cancelled" "completed" "create_invoice" "partial"

Current status of the order.

currency
string

ISO currency code used on the order.

exchange_rate
string

Exchange rate used to convert the order currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the order.

language
string

Language used to render the order.

discount_percentage
number

Global discount percentage applied to the order.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the order. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the order.

note_html
string

HTML version of the note shown on the order.

Array of objects (CustomValueWrite)

Custom field values to store on the order.

external_order_id
string

External identifier managed by the integrating system.

Array of objects (DocumentFileWrite)

Files to attach to the order.

required
Array of objects or objects (DocumentItemWrite)

Order lines to store on the order.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "status": "open",
  • "currency": "string",
  • "exchange_rate": "string",
  • "show_tax_for_exchange_rate": "string",
  • "language": "string",
  • "discount_percentage": 0,
  • "tax_calculation": "item",
  • "tax_included": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_order_id": "string",
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete an order

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List order items

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an order item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "order item created",
  • "item_id": 4004,
  • "uri": "https://deroos.dkpa.be/api/v1/orders/3003/items/4004"
}

Get an order item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "item_id": 3,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/items/3",
  • "type": "item",
  • "description": "Consulting",
  • "description_html": "<p>Consulting</p>",
  • "amount": "100.00",
  • "amount_with_tax": "121.00",
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "total_without_tax": "200.00",
  • "total_with_tax": "242.00",
  • "general_ledger_account": "700000",
  • "custom_values": [
    ]
}

Partially update an order item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "quantity": 3,
  • "description": "Updated line description"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update an order item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete an order item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List order remarks

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an order remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
One of
date
string <date>

Remark date in YYYY-MM-DD format.

description
required
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "remark created",
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5"
}

Get an order remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5",
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Partially update an order remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update an order remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete an order remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List order events

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an order event

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

eventId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
Example
{
  • "event_id": 17,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/events/17",
  • "date": "2026-05-21",
  • "type": "email sent",
  • "content": "Please find your invoice attached.",
  • "recipients": [
    ]
}

List order files

Files are attachments linked to the order.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

skip
integer >= 0
take
integer >= 1
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an order file

Files are attachments linked to the order.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42",
  • "filename": "terms.pdf",
  • "content_type": "application/pdf",
  • "role": "attachment",
  • "created": "2026-05-05 12:12:12"
}

Partially update an order file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update an order file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete an order file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Download an order file

Files are attachments linked to the order.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "error": "client_id unknown"
}

Upload an order attachment

Upload the attachment as multipart/form-data, not as a JSON request body. Files are attachments linked to the order.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: multipart/form-data
required
file
required
string <binary>
role
string
Enum: "attachment" "internal_document" "merged_document"

Functional role of the attachment. Possible values are attachment, internal_document, and merged_document.

Responses

Response samples

Content type
application/json
{
  • "success": "file created",
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42"
}

Send an order by email

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
required
Array of strings or integers non-empty

Recipients. Each value can be an email address, a client contact id, or one of main_contact, first_contact, all_contacts, myself, or account_owner.

string or (Array of strings or integers)
Deprecated

Deprecated alias for recipients. Use recipients in new integrations.

subject
string

Email subject. If omitted, the configured default subject is used.

message
string

Plain-text email message. If omitted, the configured default message is used.

message_html
string

HTML email message. Use this instead of message when sending rich text.

Array of objects

Additional temporary uploads to attach. Upload each file first through POST /uploads and provide its returned upload_id here.

Responses

Request samples

Content type
application/json
{
  • "recipients": [
    ],
  • "subject": "Document 2026-0001",
  • "message": "Please find your document attached."
}

Response samples

Content type
application/json
{
  • "success": "email sent",
  • "email_addresses": [
    ]
}

Send an order by postal mail

A Mail-IT-Wize integration must be configured before this call can be used.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
address_type
string
Default: "billing"
Enum: "billing" "delivery" "site"

Address of the document recipient to use for postal delivery.

send_registered
boolean
Default: false

Set to true to send the postal mail as registered mail.

Responses

Request samples

Content type
application/json
{
  • "address_type": "billing",
  • "send_registered": true
}

Response samples

Content type
application/json
{
  • "success": "sent to post office"
}

Deliveries

List deliveries

Supports fields, search, paging, sorting, and document-specific filters such as client, status, date, tags, or number. Response formats are limited to JSON, XML, CSV, and HTML on the collection endpoint.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1
count
string

Presence flag that switches the request to count mode. Trigger it by sending ?count without a value.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
Example
[
  • {
    }
]

Create a delivery

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the delivery.

client_name
string

Client name to store directly on the delivery.

client_attention
string

Attention line to store on the delivery.

layout_id
integer

Layout id to use when rendering the delivery.

object

Billing address to store on the delivery.

object or null

Delivery address to store on the delivery.

object or null

Site or work location address to store on the delivery.

reference
string

Free reference stored on the delivery.

date
string <date>

Main delivery date.

status
string
Enum: "open" "completed" "create_invoice"

Current status of the delivery.

language
string

Language used to render the delivery.

note
string

Plain-text note shown on the delivery.

note_html
string

HTML version of the note shown on the delivery.

Array of objects (CustomValueWrite)

Custom field values to store on the delivery.

external_delivery_id
string

External identifier managed by the integrating system.

days_delivery
integer

Planned delivery term in days.

Array of objects (DocumentFileWrite)

Files to attach to the delivery.

required
Array of objects or objects (DocumentItemWrite)

Delivery lines to store on the delivery.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "status": "open",
  • "language": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_delivery_id": "string",
  • "days_delivery": 0,
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "delivery created",
  • "delivery_id": 401,
  • "uri": "https://deroos.dkpa.be/api/v1/deliveries/401"
}

Get a delivery

Supports JSON, XML, CSV, HTML, and PDF for a single delivery.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
required
integer or string

Internal document id, or a +-separated list of document ids.

query Parameters
format
string
Enum: "xml" "json" "csv" "html" "pdf"

Optional response format override for a single document resource. Prefer the Accept header instead, typically Accept: application/json for API integrations. pdf is only available when requesting one document.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html" "application/pdf"

Preferred way to request the response format for a single document resource. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility. application/pdf is only available when requesting one document.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
{
  • "delivery_id": 401,
  • "uri": "https://deroos.dkpa.be/api/v1/deliveries/401",
  • "external_delivery_id": "EXT-401",
  • "client_id": 22,
  • "client_uri": "https://deroos.dkpa.be/api/v1/clients/22",
  • "client_name": "ACME BV",
  • "client_attention": "Finance",
  • "type": "delivery",
  • "number": "2026-0401",
  • "layout_id": 8001,
  • "reference": "REF-0401",
  • "date": "2026-05-11",
  • "status": "create_invoice",
  • "currency": "EUR"
}

Partially update a delivery

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the delivery.

client_name
string

Client name to store directly on the delivery.

client_attention
string

Attention line to store on the delivery.

layout_id
integer

Layout id to use when rendering the delivery.

object

Billing address to store on the delivery.

object or null

Delivery address to store on the delivery.

object or null

Site or work location address to store on the delivery.

reference
string

Free reference stored on the delivery.

date
string <date>

Main delivery date.

status
string
Enum: "open" "completed" "create_invoice"

Current status of the delivery.

language
string

Language used to render the delivery.

note
string

Plain-text note shown on the delivery.

note_html
string

HTML version of the note shown on the delivery.

Array of objects (CustomValueWrite)

Custom field values to store on the delivery.

external_delivery_id
string

External identifier managed by the integrating system.

days_delivery
integer

Planned delivery term in days.

Array of objects (DocumentFileWrite)

Files to attach to the delivery.

required
Array of objects or objects (DocumentItemWrite)

Delivery lines to store on the delivery.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "status": "open",
  • "language": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_delivery_id": "string",
  • "days_delivery": 0,
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a delivery

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the delivery.

client_name
string

Client name to store directly on the delivery.

client_attention
string

Attention line to store on the delivery.

layout_id
integer

Layout id to use when rendering the delivery.

object

Billing address to store on the delivery.

object or null

Delivery address to store on the delivery.

object or null

Site or work location address to store on the delivery.

reference
string

Free reference stored on the delivery.

date
string <date>

Main delivery date.

status
string
Enum: "open" "completed" "create_invoice"

Current status of the delivery.

language
string

Language used to render the delivery.

note
string

Plain-text note shown on the delivery.

note_html
string

HTML version of the note shown on the delivery.

Array of objects (CustomValueWrite)

Custom field values to store on the delivery.

external_delivery_id
string

External identifier managed by the integrating system.

days_delivery
integer

Planned delivery term in days.

Array of objects (DocumentFileWrite)

Files to attach to the delivery.

required
Array of objects or objects (DocumentItemWrite)

Delivery lines to store on the delivery.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "status": "open",
  • "language": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_delivery_id": "string",
  • "days_delivery": 0,
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a delivery

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List delivery items

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a delivery item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "delivery item created",
  • "item_id": 4004,
  • "uri": "https://deroos.dkpa.be/api/v1/deliveries/3003/items/4004"
}

Get a delivery item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "item_id": 3,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/items/3",
  • "type": "item",
  • "description": "Consulting",
  • "description_html": "<p>Consulting</p>",
  • "amount": "100.00",
  • "amount_with_tax": "121.00",
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "total_without_tax": "200.00",
  • "total_with_tax": "242.00",
  • "general_ledger_account": "700000",
  • "custom_values": [
    ]
}

Partially update a delivery item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "quantity": 3,
  • "description": "Updated line description"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a delivery item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a delivery item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List delivery remarks

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a delivery remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
One of
date
string <date>

Remark date in YYYY-MM-DD format.

description
required
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "remark created",
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5"
}

Get a delivery remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5",
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Partially update a delivery remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a delivery remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a delivery remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List delivery events

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a delivery event

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

eventId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
Example
{
  • "event_id": 17,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/events/17",
  • "date": "2026-05-21",
  • "type": "email sent",
  • "content": "Please find your invoice attached.",
  • "recipients": [
    ]
}

List delivery files

Files are attachments linked to the delivery.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

skip
integer >= 0
take
integer >= 1
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a delivery file

Files are attachments linked to the delivery.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42",
  • "filename": "terms.pdf",
  • "content_type": "application/pdf",
  • "role": "attachment",
  • "created": "2026-05-05 12:12:12"
}

Partially update a delivery file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a delivery file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a delivery file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Download a delivery file

Files are attachments linked to the delivery.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "error": "client_id unknown"
}

Upload a delivery attachment

Upload the attachment as multipart/form-data, not as a JSON request body. Files are attachments linked to the delivery.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: multipart/form-data
required
file
required
string <binary>
role
string
Enum: "attachment" "internal_document" "merged_document"

Functional role of the attachment. Possible values are attachment, internal_document, and merged_document.

Responses

Response samples

Content type
application/json
{
  • "success": "file created",
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42"
}

Send a delivery by email

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
required
Array of strings or integers non-empty

Recipients. Each value can be an email address, a client contact id, or one of main_contact, first_contact, all_contacts, myself, or account_owner.

string or (Array of strings or integers)
Deprecated

Deprecated alias for recipients. Use recipients in new integrations.

subject
string

Email subject. If omitted, the configured default subject is used.

message
string

Plain-text email message. If omitted, the configured default message is used.

message_html
string

HTML email message. Use this instead of message when sending rich text.

Array of objects

Additional temporary uploads to attach. Upload each file first through POST /uploads and provide its returned upload_id here.

Responses

Request samples

Content type
application/json
{
  • "recipients": [
    ],
  • "subject": "Document 2026-0001",
  • "message": "Please find your document attached."
}

Response samples

Content type
application/json
{
  • "success": "email sent",
  • "email_addresses": [
    ]
}

Send a delivery by postal mail

A Mail-IT-Wize integration must be configured before this call can be used.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
address_type
string
Default: "billing"
Enum: "billing" "delivery" "site"

Address of the document recipient to use for postal delivery.

send_registered
boolean
Default: false

Set to true to send the postal mail as registered mail.

Responses

Request samples

Content type
application/json
{
  • "address_type": "billing",
  • "send_registered": true
}

Response samples

Content type
application/json
{
  • "success": "sent to post office"
}

Payment Requests

List payment requests

Supports fields, search, paging, sorting, and document-specific filters such as client, status, date, tags, or number. Response formats are limited to JSON, XML, CSV, and HTML on the collection endpoint.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1
count
string

Presence flag that switches the request to count mode. Trigger it by sending ?count without a value.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
Example
[
  • {
    }
]

Create a payment request

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the payment request.

client_name
string

Client name to store directly on the payment request.

client_attention
string

Attention line to store on the payment request.

layout_id
integer

Layout id to use when rendering the payment request.

object

Billing address to store on the payment request.

object or null

Delivery address to store on the payment request.

object or null

Site or work location address to store on the payment request.

reference
string

Free reference stored on the payment request.

date
string <date>

Main payment request date.

date_delivery
string <date>

Delivery or performance date linked to the payment request.

status
string
Enum: "open" "overdue" "paid" "completed"

Current status of the payment request.

days_due
integer

Payment term in days.

currency
string

ISO currency code used on the payment request.

exchange_rate
string

Exchange rate used to convert the payment request currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the payment request.

language
string

Language used to render the payment request.

discount_percentage
number

Global discount percentage applied to the payment request.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the payment request. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the payment request.

note_html
string

HTML version of the note shown on the payment request.

Array of objects (CustomValueWrite)

Custom field values to store on the payment request.

external_paymentrequest_id
string

External identifier managed by the integrating system.

structured_message
string

Structured payment reference of the payment request.

cash_discount_percentage
number

Financial discount percentage applied to the payment request.

cash_discount_days_valid
integer

Number of days the financial discount remains valid.

Array of objects (DocumentFileWrite)

Files to attach to the payment request.

required
Array of objects or objects (DocumentItemWrite)

Payment request lines to store on the payment request.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "date_delivery": "2019-08-24",
  • "status": "open",
  • "days_due": 0,
  • "currency": "string",
  • "exchange_rate": "string",
  • "show_tax_for_exchange_rate": "string",
  • "language": "string",
  • "discount_percentage": 0,
  • "tax_calculation": "item",
  • "tax_included": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_paymentrequest_id": "string",
  • "structured_message": "string",
  • "cash_discount_percentage": 0,
  • "cash_discount_days_valid": 0,
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "paymentrequest created",
  • "paymentrequest_id": 81,
  • "uri": "https://deroos.dkpa.be/api/v1/paymentrequests/81"
}

Get a payment request

Supports JSON, XML, CSV, HTML, and PDF for a single payment request.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
required
integer or string

Internal document id, or a +-separated list of document ids.

query Parameters
format
string
Enum: "xml" "json" "csv" "html" "pdf"

Optional response format override for a single document resource. Prefer the Accept header instead, typically Accept: application/json for API integrations. pdf is only available when requesting one document.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html" "application/pdf"

Preferred way to request the response format for a single document resource. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility. application/pdf is only available when requesting one document.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
{
  • "paymentrequest_id": 81,
  • "uri": "https://deroos.dkpa.be/api/v1/paymentrequests/81",
  • "external_paymentrequest_id": "EXT-081",
  • "client_id": 92,
  • "client_uri": "https://deroos.dkpa.be/api/v1/clients/92",
  • "client_name": "ACME BV",
  • "client_attention": "Finance",
  • "type": "paymentrequest",
  • "number": "2026-0081",
  • "layout_id": 8001,
  • "reference": "REF-0081",
  • "date": "2026-05-12",
  • "status": "open",
  • "days_due": 30,
  • "days_overdue": 0,
  • "date_overdue": "2026-06-11",
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "discount_percentage": 0,
  • "cash_discount_percentage": 2,
  • "cash_discount_days_valid": 8,
  • "cash_discount_date_valid": "2026-05-20",
  • "item_discount": "none",
  • "structured_message": "123456789012",
  • "currency": "EUR",
  • "exchange_rate": "1",
  • "show_tax_for_exchange_rate": "no",
  • "language": "dutch",
  • "tax_calculation": "total",
  • "tax_included": "no",
  • "tax_country_code": "BE",
  • "items": [
    ],
  • "discount_total_without_tax": "0.00",
  • "total_refundable_deposit": "0.00",
  • "total_without_tax": "100.00",
  • "tax_rate_1": 21,
  • "total_tax_1": "21.00",
  • "tax_rate_2": 6,
  • "total_tax_2": "0.00",
  • "tax_rate_3": 0,
  • "total_tax_3": "0.00",
  • "cash_discount_total": "2.42",
  • "discount_total_with_tax": "0.00",
  • "total_with_tax": "121.00",
  • "total_paid": "0.00",
  • "outstanding_balance": "121.00",
  • "automatic_reminders": true,
  • "note": "Customer requested payment details.",
  • "note_html": "<p>Customer requested payment details.</p>",
  • "created": "2026-05-12 09:15:00",
  • "last_activity": "2026-05-13 10:30:00",
  • "custom_values": [
    ],
  • "files": [
    ],
  • "tags": [
    ],
  • "payments": [
    ],
  • "remarks": [
    ],
  • "events": [
    ]
}

Partially update a payment request

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the payment request.

client_name
string

Client name to store directly on the payment request.

client_attention
string

Attention line to store on the payment request.

layout_id
integer

Layout id to use when rendering the payment request.

object

Billing address to store on the payment request.

object or null

Delivery address to store on the payment request.

object or null

Site or work location address to store on the payment request.

reference
string

Free reference stored on the payment request.

date
string <date>

Main payment request date.

date_delivery
string <date>

Delivery or performance date linked to the payment request.

status
string
Enum: "open" "overdue" "paid" "completed"

Current status of the payment request.

days_due
integer

Payment term in days.

currency
string

ISO currency code used on the payment request.

exchange_rate
string

Exchange rate used to convert the payment request currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the payment request.

language
string

Language used to render the payment request.

discount_percentage
number

Global discount percentage applied to the payment request.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the payment request. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the payment request.

note_html
string

HTML version of the note shown on the payment request.

Array of objects (CustomValueWrite)

Custom field values to store on the payment request.

external_paymentrequest_id
string

External identifier managed by the integrating system.

structured_message
string

Structured payment reference of the payment request.

cash_discount_percentage
number

Financial discount percentage applied to the payment request.

cash_discount_days_valid
integer

Number of days the financial discount remains valid.

Array of objects (DocumentFileWrite)

Files to attach to the payment request.

required
Array of objects or objects (DocumentItemWrite)

Payment request lines to store on the payment request.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "date_delivery": "2019-08-24",
  • "status": "open",
  • "days_due": 0,
  • "currency": "string",
  • "exchange_rate": "string",
  • "show_tax_for_exchange_rate": "string",
  • "language": "string",
  • "discount_percentage": 0,
  • "tax_calculation": "item",
  • "tax_included": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_paymentrequest_id": "string",
  • "structured_message": "string",
  • "cash_discount_percentage": 0,
  • "cash_discount_days_valid": 0,
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a payment request

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the payment request.

client_name
string

Client name to store directly on the payment request.

client_attention
string

Attention line to store on the payment request.

layout_id
integer

Layout id to use when rendering the payment request.

object

Billing address to store on the payment request.

object or null

Delivery address to store on the payment request.

object or null

Site or work location address to store on the payment request.

reference
string

Free reference stored on the payment request.

date
string <date>

Main payment request date.

date_delivery
string <date>

Delivery or performance date linked to the payment request.

status
string
Enum: "open" "overdue" "paid" "completed"

Current status of the payment request.

days_due
integer

Payment term in days.

currency
string

ISO currency code used on the payment request.

exchange_rate
string

Exchange rate used to convert the payment request currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the payment request.

language
string

Language used to render the payment request.

discount_percentage
number

Global discount percentage applied to the payment request.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the payment request. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the payment request.

note_html
string

HTML version of the note shown on the payment request.

Array of objects (CustomValueWrite)

Custom field values to store on the payment request.

external_paymentrequest_id
string

External identifier managed by the integrating system.

structured_message
string

Structured payment reference of the payment request.

cash_discount_percentage
number

Financial discount percentage applied to the payment request.

cash_discount_days_valid
integer

Number of days the financial discount remains valid.

Array of objects (DocumentFileWrite)

Files to attach to the payment request.

required
Array of objects or objects (DocumentItemWrite)

Payment request lines to store on the payment request.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "date_delivery": "2019-08-24",
  • "status": "open",
  • "days_due": 0,
  • "currency": "string",
  • "exchange_rate": "string",
  • "show_tax_for_exchange_rate": "string",
  • "language": "string",
  • "discount_percentage": 0,
  • "tax_calculation": "item",
  • "tax_included": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_paymentrequest_id": "string",
  • "structured_message": "string",
  • "cash_discount_percentage": 0,
  • "cash_discount_days_valid": 0,
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a payment request

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List payment request items

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a payment request item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "payment request item created",
  • "item_id": 4004,
  • "uri": "https://deroos.dkpa.be/api/v1/paymentrequests/3003/items/4004"
}

Get a payment request item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "item_id": 3,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/items/3",
  • "type": "item",
  • "description": "Consulting",
  • "description_html": "<p>Consulting</p>",
  • "amount": "100.00",
  • "amount_with_tax": "121.00",
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "total_without_tax": "200.00",
  • "total_with_tax": "242.00",
  • "general_ledger_account": "700000",
  • "custom_values": [
    ]
}

Partially update a payment request item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "quantity": 3,
  • "description": "Updated line description"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a payment request item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a payment request item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List payment request payments

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a payment request payment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
One of
date
string <date>

Payment date in YYYY-MM-DD format.

amount
required
number

Payment amount.

method
string
Enum: "transfer" "cash" "debitcard" "creditcard" "directcollection" "online" "bancontact" "ideal" "giftcard" "bitcoin" "internal" "paypal" "payconiq" "cashdiscount" "difference" "ecocheque" ""

Payment method. Possible values are transfer, cash, debitcard, creditcard, directcollection, online, bancontact, ideal, giftcard, bitcoin, internal, paypal, payconiq, cashdiscount, difference, and ecocheque. Use an empty string when no method is stored.

description
string

Free description stored on the payment.

boolean or string

Whether the remaining open amount should be used. Allowed values are a boolean or yes/no.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-20",
  • "amount": 121,
  • "method": "transfer",
  • "description": "Payment received"
}

Response samples

Content type
application/json
{
  • "success": "payment created",
  • "payment_id": 9,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/payments/9"
}

Get a payment request payment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

paymentId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "payment_id": 9,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/payments/9",
  • "date": "2026-05-20",
  • "amount": 121,
  • "method": "transfer",
  • "description": "Advance payment",
  • "allocation_id": 123,
  • "banktransaction_id": 456,
  • "banktransaction_number": "2026/00012",
  • "source": "banktransaction"
}

Partially update a payment request payment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

paymentId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Payment date in YYYY-MM-DD format.

amount
number

Payment amount.

method
string
Enum: "transfer" "cash" "debitcard" "creditcard" "directcollection" "online" "bancontact" "ideal" "giftcard" "bitcoin" "internal" "paypal" "payconiq" "cashdiscount" "difference" "ecocheque" ""

Payment method. Possible values are transfer, cash, debitcard, creditcard, directcollection, online, bancontact, ideal, giftcard, bitcoin, internal, paypal, payconiq, cashdiscount, difference, and ecocheque. Use an empty string when no method is stored.

description
string

Free description stored on the payment.

boolean or string

Whether the remaining open amount should be used. Allowed values are a boolean or yes/no.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-20",
  • "amount": 121,
  • "method": "transfer",
  • "description": "Payment received"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a payment request payment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

paymentId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Payment date in YYYY-MM-DD format.

amount
number

Payment amount.

method
string
Enum: "transfer" "cash" "debitcard" "creditcard" "directcollection" "online" "bancontact" "ideal" "giftcard" "bitcoin" "internal" "paypal" "payconiq" "cashdiscount" "difference" "ecocheque" ""

Payment method. Possible values are transfer, cash, debitcard, creditcard, directcollection, online, bancontact, ideal, giftcard, bitcoin, internal, paypal, payconiq, cashdiscount, difference, and ecocheque. Use an empty string when no method is stored.

description
string

Free description stored on the payment.

boolean or string

Whether the remaining open amount should be used. Allowed values are a boolean or yes/no.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-20",
  • "amount": 121,
  • "method": "transfer",
  • "description": "Payment received"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

List payment request remarks

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a payment request remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
One of
date
string <date>

Remark date in YYYY-MM-DD format.

description
required
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "remark created",
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5"
}

Get a payment request remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5",
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Partially update a payment request remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a payment request remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a payment request remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List payment request events

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a payment request event

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

eventId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
Example
{
  • "event_id": 17,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/events/17",
  • "date": "2026-05-21",
  • "type": "email sent",
  • "content": "Please find your invoice attached.",
  • "recipients": [
    ]
}

List payment request files

Files are attachments linked to the payment request.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

skip
integer >= 0
take
integer >= 1
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a payment request file

Files are attachments linked to the payment request.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42",
  • "filename": "terms.pdf",
  • "content_type": "application/pdf",
  • "role": "attachment",
  • "created": "2026-05-05 12:12:12"
}

Partially update a payment request file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a payment request file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a payment request file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Download a payment request file

Files are attachments linked to the payment request.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "error": "client_id unknown"
}

Upload a payment request attachment

Upload the attachment as multipart/form-data, not as a JSON request body. Files are attachments linked to the payment request.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: multipart/form-data
required
file
required
string <binary>
role
string
Enum: "attachment" "internal_document" "merged_document"

Functional role of the attachment. Possible values are attachment, internal_document, and merged_document.

Responses

Response samples

Content type
application/json
{
  • "success": "file created",
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42"
}

Send a payment request by email

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
required
Array of strings or integers non-empty

Recipients. Each value can be an email address, a client contact id, or one of main_contact, first_contact, all_contacts, myself, or account_owner.

string or (Array of strings or integers)
Deprecated

Deprecated alias for recipients. Use recipients in new integrations.

subject
string

Email subject. If omitted, the configured default subject is used.

message
string

Plain-text email message. If omitted, the configured default message is used.

message_html
string

HTML email message. Use this instead of message when sending rich text.

Array of objects

Additional temporary uploads to attach. Upload each file first through POST /uploads and provide its returned upload_id here.

document_type
string
Default: "pdf"
Enum: "none" "pdf" "ubl" "both" "duplicate" "reminder" "reminder_summary"

Document attachment to generate. pdf (also accepted as document) is the default.

Responses

Request samples

Content type
application/json
{
  • "recipients": [
    ],
  • "subject": "Invoice 2026-0001",
  • "message": "Please find your invoice attached.",
  • "document_type": "pdf",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "email sent",
  • "email_addresses": [
    ]
}

Send a payment request by postal mail

A Mail-IT-Wize integration must be configured before this call can be used.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
address_type
string
Default: "billing"
Enum: "billing" "delivery" "site"

Address of the document recipient to use for postal delivery.

send_registered
boolean
Default: false

Set to true to send the postal mail as registered mail.

document_type
string
Default: "document"
Enum: "document" "duplicate" "reminder" "reminder_summary"

Document variant to send.

Responses

Request samples

Content type
application/json
{
  • "address_type": "billing",
  • "send_registered": true,
  • "document_type": "document"
}

Response samples

Content type
application/json
{
  • "success": "sent to post office"
}

Request a direct collection for a payment request

Request a direct debit for the outstanding payment request amount.

A Mollie integration must be configured before this call can be used. The client must already have given permission for direct collection through a valid Mollie mandate.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "direct collection requested"
}

Custom Documents

List custom documents

Supports fields, search, paging, sorting, and document-specific filters such as client, status, date, tags, or number. Response formats are limited to JSON, XML, CSV, and HTML on the collection endpoint.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1
count
string

Presence flag that switches the request to count mode. Trigger it by sending ?count without a value.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
Example
[
  • {
    }
]

Create a custom document

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the custom document.

client_name
string

Client name to store directly on the custom document.

client_attention
string

Attention line to store on the custom document.

layout_id
integer

Layout id to use when rendering the custom document.

object

Billing address to store on the custom document.

object or null

Delivery address to store on the custom document.

object or null

Site or work location address to store on the custom document.

reference
string

Free reference stored on the custom document.

date
string <date>

Main custom document date.

date_delivery
string <date>

Delivery or performance date linked to the custom document.

status
string
Enum: "open" "completed"

Current status of the custom document.

days_due
integer

Payment term in days.

currency
string

ISO currency code used on the custom document.

exchange_rate
string

Exchange rate used to convert the custom document currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the custom document.

language
string

Language used to render the custom document.

discount_percentage
number

Global discount percentage applied to the custom document.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the custom document. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the custom document.

note_html
string

HTML version of the note shown on the custom document.

Array of objects (CustomValueWrite)

Custom field values to store on the custom document.

external_customdocument_id
string

External identifier managed by the integrating system.

structured_message
string

Structured payment reference of the custom document.

cash_discount_percentage
number

Financial discount percentage applied to the custom document.

cash_discount_days_valid
integer

Number of days the financial discount remains valid.

Array of objects (DocumentFileWrite)

Files to attach to the custom document.

required
Array of objects or objects (DocumentItemWrite)

Custom document lines to store on the custom document.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "date_delivery": "2019-08-24",
  • "status": "open",
  • "days_due": 0,
  • "currency": "string",
  • "exchange_rate": "string",
  • "show_tax_for_exchange_rate": "string",
  • "language": "string",
  • "discount_percentage": 0,
  • "tax_calculation": "item",
  • "tax_included": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_customdocument_id": "string",
  • "structured_message": "string",
  • "cash_discount_percentage": 0,
  • "cash_discount_days_valid": 0,
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "customdocument created",
  • "customdocument_id": 17,
  • "uri": "https://deroos.dkpa.be/api/v1/customdocuments/17"
}

Get a custom document

Supports JSON, XML, CSV, HTML, and PDF for a single custom document.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
required
integer or string

Internal document id, or a +-separated list of document ids.

query Parameters
format
string
Enum: "xml" "json" "csv" "html" "pdf"

Optional response format override for a single document resource. Prefer the Accept header instead, typically Accept: application/json for API integrations. pdf is only available when requesting one document.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html" "application/pdf"

Preferred way to request the response format for a single document resource. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility. application/pdf is only available when requesting one document.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
{
  • "customdocument_id": 17,
  • "uri": "https://deroos.dkpa.be/api/v1/customdocuments/17",
  • "external_customdocument_id": "EXT-001",
  • "client_id": 22,
  • "client_uri": "https://deroos.dkpa.be/api/v1/clients/22",
  • "client_name": "ACME BV",
  • "client_attention": "Finance",
  • "type": "customdocument",
  • "number": "2019-00058",
  • "layout_id": 8001,
  • "reference": "REF-001",
  • "date": "2019-05-06",
  • "status": "open",
  • "currency": "EUR"
}

Partially update a custom document

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the custom document.

client_name
string

Client name to store directly on the custom document.

client_attention
string

Attention line to store on the custom document.

layout_id
integer

Layout id to use when rendering the custom document.

object

Billing address to store on the custom document.

object or null

Delivery address to store on the custom document.

object or null

Site or work location address to store on the custom document.

reference
string

Free reference stored on the custom document.

date
string <date>

Main custom document date.

date_delivery
string <date>

Delivery or performance date linked to the custom document.

status
string
Enum: "open" "completed"

Current status of the custom document.

days_due
integer

Payment term in days.

currency
string

ISO currency code used on the custom document.

exchange_rate
string

Exchange rate used to convert the custom document currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the custom document.

language
string

Language used to render the custom document.

discount_percentage
number

Global discount percentage applied to the custom document.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the custom document. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the custom document.

note_html
string

HTML version of the note shown on the custom document.

Array of objects (CustomValueWrite)

Custom field values to store on the custom document.

external_customdocument_id
string

External identifier managed by the integrating system.

structured_message
string

Structured payment reference of the custom document.

cash_discount_percentage
number

Financial discount percentage applied to the custom document.

cash_discount_days_valid
integer

Number of days the financial discount remains valid.

Array of objects (DocumentFileWrite)

Files to attach to the custom document.

required
Array of objects or objects (DocumentItemWrite)

Custom document lines to store on the custom document.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "date_delivery": "2019-08-24",
  • "status": "open",
  • "days_due": 0,
  • "currency": "string",
  • "exchange_rate": "string",
  • "show_tax_for_exchange_rate": "string",
  • "language": "string",
  • "discount_percentage": 0,
  • "tax_calculation": "item",
  • "tax_included": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_customdocument_id": "string",
  • "structured_message": "string",
  • "cash_discount_percentage": 0,
  • "cash_discount_days_valid": 0,
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a custom document

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the custom document.

client_name
string

Client name to store directly on the custom document.

client_attention
string

Attention line to store on the custom document.

layout_id
integer

Layout id to use when rendering the custom document.

object

Billing address to store on the custom document.

object or null

Delivery address to store on the custom document.

object or null

Site or work location address to store on the custom document.

reference
string

Free reference stored on the custom document.

date
string <date>

Main custom document date.

date_delivery
string <date>

Delivery or performance date linked to the custom document.

status
string
Enum: "open" "completed"

Current status of the custom document.

days_due
integer

Payment term in days.

currency
string

ISO currency code used on the custom document.

exchange_rate
string

Exchange rate used to convert the custom document currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the custom document.

language
string

Language used to render the custom document.

discount_percentage
number

Global discount percentage applied to the custom document.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the custom document. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the custom document.

note_html
string

HTML version of the note shown on the custom document.

Array of objects (CustomValueWrite)

Custom field values to store on the custom document.

external_customdocument_id
string

External identifier managed by the integrating system.

structured_message
string

Structured payment reference of the custom document.

cash_discount_percentage
number

Financial discount percentage applied to the custom document.

cash_discount_days_valid
integer

Number of days the financial discount remains valid.

Array of objects (DocumentFileWrite)

Files to attach to the custom document.

required
Array of objects or objects (DocumentItemWrite)

Custom document lines to store on the custom document.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "date_delivery": "2019-08-24",
  • "status": "open",
  • "days_due": 0,
  • "currency": "string",
  • "exchange_rate": "string",
  • "show_tax_for_exchange_rate": "string",
  • "language": "string",
  • "discount_percentage": 0,
  • "tax_calculation": "item",
  • "tax_included": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_customdocument_id": "string",
  • "structured_message": "string",
  • "cash_discount_percentage": 0,
  • "cash_discount_days_valid": 0,
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a custom document

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List custom document items

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a custom document item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "custom document item created",
  • "item_id": 4004,
  • "uri": "https://deroos.dkpa.be/api/v1/customdocuments/3003/items/4004"
}

Get a custom document item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "item_id": 3,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/items/3",
  • "type": "item",
  • "description": "Consulting",
  • "description_html": "<p>Consulting</p>",
  • "amount": "100.00",
  • "amount_with_tax": "121.00",
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "total_without_tax": "200.00",
  • "total_with_tax": "242.00",
  • "general_ledger_account": "700000",
  • "custom_values": [
    ]
}

Partially update a custom document item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "quantity": 3,
  • "description": "Updated line description"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a custom document item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a custom document item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List custom document remarks

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a custom document remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
One of
date
string <date>

Remark date in YYYY-MM-DD format.

description
required
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "remark created",
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5"
}

Get a custom document remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5",
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Partially update a custom document remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a custom document remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a custom document remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List custom document events

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a custom document event

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

eventId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
Example
{
  • "event_id": 17,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/events/17",
  • "date": "2026-05-21",
  • "type": "email sent",
  • "content": "Please find your invoice attached.",
  • "recipients": [
    ]
}

List custom document files

Files are attachments linked to the custom document.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

skip
integer >= 0
take
integer >= 1
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a custom document file

Files are attachments linked to the custom document.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42",
  • "filename": "terms.pdf",
  • "content_type": "application/pdf",
  • "role": "attachment",
  • "created": "2026-05-05 12:12:12"
}

Partially update a custom document file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a custom document file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a custom document file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Download a custom document file

Files are attachments linked to the custom document.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "error": "client_id unknown"
}

Upload a custom document attachment

Upload the attachment as multipart/form-data, not as a JSON request body. Files are attachments linked to the custom document.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: multipart/form-data
required
file
required
string <binary>
role
string
Enum: "attachment" "internal_document" "merged_document"

Functional role of the attachment. Possible values are attachment, internal_document, and merged_document.

Responses

Response samples

Content type
application/json
{
  • "success": "file created",
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42"
}

Send a custom document by email

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
required
Array of strings or integers non-empty

Recipients. Each value can be an email address, a client contact id, or one of main_contact, first_contact, all_contacts, myself, or account_owner.

string or (Array of strings or integers)
Deprecated

Deprecated alias for recipients. Use recipients in new integrations.

subject
string

Email subject. If omitted, the configured default subject is used.

message
string

Plain-text email message. If omitted, the configured default message is used.

message_html
string

HTML email message. Use this instead of message when sending rich text.

Array of objects

Additional temporary uploads to attach. Upload each file first through POST /uploads and provide its returned upload_id here.

Responses

Request samples

Content type
application/json
{
  • "recipients": [
    ],
  • "subject": "Document 2026-0001",
  • "message": "Please find your document attached."
}

Response samples

Content type
application/json
{
  • "success": "email sent",
  • "email_addresses": [
    ]
}

Send a custom document by postal mail

A Mail-IT-Wize integration must be configured before this call can be used.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
address_type
string
Default: "billing"
Enum: "billing" "delivery" "site"

Address of the document recipient to use for postal delivery.

send_registered
boolean
Default: false

Set to true to send the postal mail as registered mail.

Responses

Request samples

Content type
application/json
{
  • "address_type": "billing",
  • "send_registered": true
}

Response samples

Content type
application/json
{
  • "success": "sent to post office"
}

Send a custom document through Peppol

The Peppol integration must be configured and activated before this call can be used.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
optional
purchase_order
string

Optional purchase order reference to include in the Peppol document.

Array of objects

Optional temporary uploads to include with the Peppol delivery. Upload each file first through POST /uploads.

Responses

Request samples

Content type
application/json
{
  • "purchase_order": "PO-7781",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "invoice sent"
}

Subscriptions

List subscriptions

Supports fields, search, paging, sorting, and document-specific filters such as client, status, date, tags, or number. Response formats are limited to JSON, XML, CSV, and HTML.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1
count
string

Presence flag that switches the request to count mode. Trigger it by sending ?count without a value.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
Example
[
  • {
    }
]

Create a subscription

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the subscription.

client_name
string

Client name to store directly on the subscription.

client_attention
string

Attention line to store on the subscription.

layout_id
integer

Layout id to use when rendering the subscription.

object

Billing address to store on the subscription.

object or null

Delivery address to store on the subscription.

object or null

Site or work location address to store on the subscription.

reference
string

Free reference stored on the subscription.

date
string <date>

Main document date used by the subscription numbering logic when applicable.

status
string
Enum: "open" "disabled" "completed"

Current status of the subscription.

days_due
integer

Payment term in days.

currency
string

ISO currency code used on the subscription.

exchange_rate
string

Exchange rate used to convert the subscription currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the subscription.

language
string

Language used to render the subscription.

discount_percentage
number

Global discount percentage applied to the subscription.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the subscription. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the subscription.

note_html
string

HTML version of the note shown on the subscription.

Array of objects (CustomValueWrite)

Custom field values to store on the subscription.

external_subscription_id
string

External identifier managed by the integrating system.

target_document_type
string
Default: "invoice"
Enum: "invoice" "invoice_concept" "quote" "quote_concept" "receipt" "receipt_concept" "order" "order_concept" "delivery" "delivery_concept" "subscription" "subscription_concept" "paymentrequest" "paymentrequest_concept" "customdocument" "customdocument_concept"

Document type generated by the subscription. Defaults to invoice when omitted.

boolean or string

Whether a structured payment reference should be generated automatically.

structured_message
string

Structured payment reference used by generated documents.

boolean or string

Whether generated invoices should use direct collection.

boolean or string

Whether generated documents should be sent automatically.

send_method
string
Enum: "none" "email" "peppol" "peppol_email"

Delivery method used when auto-sending generated documents.

email_recipients
Array of strings

Email recipients used when the send method includes email.

email_subject
string

Email subject used when auto-sending generated documents.

email_content
string

Email body used when auto-sending generated documents.

email_filetype
string

File type attached when auto-sending generated documents.

next_date
string <date>

Next scheduled generation date.

boolean or string

Whether the payment term should be counted until the end of the month.

integer or string

Frequency value used together with interval.

interval
required
string
Enum: "day" "week" "month" "year"

Interval unit used for the subscription frequency.

times
integer

Number of times the subscription should still generate a document.

expiration_date
string <date>

Date after which the subscription stops generating documents.

Array of objects (DocumentFileWrite)

Files to attach to the subscription.

required
Array of objects or objects (DocumentItemWrite)

Subscription lines to store on the subscription.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "status": "open",
  • "days_due": 0,
  • "currency": "string",
  • "exchange_rate": "string",
  • "show_tax_for_exchange_rate": "string",
  • "language": "string",
  • "discount_percentage": 0,
  • "tax_calculation": "item",
  • "tax_included": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_subscription_id": "string",
  • "target_document_type": "invoice",
  • "generate_structured_message": true,
  • "structured_message": "string",
  • "direct_collection": true,
  • "auto_send_invoice": true,
  • "send_method": "none",
  • "email_recipients": [
    ],
  • "email_subject": "string",
  • "email_content": "string",
  • "email_filetype": "string",
  • "next_date": "2019-08-24",
  • "days_due_end_of_month": true,
  • "frequency": 0,
  • "interval": "day",
  • "times": 0,
  • "expiration_date": "2019-08-24",
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "subscription created",
  • "subscription_id": 548,
  • "uri": "https://deroos.dkpa.be/api/v1/subscriptions/548"
}

Get a subscription

Supports JSON, XML, CSV, and HTML for a single subscription. PDF and invoice-specific export formats are not available on this endpoint.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
required
integer or string

Internal document id, or a +-separated list of document ids.

query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
{
  • "subscription_id": 548,
  • "uri": "https://deroos.dkpa.be/api/v1/subscriptions/548",
  • "external_subscription_id": "EXT-548",
  • "client_id": 358,
  • "client_uri": "https://deroos.dkpa.be/api/v1/clients/358",
  • "client_name": "ACME BV",
  • "client_attention": "Finance",
  • "type": "subscription",
  • "number": "2026-0548",
  • "layout_id": 8001,
  • "reference": "REF-0548",
  • "status": "open",
  • "days_due": 30,
  • "days_due_end_of_month": "no",
  • "currency": "EUR",
  • "target_document_type": "invoice",
  • "next_date": "2026-06-01",
  • "interval": "month",
  • "frequency": 1,
  • "auto_send_invoice": "no",
  • "send_method": "email"
}

Partially update a subscription

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the subscription.

client_name
string

Client name to store directly on the subscription.

client_attention
string

Attention line to store on the subscription.

layout_id
integer

Layout id to use when rendering the subscription.

object

Billing address to store on the subscription.

object or null

Delivery address to store on the subscription.

object or null

Site or work location address to store on the subscription.

reference
string

Free reference stored on the subscription.

date
string <date>

Main document date used by the subscription numbering logic when applicable.

status
string
Enum: "open" "disabled" "completed"

Current status of the subscription.

days_due
integer

Payment term in days.

currency
string

ISO currency code used on the subscription.

exchange_rate
string

Exchange rate used to convert the subscription currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the subscription.

language
string

Language used to render the subscription.

discount_percentage
number

Global discount percentage applied to the subscription.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the subscription. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the subscription.

note_html
string

HTML version of the note shown on the subscription.

Array of objects (CustomValueWrite)

Custom field values to store on the subscription.

external_subscription_id
string

External identifier managed by the integrating system.

target_document_type
string
Default: "invoice"
Enum: "invoice" "invoice_concept" "quote" "quote_concept" "receipt" "receipt_concept" "order" "order_concept" "delivery" "delivery_concept" "subscription" "subscription_concept" "paymentrequest" "paymentrequest_concept" "customdocument" "customdocument_concept"

Document type generated by the subscription. Defaults to invoice when omitted.

boolean or string

Whether a structured payment reference should be generated automatically.

structured_message
string

Structured payment reference used by generated documents.

boolean or string

Whether generated invoices should use direct collection.

boolean or string

Whether generated documents should be sent automatically.

send_method
string
Enum: "none" "email" "peppol" "peppol_email"

Delivery method used when auto-sending generated documents.

email_recipients
Array of strings

Email recipients used when the send method includes email.

email_subject
string

Email subject used when auto-sending generated documents.

email_content
string

Email body used when auto-sending generated documents.

email_filetype
string

File type attached when auto-sending generated documents.

next_date
string <date>

Next scheduled generation date.

boolean or string

Whether the payment term should be counted until the end of the month.

integer or string

Frequency value used together with interval.

interval
required
string
Enum: "day" "week" "month" "year"

Interval unit used for the subscription frequency.

times
integer

Number of times the subscription should still generate a document.

expiration_date
string <date>

Date after which the subscription stops generating documents.

Array of objects (DocumentFileWrite)

Files to attach to the subscription.

required
Array of objects or objects (DocumentItemWrite)

Subscription lines to store on the subscription.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "status": "open",
  • "days_due": 0,
  • "currency": "string",
  • "exchange_rate": "string",
  • "show_tax_for_exchange_rate": "string",
  • "language": "string",
  • "discount_percentage": 0,
  • "tax_calculation": "item",
  • "tax_included": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_subscription_id": "string",
  • "target_document_type": "invoice",
  • "generate_structured_message": true,
  • "structured_message": "string",
  • "direct_collection": true,
  • "auto_send_invoice": true,
  • "send_method": "none",
  • "email_recipients": [
    ],
  • "email_subject": "string",
  • "email_content": "string",
  • "email_filetype": "string",
  • "next_date": "2019-08-24",
  • "days_due_end_of_month": true,
  • "frequency": 0,
  • "interval": "day",
  • "times": 0,
  • "expiration_date": "2019-08-24",
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a subscription

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
client_id
required
integer

Internal id of the client linked to the subscription.

client_name
string

Client name to store directly on the subscription.

client_attention
string

Attention line to store on the subscription.

layout_id
integer

Layout id to use when rendering the subscription.

object

Billing address to store on the subscription.

object or null

Delivery address to store on the subscription.

object or null

Site or work location address to store on the subscription.

reference
string

Free reference stored on the subscription.

date
string <date>

Main document date used by the subscription numbering logic when applicable.

status
string
Enum: "open" "disabled" "completed"

Current status of the subscription.

days_due
integer

Payment term in days.

currency
string

ISO currency code used on the subscription.

exchange_rate
string

Exchange rate used to convert the subscription currency to EUR.

show_tax_for_exchange_rate
string

Whether VAT converted to EUR should be shown on the subscription.

language
string

Language used to render the subscription.

discount_percentage
number

Global discount percentage applied to the subscription.

tax_calculation
string
Enum: "item" "total"

VAT calculation method used for the subscription. Allowed values are item and total. The default is total.

string or boolean

Whether the supplied amounts already include VAT.

note
string

Plain-text note shown on the subscription.

note_html
string

HTML version of the note shown on the subscription.

Array of objects (CustomValueWrite)

Custom field values to store on the subscription.

external_subscription_id
string

External identifier managed by the integrating system.

target_document_type
string
Default: "invoice"
Enum: "invoice" "invoice_concept" "quote" "quote_concept" "receipt" "receipt_concept" "order" "order_concept" "delivery" "delivery_concept" "subscription" "subscription_concept" "paymentrequest" "paymentrequest_concept" "customdocument" "customdocument_concept"

Document type generated by the subscription. Defaults to invoice when omitted.

boolean or string

Whether a structured payment reference should be generated automatically.

structured_message
string

Structured payment reference used by generated documents.

boolean or string

Whether generated invoices should use direct collection.

boolean or string

Whether generated documents should be sent automatically.

send_method
string
Enum: "none" "email" "peppol" "peppol_email"

Delivery method used when auto-sending generated documents.

email_recipients
Array of strings

Email recipients used when the send method includes email.

email_subject
string

Email subject used when auto-sending generated documents.

email_content
string

Email body used when auto-sending generated documents.

email_filetype
string

File type attached when auto-sending generated documents.

next_date
string <date>

Next scheduled generation date.

boolean or string

Whether the payment term should be counted until the end of the month.

integer or string

Frequency value used together with interval.

interval
required
string
Enum: "day" "week" "month" "year"

Interval unit used for the subscription frequency.

times
integer

Number of times the subscription should still generate a document.

expiration_date
string <date>

Date after which the subscription stops generating documents.

Array of objects (DocumentFileWrite)

Files to attach to the subscription.

required
Array of objects or objects (DocumentItemWrite)

Subscription lines to store on the subscription.

Responses

Request samples

Content type
application/json
{
  • "client_id": 0,
  • "client_name": "string",
  • "client_attention": "string",
  • "layout_id": 0,
  • "billing_address": {
    },
  • "delivery_address": {
    },
  • "site_address": {
    },
  • "reference": "string",
  • "date": "2019-08-24",
  • "status": "open",
  • "days_due": 0,
  • "currency": "string",
  • "exchange_rate": "string",
  • "show_tax_for_exchange_rate": "string",
  • "language": "string",
  • "discount_percentage": 0,
  • "tax_calculation": "item",
  • "tax_included": "string",
  • "note": "string",
  • "note_html": "string",
  • "custom_values": [
    ],
  • "external_subscription_id": "string",
  • "target_document_type": "invoice",
  • "generate_structured_message": true,
  • "structured_message": "string",
  • "direct_collection": true,
  • "auto_send_invoice": true,
  • "send_method": "none",
  • "email_recipients": [
    ],
  • "email_subject": "string",
  • "email_content": "string",
  • "email_filetype": "string",
  • "next_date": "2019-08-24",
  • "days_due_end_of_month": true,
  • "frequency": 0,
  • "interval": "day",
  • "times": 0,
  • "expiration_date": "2019-08-24",
  • "files": [
    ],
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a subscription

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List subscription items

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a subscription item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "subscription item created",
  • "item_id": 4004,
  • "uri": "https://deroos.dkpa.be/api/v1/subscriptions/3003/items/4004"
}

Get a subscription item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "item_id": 3,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/items/3",
  • "type": "item",
  • "description": "Consulting",
  • "description_html": "<p>Consulting</p>",
  • "amount": "100.00",
  • "amount_with_tax": "121.00",
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "total_without_tax": "200.00",
  • "total_with_tax": "242.00",
  • "general_ledger_account": "700000",
  • "custom_values": [
    ]
}

Partially update a subscription item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "quantity": 3,
  • "description": "Updated line description"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a subscription item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
Any of
type
string
Enum: "item" "text" "header" "footer"

Line type. Allowed values are item, text, header, and footer.

description
required
string

Plain-text description of the document line.

description_html
string

HTML version of the document line description, intended for rich-text formatting of the same line content.

amount
number

Unit amount excluding tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = no.

amount_with_tax
number

Unit amount including tax. Supports up to 4 decimals. Use this when the parent document uses tax_included = yes.

quantity
number

Quantity of the document line. Supports up to 2 decimals. Defaults to 1 when omitted.

quantity_with_unit
string

Combined quantity and unit separated by a space, for example 2 hour. Use this only on create or update, and not together with quantity or unit.

unit
string

Unit used for the quantity. Optional, maximum 10 characters, must start with a letter, and may not contain spaces.

stockitem_code
string

Stock item code linked to the line. Optional, maximum 20 characters. Setting this code alone does not update stock quantities.

stockitem_id
integer

Internal stock item id to use for the line. When set during create or update, stock is updated and missing fields such as description, amount, stockitem_code, tax_rate, tax_rate_special_status, and general_ledger_account can be auto-filled from the stock item.

discount_percentage
number

Optional line discount percentage. Use either discount_percentage or discount_amount, not both.

discount_amount
number

Optional fixed line discount amount. Use either discount_amount or discount_percentage, not both.

tax_rate
number

VAT rate applied to the line. Must match one of the document VAT rates or be 0.

tax_rate_special_status
string

VAT exemption code for the line. This can only be used when tax_rate is 0.

general_ledger_account
string

General ledger account linked to the line. Optional, 6 to 8 digits.

Array of objects (CustomValueWrite)

Custom field values stored on the document line.

Responses

Request samples

Content type
application/json
{
  • "type": "item",
  • "description": "Consulting",
  • "amount": 100,
  • "quantity": 2,
  • "unit": "hour",
  • "stockitem_code": "CONSULT",
  • "discount_percentage": 10,
  • "tax_rate": 21,
  • "tax_rate_special_status": "",
  • "general_ledger_account": 700000,
  • "custom_values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a subscription item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

itemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List subscription files

Files are attachments linked to the subscription.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

skip
integer >= 0
take
integer >= 1
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a subscription file

Files are attachments linked to the subscription.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42",
  • "filename": "terms.pdf",
  • "content_type": "application/pdf",
  • "role": "attachment",
  • "created": "2026-05-05 12:12:12"
}

Partially update a subscription file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a subscription file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
role
required
string
Enum: "attachment" "internal_document" "merged_document"

New functional role of the file. Possible values are attachment, internal_document, and merged_document.

Responses

Request samples

Content type
application/json
{
  • "role": "attachment"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a subscription file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Download a subscription file

Files are attachments linked to the subscription.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

documentFileId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "error": "client_id unknown"
}

Upload a subscription attachment

Upload the attachment as multipart/form-data, not as a JSON request body. Files are attachments linked to the subscription.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: multipart/form-data
required
file
required
string <binary>
role
string
Enum: "attachment" "internal_document" "merged_document"

Functional role of the attachment. Possible values are attachment, internal_document, and merged_document.

Responses

Response samples

Content type
application/json
{
  • "success": "file created",
  • "file_id": 42,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/files/42"
}

List subscription remarks

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a subscription remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
One of
date
string <date>

Remark date in YYYY-MM-DD format.

description
required
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "remark created",
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5"
}

Get a subscription remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "remark_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/invoices/14/remarks/5",
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Partially update a subscription remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a subscription remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
date
string <date>

Remark date in YYYY-MM-DD format.

description
string

Plain-text remark content.

description_html
string

HTML version of the remark content.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-05-19",
  • "description": "Customer asked to mention PO-7781 on the invoice."
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a subscription remark

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
documentId
required
integer

Internal document id.

remarkId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Purchases

List purchases

Supports JSON, XML, CSV, and HTML responses for purchase listings.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a purchase

Supports JSON, XML, CSV, HTML, and PDF for a single purchase. The format query parameter additionally accepts ubl only on this endpoint.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
purchaseId
required
integer
query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

format
string
Enum: "xml" "json" "csv" "html" "pdf" "ubl"

Optional response format override for a single purchase. Prefer the Accept header instead, typically Accept: application/json for API integrations. ubl and pdf are only available when requesting one purchase document.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html" "application/pdf"

Preferred way to request the response format for a single document resource. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility. application/pdf is only available when requesting one document.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
{
  • "purchase_id": 123,
  • "uri": "https://deroos.dkpa.be/api/v1/purchases/123",
  • "supplier_id": 45,
  • "supplier_uri": "https://deroos.dkpa.be/api/v1/suppliers/45",
  • "supplier_name": "Example Supplier NV",
  • "state": "paid",
  • "number": "PUR-2026-00123",
  • "date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "currency": "EUR",
  • "iban": "",
  • "total_without_tax": 200,
  • "total_with_tax": 242,
  • "source": "peppol",
  • "file_available": "yes",
  • "has_document": "yes",
  • "has_ubl": "yes",
  • "has_attachments": "no",
  • "created": "2026-05-02 11:20:34",
  • "updated": "2026-05-02 11:20:34",
  • "references": [
    ],
  • "tags": [ ]
}

Partially update a purchase

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
purchaseId
required
integer
Request Body schema: application/json
required
supplier_id
integer

Internal id of the supplier to link to the purchase.

supplier_name
string

Supplier name stored on the purchase, mainly used when no supplier is linked.

state
string
Enum: "pending" "accepted" "overdue" "rejected" "paid" "incomplete" "processing" "payment_scheduled"

New workflow state of the purchase.

number
string

Purchase number or supplier invoice number.

date
string <date>

Purchase date.

due_date
string <date>

Payment due date of the purchase.

currency
string

ISO currency code of the purchase totals.

iban
string

IBAN to use for payment when it differs from the supplier's default IBAN.

total_without_tax
number

Total amount excluding tax.

total_with_tax
number

Total amount including tax.

Array of objects

References linked to the purchase.

Responses

Request samples

Content type
application/json
{
  • "supplier_id": 12,
  • "state": "accepted",
  • "number": "AANK-2026-0033",
  • "date": "2026-05-15",
  • "due_date": "2026-06-14",
  • "currency": "EUR",
  • "iban": "BE68539007547034",
  • "total_without_tax": 200,
  • "total_with_tax": 242,
  • "references": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a purchase

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
purchaseId
required
integer
Request Body schema: application/json
required
supplier_id
integer

Internal id of the supplier to link to the purchase.

supplier_name
string

Supplier name stored on the purchase, mainly used when no supplier is linked.

state
string
Enum: "pending" "accepted" "overdue" "rejected" "paid" "incomplete" "processing" "payment_scheduled"

New workflow state of the purchase.

number
string

Purchase number or supplier invoice number.

date
string <date>

Purchase date.

due_date
string <date>

Payment due date of the purchase.

currency
string

ISO currency code of the purchase totals.

iban
string

IBAN to use for payment when it differs from the supplier's default IBAN.

total_without_tax
number

Total amount excluding tax.

total_with_tax
number

Total amount including tax.

Array of objects

References linked to the purchase.

Responses

Request samples

Content type
application/json
{
  • "supplier_id": 12,
  • "state": "accepted",
  • "number": "AANK-2026-0033",
  • "date": "2026-05-15",
  • "due_date": "2026-06-14",
  • "currency": "EUR",
  • "iban": "BE68539007547034",
  • "total_without_tax": 200,
  • "total_with_tax": 242,
  • "references": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a purchase

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
purchaseId
required
integer

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Upload a purchase file and create a purchase

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
Request Body schema: multipart/form-data
required
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "success": "purchase created",
  • "purchase_id": 123,
  • "uri": "https://deroos.dkpa.be/api/v1/purchases/123"
}

Send a purchase to the accountant

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
purchaseId
required
integer
Request Body schema: application/json
boolean or string

When enabled, no message is sent to the accountant; the purchase is only marked as sent to the accountant.

Responses

Request samples

Content type
application/json
{
  • "mark_as_sent": true
}

Response samples

Content type
application/json
{
  • "success": "string"
}

List purchase files

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
purchaseId
required
integer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a purchase file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
purchaseId
required
integer
purchaseFileId
required
integer

Responses

Response samples

Content type
application/json
{
  • "file_id": 61,
  • "uri": "https://deroos.dkpa.be/api/v1/purchases/33/files/61",
  • "type": "primary",
  • "filename": "office-supplies.pdf",
  • "content_type": "application/pdf",
  • "created": "2026-05-15T08:30:00Z"
}

Delete a purchase file

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
purchaseId
required
integer
purchaseFileId
required
integer

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Upload a purchase attachment

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
purchaseId
required
integer
Request Body schema: multipart/form-data
required
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "success": "purchase file created",
  • "file_id": 456,
  • "uri": "https://deroos.dkpa.be/api/v1/purchases/123/files/456"
}

Suppliers

List suppliers

Supports JSON, XML, CSV, and HTML responses for supplier listings.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a supplier

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
Request Body schema: application/json
required
name
string

Supplier name.

vat_number
string

VAT number of the supplier.

company_id
string

Company registration number of the supplier.

street
string

Street and house number of the supplier.

postal_code
string

Postal code of the supplier.

city
string

City of the supplier.

country_code
string

ISO country code of the supplier.

iban
string

IBAN used for payments to the supplier.

email_address
string

E-mail address of the supplier.

phone_number
string

Phone number of the supplier.

default_purchase_state
string
Enum: "pending" "accepted" "payment_scheduled" "paid"

Default state assigned to purchases for this supplier.

Array of objects

References linked to the supplier.

Responses

Request samples

Content type
application/json
{
  • "name": "Example Supplier NV",
  • "vat_number": "BE0123456789",
  • "company_id": "0123456789",
  • "street": "Examplelaan 1",
  • "postal_code": "1000",
  • "city": "Brussel",
  • "country_code": "BE",
  • "iban": "",
  • "email_address": "",
  • "phone_number": "",
  • "default_purchase_state": "pending",
  • "references": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "supplier created",
  • "supplier_id": 45,
  • "uri": "https://deroos.dkpa.be/api/v1/suppliers/45"
}

Get a supplier

Supports JSON, XML, CSV, and HTML responses for a single supplier resource.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
supplierId
required
integer

Responses

Response samples

Content type
application/json
{
  • "supplier_id": 45,
  • "uri": "https://deroos.dkpa.be/api/v1/suppliers/45",
  • "name": "Example Supplier NV",
  • "vat_number": "BE0123456789",
  • "company_id": "0123456789",
  • "street": "Examplelaan 1",
  • "postal_code": "1000",
  • "city": "Brussel",
  • "country_code": "BE",
  • "iban": "",
  • "email_address": "",
  • "phone_number": "",
  • "default_purchase_state": "pending",
  • "created": "2026-05-02",
  • "references": [
    ]
}

Partially update a supplier

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
supplierId
required
integer
Request Body schema: application/json
required
name
string

Supplier name.

vat_number
string

VAT number of the supplier.

company_id
string

Company registration number of the supplier.

street
string

Street and house number of the supplier.

postal_code
string

Postal code of the supplier.

city
string

City of the supplier.

country_code
string

ISO country code of the supplier.

iban
string

IBAN used for payments to the supplier.

email_address
string

E-mail address of the supplier.

phone_number
string

Phone number of the supplier.

default_purchase_state
string
Enum: "pending" "accepted" "payment_scheduled" "paid"

Default state assigned to purchases for this supplier.

Array of objects

References linked to the supplier.

Responses

Request samples

Content type
application/json
{
  • "name": "Example Supplier NV",
  • "vat_number": "BE0123456789",
  • "company_id": "0123456789",
  • "street": "Examplelaan 1",
  • "postal_code": "1000",
  • "city": "Brussel",
  • "country_code": "BE",
  • "iban": "",
  • "email_address": "",
  • "phone_number": "",
  • "default_purchase_state": "pending",
  • "references": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a supplier

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
supplierId
required
integer
Request Body schema: application/json
required
name
string

Supplier name.

vat_number
string

VAT number of the supplier.

company_id
string

Company registration number of the supplier.

street
string

Street and house number of the supplier.

postal_code
string

Postal code of the supplier.

city
string

City of the supplier.

country_code
string

ISO country code of the supplier.

iban
string

IBAN used for payments to the supplier.

email_address
string

E-mail address of the supplier.

phone_number
string

Phone number of the supplier.

default_purchase_state
string
Enum: "pending" "accepted" "payment_scheduled" "paid"

Default state assigned to purchases for this supplier.

Array of objects

References linked to the supplier.

Responses

Request samples

Content type
application/json
{
  • "name": "Example Supplier NV",
  • "vat_number": "BE0123456789",
  • "company_id": "0123456789",
  • "street": "Examplelaan 1",
  • "postal_code": "1000",
  • "city": "Brussel",
  • "country_code": "BE",
  • "iban": "",
  • "email_address": "",
  • "phone_number": "",
  • "default_purchase_state": "pending",
  • "references": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a supplier

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
supplierId
required
integer

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Projects

List projects

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a project

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
Request Body schema: application/json
required
external_project_id
string

External identifier managed by the integrating system.

user_id
integer or null

Internal id of the user assigned to the project.

client_id
required
integer

Internal id of the client linked to the project.

number
string

Human-readable project number.

name
string

Project name.

start_date
string <date>

Start date of the project.

end_date
string or null <date>

End date of the project.

state
string
Enum: "prepare" "open" "done" "closed" "cancelled"

Current state of the project.

billable_type
string
Enum: "hourly" "daily"

Method used to calculate billable work. hourly makes billable_rate an hourly rate and billable_estimate a number of hours; daily makes them a daily rate and a number of days.

billable_rate
number >= 0

Rate used for billable work. It is an amount per hour for hourly projects or per day for daily projects.

billable_estimate
number >= 0

Estimated billable quantity. It is a number of hours for hourly projects or a number of days for daily projects.

boolean or string

Whether the project uses tasks. When set to no, the project uses one fixed default task.

Array of objects (ProjectTaskWrite)

Tasks to create together with the project.

fixed_break
number >= 0

Fixed break deducted from time entries.

Responses

Request samples

Content type
application/json
{
  • "external_project_id": "PROJECT-123",
  • "user_id": null,
  • "client_id": 45,
  • "number": "P000123",
  • "name": "Example project",
  • "start_date": "2026-05-01",
  • "end_date": "2026-05-31",
  • "state": "open",
  • "billable_type": "daily",
  • "billable_rate": 500,
  • "billable_estimate": 50,
  • "use_tasks": "yes",
  • "tasks": [
    ],
  • "fixed_break": 0
}

Response samples

Content type
application/json
{
  • "success": "project created",
  • "project_id": 123,
  • "uri": "https://deroos.dkpa.be/api/v1/projects/123"
}

Get a project

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer

Responses

Response samples

Content type
application/json
{
  • "project_id": 123,
  • "uri": "https://deroos.dkpa.be/api/v1/projects/123",
  • "external_project_id": "",
  • "user_id": null,
  • "user_name": "",
  • "client_id": 45,
  • "client_uri": "https://deroos.dkpa.be/api/v1/clients/45",
  • "client_name": "Example Client NV",
  • "client_attention": "",
  • "billing_address": {
    },
  • "delivery_address": null,
  • "site_address": null,
  • "number": "P000123",
  • "name": "Example project",
  • "start_date": "2026-05-01",
  • "end_date": "2026-05-31",
  • "state": "open",
  • "billable_type": "daily",
  • "billable_rate": 500,
  • "billable_estimate": 50,
  • "billable_current": 5,
  • "total": 2500,
  • "total_estimate": 0,
  • "fixed_break": 0,
  • "use_tasks": "no",
  • "tasks": [
    ],
  • "last_activity": "2026-05-26 20:00:17"
}

Partially update a project

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
Request Body schema: application/json
required
external_project_id
string

External identifier managed by the integrating system.

user_id
integer or null

Internal id of the user assigned to the project.

client_id
required
integer

Internal id of the client linked to the project.

number
string

Human-readable project number.

name
string

Project name.

start_date
string <date>

Start date of the project.

end_date
string or null <date>

End date of the project.

state
string
Enum: "prepare" "open" "done" "closed" "cancelled"

Current state of the project.

billable_type
string
Enum: "hourly" "daily"

Method used to calculate billable work. hourly makes billable_rate an hourly rate and billable_estimate a number of hours; daily makes them a daily rate and a number of days.

billable_rate
number >= 0

Rate used for billable work. It is an amount per hour for hourly projects or per day for daily projects.

billable_estimate
number >= 0

Estimated billable quantity. It is a number of hours for hourly projects or a number of days for daily projects.

boolean or string

Whether the project uses tasks. When set to no, the project uses one fixed default task.

Array of objects (ProjectTaskWrite)

Tasks to create together with the project.

fixed_break
number >= 0

Fixed break deducted from time entries.

Responses

Request samples

Content type
application/json
{
  • "external_project_id": "PROJECT-123",
  • "user_id": null,
  • "client_id": 45,
  • "number": "P000123",
  • "name": "Example project",
  • "start_date": "2026-05-01",
  • "end_date": "2026-05-31",
  • "state": "open",
  • "billable_type": "daily",
  • "billable_rate": 500,
  • "billable_estimate": 50,
  • "use_tasks": "yes",
  • "tasks": [
    ],
  • "fixed_break": 0
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a project

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
Request Body schema: application/json
required
external_project_id
string

External identifier managed by the integrating system.

user_id
integer or null

Internal id of the user assigned to the project.

client_id
required
integer

Internal id of the client linked to the project.

number
string

Human-readable project number.

name
string

Project name.

start_date
string <date>

Start date of the project.

end_date
string or null <date>

End date of the project.

state
string
Enum: "prepare" "open" "done" "closed" "cancelled"

Current state of the project.

billable_type
string
Enum: "hourly" "daily"

Method used to calculate billable work. hourly makes billable_rate an hourly rate and billable_estimate a number of hours; daily makes them a daily rate and a number of days.

billable_rate
number >= 0

Rate used for billable work. It is an amount per hour for hourly projects or per day for daily projects.

billable_estimate
number >= 0

Estimated billable quantity. It is a number of hours for hourly projects or a number of days for daily projects.

boolean or string

Whether the project uses tasks. When set to no, the project uses one fixed default task.

Array of objects (ProjectTaskWrite)

Tasks to create together with the project.

fixed_break
number >= 0

Fixed break deducted from time entries.

Responses

Request samples

Content type
application/json
{
  • "external_project_id": "PROJECT-123",
  • "user_id": null,
  • "client_id": 45,
  • "number": "P000123",
  • "name": "Example project",
  • "start_date": "2026-05-01",
  • "end_date": "2026-05-31",
  • "state": "open",
  • "billable_type": "daily",
  • "billable_rate": 500,
  • "billable_estimate": 50,
  • "use_tasks": "yes",
  • "tasks": [
    ],
  • "fixed_break": 0
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a project

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List project tasks

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a project task

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
Request Body schema: application/json
required
description
string

Plain-text task description.

description_html
string

HTML task description. Takes precedence over description when both are sent.

state
string
Enum: "prepare" "open" "done" "closed" "cancelled"

Current state of the task.

Array of objects (ProjectItemWrite)

Time and material entries to create for the task.

Responses

Request samples

Content type
application/json
{
  • "description": "Example task",
  • "state": "open",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "task created",
  • "project_id": 123,
  • "task_id": 456,
  • "uri": "https://deroos.dkpa.be/api/v1/projects/123/tasks/456"
}

Get a project task

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
taskId
required
integer

Responses

Response samples

Content type
application/json
{
  • "task_id": 456,
  • "uri": "https://deroos.dkpa.be/api/v1/projects/123/tasks/456",
  • "description": "Example task",
  • "description_html": "<p>Example task</p>",
  • "state": "open",
  • "items": [
    ]
}

Partially update a project task

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
taskId
required
integer
Request Body schema: application/json
required
description
string

Plain-text task description.

description_html
string

HTML task description. Takes precedence over description when both are sent.

state
string
Enum: "prepare" "open" "done" "closed" "cancelled"

Current state of the task.

Array of objects (ProjectItemWrite)

Time and material entries to create for the task.

Responses

Request samples

Content type
application/json
{
  • "description": "Example task",
  • "state": "open",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a project task

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
taskId
required
integer
Request Body schema: application/json
required
description
string

Plain-text task description.

description_html
string

HTML task description. Takes precedence over description when both are sent.

state
string
Enum: "prepare" "open" "done" "closed" "cancelled"

Current state of the task.

Array of objects (ProjectItemWrite)

Time and material entries to create for the task.

Responses

Request samples

Content type
application/json
{
  • "description": "Example task",
  • "state": "open",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a project task

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
taskId
required
integer

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List project task items

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
taskId
required
integer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a project task item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
taskId
required
integer
Request Body schema: application/json
required
type
string
Enum: "time" "cost"

Type of project task item.

description
string

Plain-text item description.

description_html
string

HTML item description. Takes precedence over description when both are sent.

date
string or null <date>

Start date of the item.

end_date
string or null <date>

End date of the item.

start_time
string

Start time of the item.

end_time
string

End time of the item.

fixed_break
number >= 0

Fixed break deducted from the item.

quantity
number

Quantity recorded for the item.

unit
string

Unit of the recorded quantity.

price
number

Unit price of the item.

state
string
Enum: "open" "done" "ignore" "estimate"

Current state of the item.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "time",
  • "description": "Worked hours",
  • "date": "2026-05-26",
  • "start_time": "09:00",
  • "end_time": "14:00",
  • "fixed_break": 0,
  • "quantity": 5,
  • "unit": "hour",
  • "price": 100,
  • "state": "open"
}

Response samples

Content type
application/json
{
  • "success": "item created",
  • "project_id": 123,
  • "task_id": 456,
  • "item_id": 789,
  • "uri": "https://deroos.dkpa.be/api/v1/projects/123/tasks/456/items/789"
}

Get a project task item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
taskId
required
integer
itemId
required
integer

Responses

Response samples

Content type
application/json
{
  • "item_id": 789,
  • "uri": "https://deroos.dkpa.be/api/v1/projects/123/tasks/456/items/789",
  • "type": "time",
  • "description": "Worked hours",
  • "description_html": "Worked hours",
  • "date": "2026-05-26",
  • "end_date": null,
  • "start_time": "",
  • "end_time": "",
  • "fixed_break": 0,
  • "quantity": 5,
  • "unit": "",
  • "price": 500,
  • "price_total": 2500,
  • "state": "open"
}

Partially update a project task item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
taskId
required
integer
itemId
required
integer
Request Body schema: application/json
required
type
string
Enum: "time" "cost"

Type of project task item.

description
string

Plain-text item description.

description_html
string

HTML item description. Takes precedence over description when both are sent.

date
string or null <date>

Start date of the item.

end_date
string or null <date>

End date of the item.

start_time
string

Start time of the item.

end_time
string

End time of the item.

fixed_break
number >= 0

Fixed break deducted from the item.

quantity
number

Quantity recorded for the item.

unit
string

Unit of the recorded quantity.

price
number

Unit price of the item.

state
string
Enum: "open" "done" "ignore" "estimate"

Current state of the item.

Responses

Request samples

Content type
application/json
{
  • "type": "time",
  • "description": "Worked hours",
  • "date": "2026-05-26",
  • "end_date": null,
  • "start_time": "",
  • "end_time": "",
  • "fixed_break": 0,
  • "quantity": 5,
  • "unit": "hour",
  • "price": 500,
  • "state": "open"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a project task item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
taskId
required
integer
itemId
required
integer
Request Body schema: application/json
required
type
string
Enum: "time" "cost"

Type of project task item.

description
string

Plain-text item description.

description_html
string

HTML item description. Takes precedence over description when both are sent.

date
string or null <date>

Start date of the item.

end_date
string or null <date>

End date of the item.

start_time
string

Start time of the item.

end_time
string

End time of the item.

fixed_break
number >= 0

Fixed break deducted from the item.

quantity
number

Quantity recorded for the item.

unit
string

Unit of the recorded quantity.

price
number

Unit price of the item.

state
string
Enum: "open" "done" "ignore" "estimate"

Current state of the item.

Responses

Request samples

Content type
application/json
{
  • "type": "time",
  • "description": "Worked hours",
  • "date": "2026-05-26",
  • "end_date": null,
  • "start_time": "",
  • "end_time": "",
  • "fixed_break": 0,
  • "quantity": 5,
  • "unit": "hour",
  • "price": 500,
  • "state": "open"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a project task item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
projectId
required
integer
taskId
required
integer
itemId
required
integer

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Banking

List bank accounts

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a bank account

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
Request Body schema: application/json
required
number
string

Bank account number, such as an IBAN.

name
string

Display name of the bank account. Defaults to number when omitted.

boolean or string

Whether the bank account is active. Defaults to active when omitted.

boolean or string

Whether this is the default bank account. Defaults to yes only when no other active default bank account exists.

Responses

Request samples

Content type
application/json
{
  • "number": "BE00000000000000",
  • "name": "Example Company BV",
  • "active": "yes",
  • "default": "yes"
}

Response samples

Content type
application/json
{
  • "success": "bank account created",
  • "bankaccount_id": 123,
  • "uri": "https://deroos.dkpa.be/api/v1/bankaccounts/123"
}

Get a bank account

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankAccountId
required
integer

Responses

Response samples

Content type
application/json
{
  • "bankaccount_id": 123,
  • "number": "BE00000000000000",
  • "name": "Example Company BV",
  • "active": "yes",
  • "default": "yes"
}

Partially update a bank account

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankAccountId
required
integer
Request Body schema: application/json
required
number
string

Bank account number, such as an IBAN.

name
string

Display name of the bank account. Defaults to number when omitted.

boolean or string

Whether the bank account is active. Defaults to active when omitted.

boolean or string

Whether this is the default bank account. Defaults to yes only when no other active default bank account exists.

Responses

Request samples

Content type
application/json
{
  • "number": "BE00000000000000",
  • "name": "Example Company BV",
  • "active": "yes",
  • "default": "yes"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a bank account

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankAccountId
required
integer
Request Body schema: application/json
required
number
string

Bank account number, such as an IBAN.

name
string

Display name of the bank account. Defaults to number when omitted.

boolean or string

Whether the bank account is active. Defaults to active when omitted.

boolean or string

Whether this is the default bank account. Defaults to yes only when no other active default bank account exists.

Responses

Request samples

Content type
application/json
{
  • "number": "BE00000000000000",
  • "name": "Example Company BV",
  • "active": "yes",
  • "default": "yes"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a bank account

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankAccountId
required
integer

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List bank transactions

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a bank transaction

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-Apply-Allocations
boolean
Default: true

Whether payments from allocations are applied to their linked invoice, receipt, payment request, or purchase. When enabled, the linked document's payment status is updated as well. Defaults to true.

Request Body schema: application/json
required
bankaccount_id
integer or null

Internal id of the bank account to link.

number
string

Human-readable transaction number.

date
string <date>

Transaction date.

amount
number

Transaction amount. Debits are negative and credits are positive.

currency
string

ISO currency code of the transaction.

counterpart_account_number
string

Account number of the counterparty.

counterpart_account_name
string

Account holder name of the counterparty.

message
string

Payment message or bank communication.

status
string
Enum: "pending" "allocated" "assigned" "external" "unmatched" "dismissed" "mixed"

Allocation status of the transaction.

source
string
Enum: "unknown" "manual" "file" "codabox" "ponto" "enablebanking"

Origin of the bank transaction.

source_reference
string

Reference supplied by the transaction source.

Array of objects (BankTransactionAllocationWrite)

Allocations to create or update with the transaction.

Responses

Request samples

Content type
application/json
{
  • "bankaccount_id": null,
  • "number": "2026/00001",
  • "date": "2026-05-26",
  • "amount": -242,
  • "currency": "EUR",
  • "counterpart_account_number": "Example counterpart account",
  • "counterpart_account_name": "",
  • "message": "Payment reference",
  • "status": "unmatched",
  • "source": "manual",
  • "source_reference": "",
  • "allocations": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "bank transaction created",
  • "banktransaction_id": 456,
  • "uri": "https://deroos.dkpa.be/api/v1/banktransactions/456"
}

Get a bank transaction

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankTransactionId
required
integer

Responses

Response samples

Content type
application/json
{
  • "banktransaction_id": 123,
  • "bankaccount_id": null,
  • "bankaccount": null,
  • "number": "2026/00001",
  • "date": "2026-05-26",
  • "amount": -242,
  • "amount_to_allocate": -121,
  • "currency": "EUR",
  • "counterpart_account_number": "Example counterpart account",
  • "counterpart_account_name": "",
  • "message": "Payment reference",
  • "status": "unmatched",
  • "source": "unknown",
  • "source_reference": "",
  • "created": "2026-05-27 09:15:00",
  • "updated": "2026-05-27 09:15:00",
  • "allocations": [
    ]
}

Partially update a bank transaction

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankTransactionId
required
integer
header Parameters
X-Apply-Allocations
boolean
Default: true

Whether payments from allocations are applied to their linked invoice, receipt, payment request, or purchase. When enabled, the linked document's payment status is updated as well. Defaults to true.

Request Body schema: application/json
required
bankaccount_id
integer or null

Internal id of the bank account to link.

number
string

Human-readable transaction number.

date
string <date>

Transaction date.

amount
number

Transaction amount. Debits are negative and credits are positive.

currency
string

ISO currency code of the transaction.

counterpart_account_number
string

Account number of the counterparty.

counterpart_account_name
string

Account holder name of the counterparty.

message
string

Payment message or bank communication.

status
string
Enum: "pending" "allocated" "assigned" "external" "unmatched" "dismissed" "mixed"

Allocation status of the transaction.

source
string
Enum: "unknown" "manual" "file" "codabox" "ponto" "enablebanking"

Origin of the bank transaction.

source_reference
string

Reference supplied by the transaction source.

Array of objects (BankTransactionAllocationWrite)

Allocations to create or update with the transaction.

Responses

Request samples

Content type
application/json
{
  • "bankaccount_id": null,
  • "number": "2026/00001",
  • "date": "2026-05-26",
  • "amount": -242,
  • "currency": "EUR",
  • "counterpart_account_number": "Example counterpart account",
  • "counterpart_account_name": "",
  • "message": "Payment reference",
  • "status": "unmatched",
  • "source": "manual",
  • "source_reference": "",
  • "allocations": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a bank transaction

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankTransactionId
required
integer
header Parameters
X-Apply-Allocations
boolean
Default: true

Whether payments from allocations are applied to their linked invoice, receipt, payment request, or purchase. When enabled, the linked document's payment status is updated as well. Defaults to true.

Request Body schema: application/json
required
bankaccount_id
integer or null

Internal id of the bank account to link.

number
string

Human-readable transaction number.

date
string <date>

Transaction date.

amount
number

Transaction amount. Debits are negative and credits are positive.

currency
string

ISO currency code of the transaction.

counterpart_account_number
string

Account number of the counterparty.

counterpart_account_name
string

Account holder name of the counterparty.

message
string

Payment message or bank communication.

status
string
Enum: "pending" "allocated" "assigned" "external" "unmatched" "dismissed" "mixed"

Allocation status of the transaction.

source
string
Enum: "unknown" "manual" "file" "codabox" "ponto" "enablebanking"

Origin of the bank transaction.

source_reference
string

Reference supplied by the transaction source.

Array of objects (BankTransactionAllocationWrite)

Allocations to create or update with the transaction.

Responses

Request samples

Content type
application/json
{
  • "bankaccount_id": null,
  • "number": "2026/00001",
  • "date": "2026-05-26",
  • "amount": -242,
  • "currency": "EUR",
  • "counterpart_account_number": "Example counterpart account",
  • "counterpart_account_name": "",
  • "message": "Payment reference",
  • "status": "unmatched",
  • "source": "manual",
  • "source_reference": "",
  • "allocations": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a bank transaction

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankTransactionId
required
integer
header Parameters
X-Apply-Allocations
boolean
Default: true

Whether payments from allocations are applied to their linked invoice, receipt, payment request, or purchase. When enabled, the linked document's payment status is updated as well. Defaults to true.

X-Delete-Mode
string
Default: soft
Enum: "soft" "hard"

Deletion mode. Defaults to soft; use hard to permanently remove the bank transaction.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Import bank transactions from a file

Upload the raw contents of a bank-statement file. Do not use multipart/form-data. Select the parser through {importType} and optionally link the imported transactions to an existing bank account with X-BankAccountId or X-IBAN.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
importType
required
string
Enum: "coda" "mt940" "csv_bnpparibas" "csv_belfius" "csv_crelan" "csv_kbc" "csv_ing" "csv_triodos"

Format of the uploaded bank-statement file.

header Parameters
X-Filename
string
Example: bank-statement.cod

Original filename. It is stored as the source reference on imported transactions.

X-BankAccountId
integer
Example: 123

Internal id of the bank account to link to every imported transaction. Takes precedence over X-IBAN.

X-IBAN
string
Example: BE00000000000000

IBAN of the bank account to link. When no account with this IBAN exists, one is created automatically. Ignored when X-BankAccountId is supplied.

Request Body schema: application/octet-stream
required
string <binary>

Raw bank-statement file contents.

Responses

Response samples

Content type
application/json
{
  • "success": "bank transactions imported",
  • "banktransaction_count": 12
}

Batch process bank transactions

Creates, partially updates, replaces, or deletes up to 100 bank transactions in one atomic request. Every action must have a type; update, replace, and delete additionally require banktransaction_id. If one action fails, no action in the batch is applied.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-Apply-Allocations
boolean
Default: true

Whether payments from allocations are applied to their linked invoice, receipt, payment request, or purchase while processing the batch. When enabled, the linked document's payment status is updated as well. Defaults to true.

X-Delete-Mode
string
Default: soft
Enum: "soft" "hard"

Deletion mode. Defaults to soft; use hard to permanently remove the bank transaction.

Request Body schema: application/json
required
required
Array of BankTransactionBatchCreateAction (object) or BankTransactionBatchUpdateAction (object) or BankTransactionBatchReplaceAction (object) or BankTransactionBatchDeleteAction (object) [ 1 .. 100 ] items

Actions to process atomically.

Responses

Request samples

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

Response samples

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

List bank transaction allocations

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankTransactionId
required
integer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a bank transaction allocation

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankTransactionId
required
integer
header Parameters
X-Apply-Allocations
boolean
Default: true

Whether payments from allocations are applied to their linked invoice, receipt, payment request, or purchase. When enabled, the linked document's payment status is updated as well. Defaults to true.

Request Body schema: application/json
required
amount
number

Amount allocated to the linked entity.

invoice_id
integer or null

Internal id of the invoice to link. Supply at most one of the linked id fields for an allocation.

receipt_id
integer or null

Internal id of the receipt to link. Supply at most one of the linked id fields for an allocation.

paymentrequest_id
integer or null

Internal id of the payment request to link. Supply at most one of the linked id fields for an allocation.

purchase_id
integer or null

Internal id of the purchase to link. Supply at most one of the linked id fields for an allocation.

client_id
integer or null

Internal id of the client to link. Supply at most one of the linked id fields for an allocation.

supplier_id
integer or null

Internal id of the supplier to link. Supply at most one of the linked id fields for an allocation.

reference
string

Free external reference to use only when no invoice_id, receipt_id, paymentrequest_id, purchase_id, client_id, or supplier_id is supplied. When used, the status is determined automatically as external.

Responses

Request samples

Content type
application/json
{
  • "amount": -121,
  • "invoice_id": 789
}

Response samples

Content type
application/json
{
  • "success": "bank transaction allocation created",
  • "allocation_id": 789,
  • "uri": "https://deroos.dkpa.be/api/v1/banktransactions/456/allocations/789"
}

Delete all allocations for a bank transaction

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankTransactionId
required
integer
header Parameters
X-Apply-Allocations
boolean
Default: true

Whether payments from allocations are applied to their linked invoice, receipt, payment request, or purchase. When enabled, the linked document's payment status is updated as well. Defaults to true.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Get a bank transaction allocation

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankTransactionId
required
integer
allocationId
required
integer

Responses

Response samples

Content type
application/json
{
  • "allocation_id": 456,
  • "status": "allocated",
  • "amount": -121,
  • "invoice_id": 789,
  • "invoice_number": "2026-0001",
  • "receipt_id": null,
  • "paymentrequest_id": null,
  • "purchase_id": null,
  • "client_id": null,
  • "supplier_id": null,
  • "reference": "",
  • "created": "2026-05-27 09:15:00"
}

Partially update a bank transaction allocation

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankTransactionId
required
integer
allocationId
required
integer
header Parameters
X-Apply-Allocations
boolean
Default: true

Whether payments from allocations are applied to their linked invoice, receipt, payment request, or purchase. When enabled, the linked document's payment status is updated as well. Defaults to true.

Request Body schema: application/json
required
amount
number

Amount allocated to the linked entity.

invoice_id
integer or null

Internal id of the invoice to link. Supply at most one of the linked id fields for an allocation.

receipt_id
integer or null

Internal id of the receipt to link. Supply at most one of the linked id fields for an allocation.

paymentrequest_id
integer or null

Internal id of the payment request to link. Supply at most one of the linked id fields for an allocation.

purchase_id
integer or null

Internal id of the purchase to link. Supply at most one of the linked id fields for an allocation.

client_id
integer or null

Internal id of the client to link. Supply at most one of the linked id fields for an allocation.

supplier_id
integer or null

Internal id of the supplier to link. Supply at most one of the linked id fields for an allocation.

reference
string

Free external reference to use only when no invoice_id, receipt_id, paymentrequest_id, purchase_id, client_id, or supplier_id is supplied. When used, the status is determined automatically as external.

Responses

Request samples

Content type
application/json
{
  • "amount": -121,
  • "invoice_id": 789
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a bank transaction allocation

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankTransactionId
required
integer
allocationId
required
integer
header Parameters
X-Apply-Allocations
boolean
Default: true

Whether payments from allocations are applied to their linked invoice, receipt, payment request, or purchase. When enabled, the linked document's payment status is updated as well. Defaults to true.

Request Body schema: application/json
required
amount
number

Amount allocated to the linked entity.

invoice_id
integer or null

Internal id of the invoice to link. Supply at most one of the linked id fields for an allocation.

receipt_id
integer or null

Internal id of the receipt to link. Supply at most one of the linked id fields for an allocation.

paymentrequest_id
integer or null

Internal id of the payment request to link. Supply at most one of the linked id fields for an allocation.

purchase_id
integer or null

Internal id of the purchase to link. Supply at most one of the linked id fields for an allocation.

client_id
integer or null

Internal id of the client to link. Supply at most one of the linked id fields for an allocation.

supplier_id
integer or null

Internal id of the supplier to link. Supply at most one of the linked id fields for an allocation.

reference
string

Free external reference to use only when no invoice_id, receipt_id, paymentrequest_id, purchase_id, client_id, or supplier_id is supplied. When used, the status is determined automatically as external.

Responses

Request samples

Content type
application/json
{
  • "amount": -121,
  • "invoice_id": 789
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a bank transaction allocation

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
bankTransactionId
required
integer
allocationId
required
integer
header Parameters
X-Apply-Allocations
boolean
Default: true

Whether payments from allocations are applied to their linked invoice, receipt, payment request, or purchase. When enabled, the linked document's payment status is updated as well. Defaults to true.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Accounts

Get the current authenticated identity

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth

Responses

Response samples

Content type
application/json
{
  • "identity": {
    },
  • "account": {
    },
  • "access": {
    }
}

List users for the current account

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

skip
integer >= 0
take
integer >= 1

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a user

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
Request Body schema: application/json
required
object (UserWrite)

Responses

Request samples

Content type
application/json
{
  • "name": "Wim Verstuyf",
  • "email_address": "wim@example.com"
}

Response samples

Content type
application/json
{}

Get a user

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
userId
required
integer

Responses

Response samples

Content type
application/json
{
  • "user_id": 5,
  • "uri": "https://deroos.dkpa.be/api/v1/users/5",
  • "name": "Wim Verstuyf",
  • "email_address": "wim@example.com",
  • "rights": [
    ]
}

Remove a user

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
userId
required
integer

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List SSO entries for a user

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
userId
required
integer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create SSO entries for a user

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
userId
required
integer
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "success": "string"
}

Remove all SSO entries for a user

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
userId
required
integer

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

List accounts

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

skip
integer >= 0
take
integer >= 1

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an account

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
Request Body schema: application/json
required
object (AccountWrite)

Responses

Request samples

Content type
application/json
{
  • "name": "Demo account",
  • "account_type": "company"
}

Response samples

Content type
application/json
{}

Get an account

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
accountIdOrNumber
required
string

Responses

Response samples

Content type
application/json
{
  • "account_id": 101,
  • "number": "EF-101",
  • "name": "Demo account",
  • "account_type": "company"
}

Notifications

List notifications

Returns the notifications for the current account.

When you use ?count, the API returns only notification_count. The filter parameter is not supported together with ?count.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

skip
integer >= 0
take
integer >= 1
count
string

Presence flag that switches the request to count mode. Trigger it by sending ?count without a value.

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Get a notification

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
notificationId
required
integer

Responses

Response samples

Content type
application/json
{
  • "notification_id": 55,
  • "type": "invoice_overdue",
  • "level": "warning",
  • "status": "new",
  • "title": "Invoice overdue",
  • "message": "Invoice 2026-0001 is overdue by 7 days.",
  • "link": null,
  • "date": "2026-06-12 09:30:00",
  • "client_id": 92,
  • "document_id": 1001,
  • "document_type": "invoice",
  • "banktransaction_id": null,
  • "purchase_id": null
}

Update a notification

Only status can be updated.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
notificationId
required
integer
Request Body schema: application/json
required
status
required
string
Enum: "new" "open" "closed"

New status of the notification.

Responses

Request samples

Content type
application/json
{
  • "status": "closed"
}

Response samples

Content type
application/json
{
  • "success": "notification updated"
}

Stock

List stock items

Supports JSON, XML, CSV, and HTML responses for stock item listings. Prefer Accept: application/json for API usage. If no format is specified the API defaults to XML for backwards compatibility.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

search
string

Search using a single free-text term. The search is case-insensitive and the value must be URL-encoded.

filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

sort
string

Sort by one or more supported fields. Separate multiple fields with a comma and prefix a field with - for descending order.

skip
integer >= 0
take
integer >= 1
count
string

Presence flag that switches the request to count mode. Trigger it by sending ?count without a value.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
Example
[
  • {
    }
]

Create a stock item

Creates a new stock item.

code and description are required. type defaults to single when omitted.

For list, combined, and combined_fixed stock items, items is required. Omit stockitem_id when creating a new stock item.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
code
required
string

Unique code of the stock item.

description
string

Plain-text description of the stock item.

description_html
string

HTML version of the stock item description.

Array of objects (StockItemTranslationWrite)

Localized descriptions to store on the stock item.

type
string
Enum: "single" "list" "combined" "combined_fixed"

Stock item type. Defaults to single when omitted.

comments
string

Plain-text internal or additional comments for the stock item.

comments_html
string

HTML version of the stock item comments.

price
number or null

Sales price of the stock item.

cost
number or null

Purchase or cost price of the stock item.

tax_category
integer [ 0 .. 3 ]

VAT category for this stock item.

tax_category_special_status
string

VAT exemption code used together with tax_category 0.

boolean or string

Whether the supplied price already includes tax.

number or string

Available supply for the stock item, or infinite when no stock limit applies.

unit
string

Unit used for quantities of this stock item.

general_ledger_account
string

General ledger account linked to the stock item.

Array of objects (CustomValue)

Custom field values to store on the stock item.

Array of objects (StockItemChildWrite)

Child stock items included when creating a list, combined, or combined_fixed stock item.

null or StockItemCustomPricesWrite (object)

Client-specific price overrides to store on the stock item.

boolean or string

Whether the stock item should be active.

Responses

Request samples

Content type
application/json
{
  • "code": "ART-001",
  • "description": "Support contract",
  • "translations": [
    ],
  • "type": "single",
  • "comments": "Renewable yearly",
  • "price": 75,
  • "cost": 45,
  • "tax_category": 1,
  • "tax_included": "no",
  • "supply": "infinite",
  • "unit": "hour",
  • "general_ledger_account": "700000",
  • "custom_values": [
    ],
  • "custom_prices": {
    },
  • "active": "yes"
}

Response samples

Content type
application/json
{
  • "success": "stockitem created",
  • "stockitem_id": 44,
  • "uri": "https://deroos.dkpa.be/api/v1/stockitems/44"
}

Bulk process stock items

Sends the bulk stock item flow through the regular /stockitems API operation.

You can use the same bulk payload in two ways:

  • send it to /stockitems with header X-Action: bulk
  • send it to /stockitems/bulk without that header

The X-Action: bulk header is optional on /stockitems/bulk.

Send at most 100 stock items per call. Processing is atomic: if one item fails, no stock items are created or updated.

Include stockitem_id to partially update an existing stock item. Omitted fields are left unchanged, matching Partially update a stock item. Omit stockitem_id to create a new stock item.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

X-Action
string
Value: "bulk"

Action override used by the implementation for bulk operations.

Request Body schema: application/json
required
required
Array of objects (StockItemWrite) <= 100 items

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "success": "stockitems processed"
}

Get a stock item

Supports JSON, XML, CSV, and HTML responses for a single stock item resource. Prefer Accept: application/json for API usage. If no format is specified the API defaults to XML for backwards compatibility.

The implementation also accepts multiple ids joined by +.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
required
integer or string

May also be a +-separated list of ids.

query Parameters
format
string
Enum: "xml" "json" "csv" "html"

Optional response format override. Prefer the Accept header instead, typically Accept: application/json for API integrations.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/csv" "text/html"

Preferred way to request the response format. Use Accept: application/json for API integrations. If neither Accept nor format is provided, the API defaults to XML for backwards compatibility.

X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
Example
{
  • "stockitem_id": 44,
  • "uri": "https://deroos.dkpa.be/api/v1/stockitems/44",
  • "code": "ART-001",
  • "description": "Support contract",
  • "description_html": "<p>Support contract</p>",
  • "translations": [
    ],
  • "type": "single",
  • "comments": "Renewable yearly",
  • "comments_html": "<p>Renewable yearly</p>",
  • "price": 75,
  • "cost": 45,
  • "tax_category": 1,
  • "tax_category_special_status": "",
  • "tax_included": false,
  • "supply": "infinite",
  • "unit": "hour",
  • "general_ledger_account": "700000",
  • "custom_values": [
    ],
  • "items": null,
  • "custom_prices": {
    },
  • "active": "yes",
  • "last_activity": "2026-06-11 09:30:00"
}

Partially update a stock item

Only the fields you send are updated. Any fields you omit keep their existing value.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
stockItemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
stockitem_id
integer

Include this field only when using bulk processing to update an existing stock item.

code
string

Unique code of the stock item.

description
string

Plain-text description of the stock item.

description_html
string

HTML version of the stock item description.

Array of objects (StockItemTranslationWrite)

Localized descriptions to store on the stock item.

type
string
Enum: "single" "list" "combined" "combined_fixed"

Stock item type.

comments
string

Plain-text internal or additional comments for the stock item.

comments_html
string

HTML version of the stock item comments.

price
number or null

Sales price of the stock item.

cost
number or null

Purchase or cost price of the stock item.

tax_category
integer [ 0 .. 3 ]

VAT category for this stock item.

tax_category_special_status
string

VAT exemption code used together with tax_category 0.

boolean or string

Whether the supplied price already includes tax.

number or string

Available supply for the stock item, or infinite when no stock limit applies.

unit
string

Unit used for quantities of this stock item.

general_ledger_account
string

General ledger account linked to the stock item.

Array of objects (CustomValue)

Custom field values to store on the stock item.

Array of objects (StockItemChildWrite)

Child stock items included when updating a list, combined, or combined_fixed stock item.

null or StockItemCustomPricesWrite (object)

Client-specific price overrides to store on the stock item.

boolean or string

Whether the stock item should be active.

Responses

Request samples

Content type
application/json
{
  • "description": "Updated support contract",
  • "comments_html": "<p>Renewable every year</p>",
  • "active": "no"
}

Response samples

Content type
application/json
{
  • "success": "stockitem updated"
}

Update a stock item

Replaces the stock item data with the values from the request body.

Fields you do not send are not preserved and may be reset. Use Partially update a stock item if you only want to change specific fields and keep the others unchanged.

code and description are required. For list, combined, and combined_fixed stock items, items is required.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
stockItemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
code
required
string

Unique code of the stock item.

description
string

Plain-text description of the stock item.

description_html
string

HTML version of the stock item description.

Array of objects (StockItemTranslationWrite)

Localized descriptions to store on the stock item.

type
string
Enum: "single" "list" "combined" "combined_fixed"

Stock item type. Defaults to single when omitted.

comments
string

Plain-text internal or additional comments for the stock item.

comments_html
string

HTML version of the stock item comments.

price
number or null

Sales price of the stock item.

cost
number or null

Purchase or cost price of the stock item.

tax_category
integer [ 0 .. 3 ]

VAT category for this stock item.

tax_category_special_status
string

VAT exemption code used together with tax_category 0.

boolean or string

Whether the supplied price already includes tax.

number or string

Available supply for the stock item, or infinite when no stock limit applies.

unit
string

Unit used for quantities of this stock item.

general_ledger_account
string

General ledger account linked to the stock item.

Array of objects (CustomValue)

Custom field values to store on the stock item.

Array of objects (StockItemChildWrite)

Child stock items included when creating a list, combined, or combined_fixed stock item.

null or StockItemCustomPricesWrite (object)

Client-specific price overrides to store on the stock item.

boolean or string

Whether the stock item should be active.

Responses

Request samples

Content type
application/json
{
  • "code": "ART-001",
  • "description": "Support contract",
  • "translations": [
    ],
  • "type": "single",
  • "comments": "Renewable yearly",
  • "price": 75,
  • "cost": 45,
  • "tax_category": 1,
  • "tax_included": "no",
  • "supply": "infinite",
  • "unit": "hour",
  • "general_ledger_account": "700000",
  • "custom_values": [
    ],
  • "custom_prices": {
    },
  • "active": "yes"
}

Response samples

Content type
application/json
{
  • "success": "stockitem updated"
}

Delete a stock item

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
stockItemId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "stockitem removed"
}

Layouts

List layouts

Returns the layouts available in the current account.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a layout

Creates a new layout.

name and version are required. version must be one of predefined, dompdf1 or custom_dompdf.

For predefined layouts, settings and template are not used. For other layout versions, both settings and template are required.

active is optional and defaults to active when omitted.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
name
required
string <= 50 characters
version
required
string
Enum: "predefined" "dompdf1" "custom_dompdf"
object
template
string
boolean or string

Responses

Request samples

Content type
application/json
{
  • "name": "Mijn layout",
  • "version": "dompdf1",
  • "settings": {
    },
  • "template": "<html>Mijn template</html>",
  • "active": "yes"
}

Response samples

Content type
application/json
{
  • "success": "layout created",
  • "uri": "https://deroos.dkpa.be/api/v1/layouts/8001",
  • "layout_id": 8001
}

Get a layout

Returns the layout with the given id.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
layoutId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "layout_id": 8001,
  • "uri": "https://deroos.dkpa.be/api/v1/layouts/8001",
  • "name": "Mijn layout",
  • "version": "dompdf1",
  • "settings": {
    },
  • "template": "<html>Mijn template</html>",
  • "active": "yes"
}

Partially update a layout

Updates only the fields you provide. Fields you do not send remain unchanged.

If you update version to predefined, settings and template are not used. For other layout versions, settings must be an object and template must contain the HTML template when you include those fields in the request.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
layoutId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
name
string <= 50 characters
version
string
Enum: "predefined" "dompdf1" "custom_dompdf"
object
template
string
boolean or string

Responses

Request samples

Content type
application/json
{
  • "name": "Mijn layout",
  • "settings": {
    },
  • "active": "no"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Update a layout

Replaces the layout data with the values from the request body. Fields you do not send are not preserved and may be reset. Use Partially update a layout if you only want to change specific fields.

name and version are required. For layout versions other than predefined, settings and template are also required. active may be sent as true/false or as yes/no.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
layoutId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
name
required
string <= 50 characters
version
required
string
Enum: "predefined" "dompdf1" "custom_dompdf"
object
template
string
boolean or string

Responses

Request samples

Content type
application/json
{
  • "name": "Mijn layout",
  • "version": "dompdf1",
  • "settings": {
    },
  • "template": "<html>Mijn template</html>",
  • "active": "yes"
}

Response samples

Content type
application/json
{
  • "success": "string"
}

Delete a layout

Deletes the layout with the given id.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
layoutId
required
integer
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "string"
}

Accounting

List general ledger accounts

Returns the configured general ledger accounts for the active account.

General ledger accounts are handled as a full list. One account is always marked as the default account.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
filter
string

Filter on one or more top-level fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=city%3DBrussels,name%3D%7ERestaurant.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

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

Replace all general ledger accounts

Replaces the complete list of general ledger accounts for the active account.

Send X-Action: bulk and provide a top-level general_ledger_accounts array. Accounts that are not included in the request are removed. At least one account is required.

The default field is optional per item. If no item is marked as default, the first submitted account becomes the default account automatically. If multiple items are marked as default, only one default account is kept.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-Action
string
Value: "bulk"

Action override used by the implementation for bulk operations.

X-AccountId
string

Optional account number for multi-account access.

Request Body schema: application/json
required
required
Array of objects (GeneralLedgerAccountWrite) non-empty

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "success": "general_ledger_accounts updated"
}

Reset general ledger accounts to defaults

Removes the current custom list and restores the default general ledger account setup.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "success": "general_ledger_accounts reset to defaults"
}

Accounting queue

Files that are ready to be downloaded from the accounting queue, either for a single account or across all linked accounts in a portal.

Get accounting queue summary

Returns a summary of the accounting queue for the authenticated context.

In a client account context, the queue contains files from the personal accounting queue of that account. In a portal context, the queue contains files from all linked accounts.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth

Responses

Response samples

Content type
application/json
Example
{
  • "scope": "account",
  • "file_count": 0,
  • "total_size": 0,
  • "last_added_at": "2019-08-24 14:15:22"
}

List accounting queue files

Returns all files currently available in the accounting queue.

In a client account context, the returned paths are relative to the queue root, for example sales-invoices/invoice.pdf. In a portal context, the returned paths are prefixed with the account number, for example CD12345678/sales-invoices/invoice.pdf.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

skip
integer >= 0
take
integer >= 1
account_id
integer <int32>

Optional account filter for portal context.

When provided, only files for the selected linked account are returned. Takes precedence when both account_id and account_number are provided.

account_number
string

Optional account-number filter for portal context.

As an alternative to account_id, only files for the selected linked account are returned. Unknown or inaccessible account numbers return an empty list.

directory
string
Enum: "sales-invoices" "purchase-invoices" "self-billing-issued" "self-billing-received"

Optional directory filter within the accounting queue.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Download an accounting queue file

Downloads a single file from the accounting queue using an opaque download token.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
downloadToken
required
string

Opaque token identifying a downloadable accounting queue file.

Responses

Response samples

Content type
application/json
{
  • "error": "invalid input"
}

Confirm processed accounting queue files

Confirms one or more successfully processed files.

Files are removed from the accounting queue only after a successful confirmation.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
Request Body schema: application/json
required
required
Array of AccountingQueueConfirmPathFile (object) or AccountingQueueConfirmTokenFile (object)

Files that should be confirmed as successfully processed and removed from the accounting queue.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "success": "files confirmed",
  • "confirmed_file_count": 1,
  • "failed_file_count": 0,
  • "files": [
    ]
}

Activities

List activities

Returns activities generated automatically by the system. Activities are read-only and cannot be created or updated through the API.

Use fields to limit the returned properties and filter to filter the result set.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
query Parameters
fields
string

Comma-separated list of requested fields. Use this parameter to limit the fields returned and improve performance.

filter
string

Filter on one or more top-level activity fields. Use comma-separated expressions in the form field operator value, URL-encoded as needed; supported operators are =, !=, <=, >=, <, >, and =~, for example ?filter=type__eq__invoice_create.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an activity

Returns a single activity by ID. Activities are generated by the system and can only be retrieved through the API.

Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
path Parameters
activityId
required
integer
Example: 7001

Unique ID of the activity to retrieve.

header Parameters
X-AccountId
string

Optional account number for multi-account access.

Responses

Response samples

Content type
application/json
{
  • "activity_id": 7001,
  • "uri": "https://deroos.dkpa.be/api/v1/activities/7001",
  • "type": "invoice_create",
  • "date": "2012-10-01 18:28:35",
  • "user": "John Doe",
  • "description": "Factuur aangemaakt",
  • "information": "Factuur 2012-0001 aangemaakt (ID 2002)",
  • "client_id": 1001,
  • "invoice_id": 2002,
  • "references": [
    ]
}

Utilities

Upload temporary attachment

Upload one or more temporary attachments for later use in other API actions, most notably when sending invoices, quotes, receipts, orders or deliveries by email or peppol.

This call does not send an email by itself. Instead, it stores the uploaded files temporarily and returns an upload_id for each file. You can then include those upload_id values in the attachments argument of a later send request.

Implementation details:

  • Send the files as multipart/form-data
  • Use file for a single file
  • Use file[] to upload multiple files in one request
  • At most 10 files can be uploaded in a single request
  • Each file must be at most 5 MB
  • The returned upload remains available for up to 1 hour after upload
  • If needed, pass the desired filename later in the send request together with the returned upload_id
Authorizations:
ApiKeyAuthBasicAuthOAuth2Auth
header Parameters
X-AccountId
string

Optional account number for multi-account access.

Request Body schema: multipart/form-data
required
One of
file
required
string <binary>

Single file upload.

Responses

Request samples

Content type
multipart/form-data
Example
{
  "file": "<binary pdf content>"
}

Response samples

Content type
application/json
Example
[
  • {
    }
]

Authentication

Create an API key

Requires HTTP Basic Authentication.

For accounts with two-factor authentication (2FA) enabled, the X-Verification-Code header must also be provided and contain a valid 2FA code.

Although API keys can be created through this endpoint, we recommend managing API keys via the web application whenever possible.

Authorizations:
BasicAuth
Request Body schema: application/json
required
name
required
string
rights
Array of strings
Items Enum: "all" "none" "clients" "read_clients" "invoices" "read_invoices" "receipts" "read_receipts" "quotes" "read_quotes" "orders" "read_orders" "deliveries" "read_deliveries" "paymentrequests" "read_paymentrequests" "customdocuments" "read_customdocuments" "subscriptions" "read_subscriptions" "projects" "read_projects" "own_projects" "purchases" "read_purchases" "stock" "read_stock" "reports" "settings" "account" "layouts" "modules" "accesscontrol" "bank" "read_bank"

Optional list of rights for the API key. If omitted, the API key receives full access.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "ERP integration"
}

Response samples

Content type
application/json
{
  • "success": "apikey created",
  • "apikey": "3f5c3d1a-fd30-46b6-a18f-35d0cc5fe8d8"
}

Start OAuth authorization

Start the OAuth 2.0 Authorization Code Flow for a registered application.

The user is redirected to the interactive authorization page, where they log in, select the account to authorize if they have access to multiple accounts, and grant consent. A successful OAuth authorization is always limited to a single account.

To use OAuth, your application must first be registered by the De Roos helpdesk. After registration you receive a client_id and client_secret.

Note: the OAuth endpoints live on the application root and are not prefixed with /api/v1.

After approval, the user is redirected to the supplied redirect_uri with a temporary authorization code. Your application must then exchange that code at /oauth/token.

query Parameters
response_type
required
string
Value: "code"

Must always be code.

client_id
required
string

Client identifier received after registering your application.

redirect_uri
required
string <uri>

One of the redirect URLs registered for your application.

scope
string
Example: scope=invoices:read clients:manage

Space-delimited OAuth scopes to request.

Available scopes: clients:read, clients:manage, invoices:read, invoices:manage, receipts:read, receipts:manage, quotes:read, quotes:manage, orders:read, orders:manage, deliveries:read, deliveries:manage, paymentrequests:read, paymentrequests:manage, customdocuments:read, customdocuments:manage, subscriptions:read, subscriptions:manage, purchases:read, purchases:manage, products:read, products:manage, projects:read, projects:manage, projects:manage:assigned, bank:read, bank:manage, settings:manage, account:manage, layouts:manage, access_control:manage.

Request only the scopes your integration actually needs.

state
string
Example: state=xyz123

Opaque value used by the client to verify the callback and prevent CSRF attacks.

prompt
string
Value: "login"

Use login to force a fresh login during authorization.

Responses

Request samples 

curl -G 'https://deroos.dkpa.be/oauth/authorize' \
  --data-urlencode 'client_id=abcd1234' \
  --data-urlencode 'redirect_uri=https://example.com/callback' \
  --data-urlencode 'response_type=code' \
  --data-urlencode 'scope=invoices:read clients:manage' \
  --data-urlencode 'state=xyz123' \
  --data-urlencode 'prompt=login'

Response samples

Content type
application/json
{
  • "error": "client_id unknown"
}

Request OAuth token

Supports the OAuth 2.0 authorization_code and refresh_token grant types. Client authentication is handled with client_id and client_secret form fields.

Use this endpoint in two situations:

  1. Exchange a temporary authorization code for an access token and refresh token.
  2. Refresh an expired access token by submitting a valid refresh token.

Supported grant types:

  • authorization_code
  • refresh_token

Authorization codes are valid for 10 minutes. Access tokens are valid for 1 hour. Refresh tokens are valid for 3 months.

Use the returned bearer token in the Authorization header of subsequent API requests:

Authorization: Bearer <access_token>

Note: this endpoint is available at /oauth/token and is not prefixed with /api/v1.

Request Body schema: application/x-www-form-urlencoded
required
One of
grant_type
required
string
Value: "authorization_code"

Must be authorization_code.

client_id
required
string

Client identifier received after registering your application.

client_secret
required
string

Client secret received after registering your application.

redirect_uri
required
string <uri>

Redirect URI used in the original authorization request.

code
required
string

Temporary authorization code received on the redirect callback.

Responses

Request samples

Content type
application/x-www-form-urlencoded
Example
grant_type=authorization_code&client_id=abcd1234&client_secret=dcba4321&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&code=AUTH_CODE

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOi...",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "refresh_token": "8xLOxBtZp8"
}