Data Structures & Status Codes

Common Requirements for API Requests

All requests should set the following headers
Accept application/json

Concepts related to Responses

Attributes Common to all Objects

Every object returned by the Keyline API always has the following attributes. So in order to simplify the overall documentation, we list those common attributes here instead of adding them to each object's documentation.
id integer The Keyline internal ID of the invoice
created_at datetime The date and time when the invoice was created
updated_at datetime The date and time when the invoice was last modified

Types Used throughout the API

The Keyline API at some places encodes certain types with some meta-information. In order to simplify the documentation and make it easier to read, those types, that are used across multiple objects, are listed below.


Whenever an attribute in Keyline denotes a money value, such as the net total price of an invoice, it is encoded with the type Money, and contains the following meta-information.

cent_amount integer The amount in cents of the money value.
currency string The ISO code for the currency of the cent_amount field


cent_amount decimal The amount in cents of the money value. Esp. line items can have prices with cent fractions, so this amount is encoded as a decimal.
currency string The ISO code for the currency of the cent_amount field
rate float The tax rate percentage, formatted as a float number, such as that 0.19 translates to a tax rate of 19%

Response Paging

Responses to GET requests that hit index endpoints, such as /api/v1/customers will at most get back a result set of size 100. If the total size of the desired result set exceeds 100, multiple requests need to be made.

If a response's result set was paged, the response headers contain the following extra headers:

X-Keyline-Result-Page Gives the page number of the current returned result subset
X-Keyline-Result-Per-Page Gives the maximum size of the current returned result subset. Is always 100.
X-Keyline-Result-Total Gives the total number of results across all pages.

If a client wants to fetch a page number different from the first, it must specify the parameter page as a query parameter, where page is always an integer, and the lowest page number is always 1.

Status Codes

The Keyline API uses standardised HTTP response codes the inform the caller about the status of any requests.

These are the most common codes you'll get to see:

200 OK Everything is okay
201 Created You just created a new resource
204 No Content The update or delete operation you just ran was successful
400 Bad request The request you made is missing required parameters and cannot be executed
401 Unauthorized You're not allowed to access this resource. Check your access token
404 Not found You tried to access a resource that doesn't exist
422 Unprocessable Entity The validation of the resource you wanted to create or change failed. The JSON will contain a detailed error description
500 Internal Server Error Yikes! This is pretty bad and might be our fault. If you encounter one of these, we are automatically informed, but please contact us with some in-depth infos.

Missing parameters (HTTP 400)

Create and update request have certain requirements regarding the parameters you must submit in order the execute the request. A line item change request for example needs the order information as parameter. If you do not supply this, you will get the following error:

$ curl -X POST

HTTP/1.1 400 Bad Request
  "error_description": "A required parameter for this request was not supplied",
  "missing_parameters": ["order"]

Validation errors (HTTP 422)

If the creation or alteration of a resource failed because some validation criteria were not met, you will get a HTTP response with the status code 422 which contains error information just like in the following example:

$ curl -X POST -d "order[reference]=Piece"

HTTP/1.1 422 Unprocessable Entity
  "errors": {
    "reference": ["cannot be changed"]

What's best to read next?