Introduction

Welcome to the JoinData API documentation.

The API documentation contains the specifications of the API's that are available.
For background information about the platform and contact details, please visit https://www.join-data.nl.

If you have valid credentials you can test API calls here. Feel free to play around with our API's.
When you have any questions please send an e-mail to support@join-data.nl.

Security

We use the OAuth 2.0 protocol (https://tools.ietf.org/html/rfc6749) for authentication of users and applications.
The token and authorization URL can be found by pressing the 'Authorize' button which can be found in the API specifications below.

Environments

The JoinData Datahub provides - besides the production environment - a sandbox in which the integration can be realised and tested before going to production. Below you find the URL's for the API documentation, the API's and the authentication server.

Service Description Sandbox Production
General JoinData website. - https://www.join-data.nl
API documentation The API documentation you are currently looking at. https://integration.join-data.net/api/docs https://integration.join-data.net/api/docs
My JoinData Application designed for farmers. https://integration.join-data.net/my-join-data https://production.join-data.net/my-join-data
My JoinData for Partners Application designed for Partners of JoinData such as data suppliers and application developers. https://integration.join-data.net/my-join-data-partners https://production.join-data.net/my-join-data-partners
Authentication server Base URL The base URL of the JoinData authentication server. https://integration.join-data.net/auth https://production.join-data.net/auth
Datahub API Base URL The base URL of the Datahub API. https://integration.join-data.net/api/broker/icar-ade/v1 https://production.join-data.net/api/broker/icar-ade/v1
Purpose Registry API Base URL The base URL of the Purpose Registry API. https://integration.join-data.net/api/purpose-registry https://production.join-data.net/api/purpose-registry
Company Mapping API Base URL The base URL of the Company Mapping API. https://integration.join-data.net/api/company-mapping-service https://production.join-data.net/api/company-mapping-service
Source Registry API Base URL The base URL of the Source Registry API. https://integration.join-data.net/api/source-registry/v2 https://production.join-data.net/api/source-registry/v2
Webhooks API Base URL The base URL of the Webhooks API. https://integration.join-data.net/api/webhooks/v1 https://production.join-data.net/api/webhooks/v1

Notes for integration parties

As our API is subject to change, we require integration parties to be flexible with their implementation. Please take care your application won't break, by keeping the following remarks in mind:

  • New endpoints can be added to the API.
  • New fields can be added to messages (request and response).
  • This documentation will be updated and is maintained by JoinData.
  • Our API's use versioning. Version number changes will only be introduced if there are incompatible structural changes. Previous versions will be deprecated and will have a limited lifetime.

Common situations regarding Datahub API response

When making a request to the Datahub API access to the resource is validated by a mandate. In case your token and mandate are valid, Datahub API will connect to Source Registry API to see if there are one or more sources which can deliver the data you requested. As Datahub discovers the sources a connection is made to the providing companies and an array of sources is returned in the response. There are some situations which can raise questions so we made a short list below of situations which can occur.

  • "data": [] An array with only a `id`, `errors` and an empty array within `data` element. A source is found, but the providing company returned no data:
    • Providing company has no data available.
    • Datetime period filtering is being used and providing company has no data available within the requested range.
If the above causes don't give you an idea where the problem might be, no errors are presented which you can do something about, then please feel free to contact us.

Use of standards

The Datahub promotes the use of ICAR-ADE standards by designing the API's based on translating the current ICAR-ADE XML/SOAP standards into the Datahub JSON/REST messages. If those standards are not available yet, new standards are developed according to the ICAR-ADE philosophy. The API design will be shared and discussed with the ICAR-ADE team on regulary basis.

For specifying data types the UN/CEFACT Common Code for Units of Measurement is used. For a full list of possible values can be found here:
https://www.unece.org/fileadmin/DAM/cefact/recommendations/rec20/rec20_rev3_Annex2e.pdf.

Identification schemes

Our API's use identification schemes for identifying resources (See each API for scheme usage). These schemes are used to indicate the type of identifier and preventing duplicate identifiers accross different countries. For now we have specified the following schemes:

Company identifiers

  • nl.kvk - The dutch ‘KVK’ number
  • be.onn - The belgian ‘ondernemings’ number
  • euid - The european ‘company’ number

Location identifiers

  • nl.kvk - The dutch ’KVK’ number
  • nl.ubn - The dutch ’UBN’ number. See RVO for more info.
  • nl.ftn - The dutch ’Milk TankId’ number
  • be.onn - The belgian ‘ondernemings’ number.
  • be.pen - The belgian ‘productie eenheid’ number
  • euid - The european ‘company’ number. See e-justice.europa.eu for more info.

Animal identifiers

  • nl-v1 - The dutch 'Levensnummer' (life number) registered at RVO. See RVO for more info.
  • be-v1 - The belgian 'Levensnummer' (life number) registered at FAVV.