This page is part of the Developer Documentation and zooms in on how you can use the Purpose Registry of JoinData. The Purpose Registry is the part of JoinData where consent for sharing data is stored. It stores purposes, participations and mandates. It can be used by application providers to get consent to be able to retrieve data, but also by other parties to store consent for other data flows. The latest API can be found here.

• Context
• Purposes, participations and mandates
  • Importing mandates
  • Asking for consent
    • 1. Create a purpose
    • 2. Register a participation
    • 3. Get consent
• WebHook and Synchronization
  • Usage
    • Example messages
  • List of events
  • Postman example
• Sources

Context

To share data between parties, often consent is required. JoinData has a centralised registry where farmers (and other parties) can store their consent. JoinData’s DataHub, the Company Mapping Service and other services use the Purpose Registry to check for consent before sharing data. The same registry can also be used for data flows outside of the JoinData platform.

Purposes, participations and mandates

The Purpose Registry makes a distinction between purposes, participations and mandates. These entities appear in different stages of development.

A purpose is the reason why data is being shared. This can be a research project, an application or part of a service being delivered. A purpose is typically registered during development of an application: you register which data sets you need along with a description of that purpose.

The participation is created when a specific farmer (or authorizing company in general) joins the purpose. E.g., when the farmer indicates interest for a project, or installs an app. Specific restrictions on location and the validity period are then fixed.

As soon as a farmer accepts the participation (e.g. via the using the Onboarding Client), mandates for each data set are created.

Your application can use the API to:

• create or remove purposes;
• have farmers participate in a purpose, or remove those participations;
• check if you have a mandate for a specific farmer and/or dataset;
• query which purposes, participations and mandates are registered for you;
• import legacy mandates.

Importing mandates

If you already have a database with approved mandates, these can be imported into JoinData’s Purpose Registry. These are then imported on a lower trust level, and farmers can be asked to reaffirm those mandates. This allows a gradual migration from an existing system towards the JoinData Purpose Registry. Ask JoinData for more information.

Asking for consent

In a normal flow, a purpose is created and a participation of a farmer is registered on that purpose. The next step is to ask consent of the farmer for that participation. Consent can only be asked via the onboarding client of JoinData, or via the My JoinData interface. Asking for consent is a three step process:

1. Create a purpose for your application;
2. Register a participation for that farmer on that purpose;
3. Get consent of the farmer via integrating the onboarding app or via My JoinData.

You always need consent of the farmer. Even if the farmer is logged in in your app and he is accessing his own data, it is still  your app that the farmer needs to trust with his data.

1. Create a purpose

A purpose is specific for an application provider and typically created during the development of a project or app. You only need to create it once for each project, application or other purpose for which you require data.

There are three ways to create a purpose:

• To create a purpose you can login on My JoinData for Partnersand create one manually
• You can ask JoinData to create it for you using the Purpose Creation Form.
• Or you can do it automated via the Purpose API. Specifically, you can use the POST /api/v1/purposes.

The API call gives you the most options and flexibility and offers some features that are not available via the other routes. In all cases, you will get a purposeId that represents the purpose and that you require in following steps.

You need to provide a title, which is your application name or project that you are working on. Also, you need to provide a description which indicates what your purpose for the data is: why do you need this data and what are you going to use it for?

You also need to provide the data sets that you want to access. See Developer Documentation: Data Sets for which data sets are available and their respective id’s. Note that the id’s are different for the integration and the production environments since new definitions may be added over time.

You also need to specify which categories your purpose belongs to; contact JoinData for the classification of your purpose. This is used to show to farmers what sort of purpose it is: is it for research, benchmarking or to provide advice.

Purpose Category	Description
Advise	Based on the data acquired, advice or insights for the farmer are created.
Research	The purpose is used to improve the way the application provider works, or for research in general.
TechnicalReports	The purpose is used to create a technical reports.
FinancialReports	The purpose is used to create financial reports.
Benchmarks	The data acquired is used to make comparisons between companies and to generate aggregated company views.
Certification	The data is required to comply with quality programs or to achieve or maintain certifications.
Commercial	The data will be used to create commercial products for the application provider
Efficiency	The data will be used to improve the process of the application provider

You can also supply a range of related purposes. When you supply related purposes and create a participation for a farmer, the related purposes will function as related participations. When the farmer initiates the acceptance of your participation, a request for every related participation is prompted to the farmer to be able to grant a range of participations. This is useful if the business process associated with your purpose depends on other purposes.

Last but not least, you can specify restrictions: the most common restriction is to have a limited lifespan of your mandate, or of the time period of the data that you can access.

This will create a new purpose with a purposeId. It still has to be verified and approved by JoinData. Please contact your representative to get it approved. Note that this purposeId can be reused for as long as the purpose exists; you may e.g. hard code it in your application.

