Access tokens

For each API call you make you need to authenticate with a valid access token as described here. For each API request, the access token should be placed in the header of the request.

Select endpoint

The Business Insight API uses specific endpoints for different types of data. For example, requesting data about animals goes to the /v1/animals endpoint, while updating a specific heat calendar event goes to /v1/calendar/heat_event/{id}.

Requests to an endpoint are made using the HTTP protocol, using REST to structure the calls. For example, this means that for requesting data a HTTP GET request is made.

HTTP method description

GET                Used to request an object from the API
PUT                Used to update an object on the server
POST           Used to create a new object on the server
DELETE    Used to delete an object on the server


The header of the request should at least contain the access token of the installation you want to access.

Authentication header:

- H 'Authorization': Bearer 14f47b4ceb

Add query parameters

When sending a HTTP request, often additional parameters need to be send along. For example, a GET request for an animal can contain a life_number. Or a PUT request to update an animal can contain the new data of that animal.

One way to send these parameters is adding them as query parameters, a list of keys and values:

Format query parameters


For example, requesting an animal (GET request) with the value ‘NL 20123456789’ for the parameter ‘life_number’ looks like:


curl -H 'Authorization: Bearer 14f47b4ceb' \
-X GET' \

Add parameters in the body

However, the preferred method of sending parameters is in the body. Data in the body should be JSON and an additional content-type header is required to specify the JSON-format.

JSON body parameters

-d {'parameter1':value1,'parameter2':value2}

Content-Type header

-H 'Content-Type: application/json'

For example, creating a new animal (POST request) looks like:


curl -X POST
-d {"type":"Cow","number":11,"sex":2,"life_number":"NL 12345"}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 14f47b4ceb' \