logo

Certifier API Guide

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 updating existing 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...

Choose the certification for which you want to upload awarded companies

Select...

The identifier is used for you to upload the unique ID you must provide for each awarded company

Select...

The group can be considered your portfolio, where you can get an overview and statistics of your certified members

You need the API key to send us data securely to the BeCause APIs

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.
            "validation": {
              "validationState": "Valid" //Possible values: "Valid", "Unvalidated", "Revoked".
            } //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.
  • Validation: Optional. Specify the validation state of the certification for this company. If not given, will default to Valid. Available values for ValidationState:
    • Valid: Indicating this company is certified.
    • InProgress: Indicating this company is in the process of being certified.
    • Unvalidated: Indicating the certification data provided for this company has not yet been validated by the certifier.
    • Revoked: Indicating the certification for this company was revoked by the certifier.

Reach out to support@because.eco or jonas@because.eco for any questions, or if you need to send more advanced data such as consumption data.

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 support@because.eco

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:

Export Data Access.

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:

Export Certified Companies.

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:

Update Certification.

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