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.

Developer Center

We have created a Developer Center where you can find more background information about implementing and using our API's.

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 tech@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 demo application, the API's and the authentication server.

Service Description Sandbox Production
General JoinData website. - https://www.join-data.nl
Developer Center Developer documentation. - https://www.join-data.nl/developers
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
Demo application A demo application showcasing the possibilities of JoinData Datahub. https://integration.datahubdemo.com https://www.datahubdemo.com
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/purpose-registry https://production.join-data.net/purpose-registry
Company Mapping API Base URL The base URL of the Company Mapping API. https://companymapping-api-integration.joindatacloud.nl/api https://companymapping-api.joindatacloud.nl/api
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.
  • Developer documentation can be found at the Developer Center.

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

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

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.