You can also specify your reference to a purpose in the externalReference field. This may help you to maintain a relation between your projects and apps, and the registered purposes at JoinData. Note that you could also use this field to indicate a version of that purpose. E.g., if your app evolves over time, you may need to revisit the original purpose. You could simply register a new purpose and use e.g. “myapp-v2” as an external reference. This way, you can keep track of which users have consented to the new purpose and which still are on an older version. If you specify the old purposeId in the replacesPurpose field, anytime a farmer consents to the new purpose the old purpose is immediately removed, thus replacing the old purpose with the new one.

2. Register a participation

As soon as your purpose is approved, you can start registering participants. This can be done via your backend system, or upon installation of your app, whatever is most suitable for your use case.

There are two ways of registering a participation

• You can login on My JoinData for Partnersand add a participation to the purpose;
• Or automated via the Purpose API using: POST /api/v1/purposes/{purposeId}/participations

In all cases, you will get a participationId that you may require in the next steps.

You only need to register the authorizing company, in most cases the farmer since you need his or her consent. You need to know the company’s identifier, e.g. in the Netherlands you need the KVK (chamber of commerce number).

If your use case requires more specific mandates, you can also specify which data source providers you’d like to mandate, by providing providing companies as well. You can also e.g. restrict this participation on locations or add other restrictions specifically for this farm.

3. Get consent

The next step is to get consent of the farmer. For that he or she needs to be shown a JoinData consent page showing the participation.

There are three ways of getting consent:

• The most trivial (but less user-friendly) way is to have the farmer navigate to My JoinData. There, the participation should be waiting for approval. The url for this is:
  • https://integration.join-data.net/my-join-data/participations (for integration)
  • https://production.join-data.net/my-join-data/participations (for production)
• You can also embed the relevant My JoinData tabs in your own website
• Or you can ask consent during your own onboarding process, either when the farmer is registering at your website or when he is installing your app. For that we have an onboarding client. See Developer Documentation: Using the Onboarding Client for more information.

WebHook and Synchronization

If you need to have your mandates in your own database, e.g. for efficient batch processing or for maintaining existing processes, you can setup a synchronization between JoinData and your own database. In the common case, JoinData is the primary source of mandates and any change in these mandates are communicated to your service via a WebHook. In some cases, changes in mandates can also origin in your service. For JoinData to accept those changes, security requirements have to be met. Ask JoinData for more information if you require this.

For parties who would like te receive notifications from the JoinData notification service we have the following requirements:

• Connection only using HTTPS
• A URL we can post messages to
• A secret so you can verify message comes from JoinData and is not tampered with

There are multiple events related to mandates that you can register your webhook on. Contact JoinData to register your web hook in our system.

Usage

Whenever a change has happened at JoinData side, your endpoint will be called. In general, you will only receive the id of the object that has changed. You can configure the webhook to notify you on mandate level or participation level. A webhook on mandate level notifies you whenever a mandate changes (on data set level). A webhook on participation level happens whenever a participation is accepted or rejected by the farmer.

The recommended approach is participation level. Since a farmer in the purpose registry can only accept or reject the entire participation, notifications on mandate level are not useful anymore.

In general, a participationId or mandateId is given to indicate the entity for which the change has happened. You can then use this id to query the mandate via the purpose api.

All messages will have the elements below. HTTP POST payloads that are delivered to your webhook’s configured URL endpoint will contain the following headers:

Header	Description
Content-Type	application/json
X-joinData-Signature	The HMAC hex digest of the response body. The HMAC hex digest is generated using the sha256 hash function and the secret as the HMAC key.
X-joinData-Event	Name of the event that triggered the delivery

The message body can contain of the following fields:

Field	Description
mandateId	JoinData mandate-ID (for mandate level webhooks). Note that this id should be treated as a string as it can contain both an numeric value or a GUID.
purposeId	JoinData purpose-ID (for participation level webhooks). This contains a GUID.
participationId	JoinData participation-ID (for participation level webhooks). This contains a GUID.
timestamp	Timestamp of the event

Example messages

An example for mandate-level events:

Example

{  
"mandateId": "9f765da0-7a04-4da2-9a30-016b1ea0b850",
"timestamp": "2018-05-01T00:00:00.000Z"
}

An example for participation-level events:

Example

{  
"purposeId": "0c0912b2-9b1b-4818-b4eb-370ef0b083d5",
"participationId": "966bc560-6940-4a84-84d4-d412bddce473",
"timestamp":"2018-05-01T00:00:00.000Z"
}

List of events

The following table indicates the events that you can subscribe to.

Name	Description
*	Any time any event is triggered (Wildcard Event).
mandate.*	Any time a mandate event is triggered
mandate.claim	Any time a mandate is claimed
mandate.approved	Any time a mandate is approved
mandate.updated	Any time a mandate is updated
mandate.revoked	Any time a mandate is revoked
participation.*	Any time a participation event is triggered. Typically this is whenever a farmer presses a button.

Postman example

We have created a postman example to test your webhook.

JoinData WebHook Example.postman_collection.json

Sources

• https://integration.join-data.net/api/docs#purpose-api, integration environment API documentation
• https://production.join-data.net/api/docs#purpose-api, production environment API documentation (should be the same as integration)
• https://www.freeformatter.com/hmac-generator.html