Certifier API Guide
Good to know
This guide will walk you through integrating with the BeCause APIs and submitting lists of the companies you have awarded with certification(s).
In order to do so, you will in the next steps be asked to create and/or select the following:
- Certification: This should be the certification that the companies you are submitting has been awarded with. If you cannot find it in the dropdown, it is likely not on the platform yet, and you need to create the certification. The step in the guide will explain how.
- Identifier: Each company you upload needs to have a an identifying ID associated with it. This ID can take many forms, and some certifiers uses incrementing numbers (such as 1, 2, 3, 4), while others use formats such as GK0001, GK0002, etc. The important thing is that this ID must never be changed for the company that you are submitting. We use this ID for keeping your data clean - even if you change the name, location or domain of an awarded company that you provide to us over the API (e.g. if wrong data was provided in the first place), if you provide the same ID for the company, then we know you want to update that specific company and not create a new one. Thus, providing these IDs helps us with making sure we do not create accidental new awarded companies instead of creating new ones. The reason you have to create the ID manually is mainly because, you can have multiple IDs or custom data that you want those that export your data to receive (but in that case, contact us and we will guide you through the more advanced API use-cases such as that).
- Group: A group can be considered a "portfolio of your awarded companies" on BeCause.eco. You can use the group to see details about the individual companies you have certified, or get statistics on these.
- API Key: As the name suggest, you need an API Key for communicating with the BeCause APIs securely. Remember to write it down after creating it, as we cannot retrieve it for you later.
If you need to use the API for advanced use cases such as:
- Uploading data such as company consumption data (such as "Towel reuse: Yes/no" for hotels),
- Uploading custom data (such as "This is a: Hostel/Restaurant/Hotel
Then just contact us, and we will guide you through it.
Select Certification
Select Identifier
The identifier is used for you to upload the unique ID you must provide for each awarded company
Select your group
See API Payloads
Select everything else to see this
1. First, you need to send the data to this endpoint:
curl -X 'POST' \
'https://api.because.eco/api/v1/bulk/consolidated/upsert-standard-holders' \
-H 'accept: text/plain' \
-H 'Content-Type: application/json-patch+json' \
-H 'Authorization: Basic <your api key>' \
-d '{ <payload specified below> }'
2. And, assuming you are sending certification information for this example company:
Company: BeCause ApS,
Domain: because.eco,
VAT: DK39745267,
Address:
Latitude: 55.66226377305261,
Longitude: 12.58718252728974,
Street Address: Njalsgade 76,
Zip: 2300,
Capital: Copenhagen,
Country: Denmark
The unique ID you keep for this certified company: CERTIFIED-0001.
3. Then, the payload should have this format:
{
"groupId": "undefined", //The id of your group 'undefined'
"companies": [
{
"name": "BeCause", //Example.
"identifier": {
"domainName": "because.eco", //Example. Optional.
"vatNumber": "DK39745267", //Example. Optional.
"customIdentifiers": [
{
"id": "undefined", //Your identifier 'undefined'
"value": "YourId E.g. BC0001" //Example. Mandatory. Never-changing and unique.
}
],
"locationCoordinates": {
"latitude": 12.123456, //Example. Mandatory.
"longitude": 12.123456 //Example. Mandatory.
},
"clientReferenceId": "YourId E.g. CERTIFIED-0001" //Optional.
},
"customProperties": [
{
"id": "undefined", //Your identifier 'undefined'
"value": "YourId E.g. CERTIFIED-0001" //Example. Mandatory and unique.
}
],
"companyAddress":{
"streetAddress": "Njalsgade 76", //Example. Mandatory.
"zipCode": "2300", //Example. Either Zipcode or city must be provided.
"city": "Copenhagen", //Example. Either Zipcode or city must be provided.
"region": "Capital", //Optional
"threeLetterCountryCode": "DNK" //Mandatory. Format: ALPHA-3 ISO-3166-1.
},
"certifications": [
{
"certificationId": "undefined", //The ID of your certification ''
"startDateUtc": "2021-11-30T00:00:00", //Optional.
"endDateUtc": "2022-11-30T00:00:00", //Mandatory.
"links": [], //Optional.
}
]
}
// ... Add the remaining certified companies here similarly to above
]
}
4. If you receive a HTTP 200 response after sending the data, then the upload was accepted
You can follow the progress and eventual result of the upload here: API Usage Overview
5. Finally, here is a description of the data you just sent:
- Domain name (because.eco in above example): The value is optional, however, it helps the market places (such as Booking.com) with finding your certified entities automatically.
- VAT Number (DK39745267.eco in above example): The value is optional, however, it helps the market places (such as Booking.com) with finding your certified entities automatically.
- Coordinates (Latitude & longitude): These are mandatory and the more decimals the better. Preferably at least 5 decimals (i.e. a precision of ~1 meter). The coordinates are used to ensure that the market-places (e.g. Booking.com) can automatically recognize the correct companies (e.g. hotels), even if there are spelling mistakes or e.g. multiple streets or hotels with the same names.
- Client Reference ID (CERTIFIED-0001 in above example): If you download any API reports the API Usage Overview page, this data is shown in the report. It helps you recognize the hotels in the report.
- Custom Identifiers (CERTIFIED-0001 in above example): Mandatory and at least one identifier must be provided. This is your own internal and never-changing ID for the certified entity. It helps our algorithm recognize it as the same company, in case you upload it multiple times, such that you do not create duplicate companies. It also helps us if the hotel changes name or address, since we can still recognize it as being the same hotel, despite all other information changing.
- Certification Start Date: Optional. The value specifies when the certification started being active. It may be relevant for market places (e.g. Booking.com) in the future to show data such as: "Certified by for 3 years".
- Certification End Date: Mandatory. The API accepts payloads without this value, BUT nearly all market places (such as Google, Booking, etc.) will not show the awarded certification, if they do not know whether it has expired.
- Certification Links: Optional. An array of strings. You can use this value to add links to e.g. a page or a certificate PDF on your site. We provide it to the market places, but cannot guarantee that it will be shown.
Reach out to [email protected] or [email protected] for any questions, or if you need to send more advanced data such as consumption data.
Review API Data & Next Steps
1. Verify the status and result of the import:
You can see the status of the import here: API Usage Overview. If you face any issues with the import failing for unclear reasons, please reach out to [email protected]
2. If the import went well:
Success! The market places are now able to start fetching and showing your certification data.
You can see who has exported the list of your certified companies from this page:
From that page, you can also give manual access to any market places that you invite to the platform, such that they can download your data over API or via Excel from:
BeCause.eco will automatically give relevant market places the ability to fetch and show your certified companies - let us know, if you are not interested in this option.
3. Next steps?
Need to change your certification data? You can update your certification information from this page:
Want to have data insights? You can see the portfolio (group) of your certified companies from this page:
View my group of certified companies.
If want to know more about the features and possibilities of groups and certifications on the platform, please contact us