Using the Company Mapping Service
This page is part of the Developer Documentation and zooms in on how to use the Company Mapping Service. The Company Mapping Service (CM) is a registry of all identifiers of companies (mostly farmers) as they are known at other companies (e.g. customer relation numbers, tank id’s etc). You can use the company mapping service to read mapped identifiers for your customers. You can then use these identifiers to correlate messages from datasources using these external identifiers, to identifiers that you can use. You can also store your own customer identifiers in the service, allowing other parties to correlate with your identifiers.
- Concept
- User interface
- Up- and downloading CSV files
- Environments
- Using the API
- Reading mappings
- Writing mappings
- Authentication
- Trust Levels
Concept
The Company Mapping Service manages all identifiers of a company and map those to a unique company within the JoinData system. For the Netherlands this means that all identifiers are related to a single KVK (chamber of commerce number).
The company who is described is called the target company. Each company at which the target company is a customer can register its own mappings. Such a provider is called the owning company. For example, a farmer (as a target company) has a KVK and one or more UBN’s (locations). These location mappings are ‘owned’ by the Dutch RVO agency, the owning company for those mappings. Other owning companies can register their customer numbers, tank id’s or any other references they have for the same farmer.
Each owning company can read and write their own mappings for their own customers.
The identifiers that are used in the mappings are categorized by type of field; the field-type indicates what the identifier refers to:
- a CompanyId: refers to a legal entity;
- a LocationId: refers to a specific location;
- a CustomId: refers to a custom identifier as used by a data source or application provider.
Depending on the company that issues the identifier (the owning company), the mappings are classified in one of the subsets of the identifier data-set (see Developer Documentation: Data Sets). The data set a mapping is placed in can be one of:
- national-ids: governmental id’s that are well known and in general use;
- commercial-company-ids: id’s that are issued by commercial companies and as such reveal information on the operation of a company;
- milk-tank-ids: the id of a milk tank on the farm. Often used in processes and as such somewhat in general use;
- feed-silo-ids: the id of a feed silo on the farm. Often used in processes and as such somewhat in general use.
User interface
Although the company mapping service is designed for machine-to-machine communication, JoinData also provides a user interface for manually updating the company mappings. Note that this is not the preferred way of updating mappings since it manually updating means that it is possible to make mistakes. It also means that the information is not necessarily up-to-date. As such, manually updating the mappings has a lower trust level then updating it via the API. This means that you cannot update mappings that are registered via the API.
You can find the user interface at https://companymapping.joindatacloud.nl/index.html. You need an eHerkenning login which is authorised for the owning company.
The user interface primarily exposes a table containing your mappings.
On top you can see the filters for the table: you can filter on the Trust Level (“klasse” in dutch), on the company id (KVK) and on your customer id.
The table itself first shows the trust level of that record (see below for more on trust levels). Next is the company id (KVK in the Netherlands), your customer id and how you describe your customer id (e.g. “klantnummer”. The last colum shows in what data set the mapping is placed (and thus what kind of mandate is required for a company to read this mapping). See Developer Documentation: Data Sets for more information on that.
Per record, you can perform actions:
Up- and downloading CSV files
Using the import button in the menu it is possible to upload a CSV File. The import will remove all current company-mappings for the current authorized Company and it will create new company-mappings based on the content of the CSV File.
You can up- and download all your mappings in a single file. This is a very basic interface which is meant for initial bootstrapping.
Using the export button in the menu it is possible to download a CSV File, it is also possible to include inactive mappings by checking the checkbox. The export will create a CSV file with all the company-mappings for the current authorized Company.
Below is an example of a CSV file content. The first row is a header row describing the columns.
TargetCompanyKvk;Value;SchemeDescription;Dataset;Scheme;StartTimestamp;EndTimestamp;ActiveTimestamp;InactiveTimestamp; Trustlevel08123456;12345;"Mijn klantnummer";"Commercial"; "CUSTOM";"01-01-2019 00:00:00";"01-01-2020 00:00:00";"01-01-2019 00:00:00";"01-01-2020 00:00:00";208123456;12346; "Mijn tank klantnummer";"MilkTanks";"CUSTOM";;;"01-01-2019 00:00:00";;208123456;12347;"Mijn voer klantnummer"; "FeedTanks";"CUSTOM";;;"01-01-2018 00:00:00";;2
Below is an example of a CSV file content that you can upload. The first row is a header row describing the columns, this row can be omitted as the upload service will detect if the file has a header or not. The other rows are different company-mappings. The scheme description and Dataset columns can be left empty.
TargetCompanyKvk;Value;SchemeDescription;Dataset 08123456;12345;"Mijn klantnummer";"Commercial" 08123456;12346;"Mijn tank klantnummer";"MilkTanks" 08123456;12347;"Mijn voer klantnummer";"FeedTanks"
After uploading a CSV file the app will show a preview of how it interprets the CSV file, how many Company Mappings will be deleted and how many will be created. You can verify the data and Confirm or Cancel the upload.
You can only upload a full data set. It is assumed that that is your full mapping data set and all of your mappings that are not in the new upload will be removed. You cannot do partial updates using CSV uploads.
Environments
As described in the General Developer Documentation, we have isolated environments for testing and production. When developing, you will be connecting to our integration environment. After testing, you can change your url’s and credentials to connect to the production environment.
Integration
API documentation is available at https://companymapping-api-integration.joindatacloud.nl
App is available at https://companymapping-integration.joindatacloud.nl
Production
API documentation is available at https://companymapping-api.joindatacloud.nl
App is available at https://companymapping.joindatacloud.nl
Using the API
You can both read mappings (of yourself or from other companies) as well as update mappings of yourself using the API.
To read mappings for a specific company, other than your own mappings, you will need consent from the farmer. Specifically, you will need a mandate for one of the sub-data sets of identifiers (see Developer Documentation: Data Sets).
Reading mappings
Depending on your use case, you can query for mappings in multiple ways. The company-mapping GET endpoint is the main API. In the API documentation (https://companymapping-api.joindatacloud.nl) you can find the specifications in detail. The filter parameters can be used in a flexible way, and some common use cases are described here.
- Read your own registered mappings: By specifying owner-scheme and owner-value, you can query all mappings of an owning-company. For example, if you specify ‘nl-v1’ for scheme and your own KVK for the value, you will retrieve all the mappings that you have registered. If you specify another owning company, you will get mappings for which you are mandated.
- Read all mappings for a customer: By specifying target-scheme and target-value, you can query all known identifiers for a specific company. If you specify ‘nl-v1’ for scheme and a KVK of a farm, you will retrieve all mappings for that company that you are mandated for.
You can fine-tune these queries by specifying e.g. field-type to specifically look for company, location or custom identifiers; you can also set a minimum-trust-level depending on how sensitive your use case is (see the section on Trust Levels for more information). And you can set a period in which you are interested using a start-timestamp and end-timestamp. Mappings can change over time, e.g. a location can be bought by another company.
The response is a list of mappings, see the examples below. For each mapping, there is a startTimestamp and endTimestamp. These indicate the period for which the mapping is active (e.g. when the location was owned by that company). There are also active- and inactiveTimestamps. These indicate when the record was stored in JoinData; if you retrieve a record that is no longer valid (e.g. the inactiveTimestamp is in the past), you should not use the record anymore. By default, you will not retrieve inactive records.
Example of a companyId mapping result, in this case showing a KvK of a farm (a companyId in the ‘nl-v1’ scheme):
[ { "id": 0, "ownerCompany": null, "targetCompany": { "scheme": "nl-v1", "value": "65931041" }, "fieldType": "companyId", "dataSet": "national", "scheme": "nl-v1", "schemeDescription": "KVK", "value": "65931041", "startTimestamp": "2019-02-05T12:58:20.921Z", "endTimestamp": "2019-02-05T12:58:20.921Z", "activeTimestamp": "2019-02-05T12:58:20.921Z", "inactiveTimestamp": "2019-02-05T12:58:20.921Z", "trustLevel": 0 } ]
An example of a locationId mapping, in this case showing an UBN of a farm (a locationId in the ‘nl-v1’ scheme):
[ { "id": 2444, "ownerCompany": null, "targetCompany": { "scheme": "nl-v1", "value": "65931041" }, "fieldType": "locationId", "dataSet": "national", "scheme": "nl-v1", "schemeDescription": "UBN", "value": "1234567", "startTimestamp": "2019-02-05T12:58:20.921Z", "endTimestamp": "2019-02-05T12:58:20.921Z", "activeTimestamp": "2019-02-05T12:58:20.921Z", "inactiveTimestamp": "2019-02-05T12:58:20.921Z", "trustLevel": 0}
And an example of a customId. In this case the owning company is RVO, which has customer numbers called BRS.
[ { "id": 2644, "ownerCompany": { "scheme": "nl-v1", "value": "27378529" }, "targetCompany": { "scheme": "nl-v1", "value": "65931041" }, "fieldType": "CustomId", "dataSet": "commercial", "scheme": "nl-v1", "schemeDescription": "BRS", "value": "123456789", "startTimestamp": "2019-02-05T12:58:20.921Z", "endTimestamp": "2019-02-05T12:58:20.921Z", "activeTimestamp": "2019-02-05T12:58:20.921Z", "inactiveTimestamp": "2019-02-05T12:58:20.921Z", "trustLevel": 0 }
Writing mappings
For maintaining your own mappings, you can POST to the same company-mapping endpoint. The details of the body are described in the API documentation (https://companymapping-api.joindatacloud.nl). You have to specify your own company (or at least a company for which you are authorized to do so) and the target company, in most cases your customer. You should also specify the fieldType, indicating on what level your mapping is: company, location or if it is a custom mapping). In most cases, this will be a custom mapping. You should also specify a dataSet; this determines what kind of mandate another company requires to be able to read that mapping. In scheme you can denote an applicable scheme (most mappings you will use will be custom, so the scheme will be ‘custom’ as well). The schemeDescription can be used to describe how you refer to the mapping (e.g. “klantnummer”, “relation id” or some other identifier name).
You do not have to specify the active/inactiveTimestamps, if omitted, JoinData will assume that they are active from the moment that you post them and leave the inactive timestamp open.
Finally, you should also specify the trust level. Your client account will be authorised up to a specific level; you can only specify that level or lower when creating mappings. For a definition of the trust levels, see the next paragraph.
Authentication
The Company Mapping API accepts JWT bearer tokens from our Identity and Access system (see Developer Documentation: Identification and Authentication).
Your token either represents your application company (in case of a service account) or an application instance acting on behalf of a farmer. We’ll call this the ‘logged in company’.
The API will only return the following records:
- mappings where the currently logged in user is the OwnerCompany (“your customers”)
- mappings where the currently logged in user is the TargetCompany (“mappings where you are the customer”)
- mappings with OwnerCompany and TargetCompany for which the a mandate exists in the Purpose Registry
- concerning one of the datasets (“identifiers”, “national-ids”, “commercial- company-ids”, “milk-tank-ids”, “feed-silo-ids”)
- with currently logged in company is the Authorized Company in the mandate
- with the OwnerCompany in the mapping is the Providing Company in the mandate
- with the TargetCompany in the mapping is the Authorizing Company in the mandate
Trust Levels
When storing a company mapping a trust level can be given in the request. These indicate how recently this mapping is updated. This allows us to transparently and gradually upgrade to a more strict verification while staying operational; other companies may decide not to use the mapping if it doesn’t have a high enough trust level.
- 3 stars: The data is automatically retrieved from a trusted source within a reasonable time frame. If the source is a user of our system, e.g. the farmer, authentication is done via 2-factor authentication.
- 2 stars: The data is retrieved from a trusted source but there is no reasonable update process in place. Data may thus be outdated. E.g. when using the JoinData Company Mapping UI.
1 star: The data cannot be proven to be 3 stars or 2 stars. Data comes from a legacy system, a third party or is manually entered by an untrusted source.