Read data

Read data

Data are always read with the HTTP GET method either in lists or single resource.

A list will be read on the resource path:

curl -H 'X-BillomatApiKey: {apikey}'
https://{billomatid}.billomat.net/api/clients

When reading a single resource, the URL consists of of the path and the ID of the resource:

curl -H 'X-BillomatApiKey: {apikey}'
https://{billomatid}.billomat.net/api/clients/1

If the request was successful, returns the status 200 OK and the requested data in the desired format.
The number of records per request (for a list of a resource) can be specified via the parameter per_page. Through the individual pages can be navigated with the parameter page:

Paging

curl -H 'X-BillomatApiKey: {apikey}'
https://{billomatid}.billomat.net/api/clients?per_page=50&page=2

shows 50 clients per page and the 2nd page (entries from 51 – 100).
The XML root element of a resource list also provides for better orientation the attributes page (current page), per_page (entries per page) and total (total number over all pages). Default value for page is 1 and for per_page is 100, maximum 1000 entries can be returned per page.

Filtering

It is possible to filter lists with filter parameters. Supported filters are documented in the particular resource descriptions.

You may only want to know how many hits a filtering returns. In this case, you can perform a HEAD request on the list resource with your filters and read out the header X-Total-Count.

Sorting

You can specify a sort order with the optional paramater order_by. Sortings consist of the name of the field and sort order: ASC for ascending resp. DESC for descending order. If no order is specified, ascending order (ASC) is used.

Nested sort orders are possible. Please separate the sort orders by comma.

Example:
Sort invoices by date descending and ascending by invoice number within the same date:

curl -H 'X-BillomatApiKey: {apikey}'
https://{billomatid}.billomat.net/api/invoices?order_by=date+DESC,invoice_number+ASC

Language

A few values depends on the language (more precisely it is a locale dependency). The locale can be specified with the HTTP header Accept-Language.

curl -H 'X-BillomatApiKey: {apikey}' -H 'Accept-Language: de-de'
https://{billomatid}.billomat.net/api/activity-feed
curl -H 'X-BillomatApiKey: {apikey}' -H 'Accept-Language: en-gb'
https://{billomatid}.billomat.net/api/activity-feed