The Diligent ESG API is the developer interface for Diligent ESG platform.

Diligent ESG currently supports two API types:

• Activity data API: Send in activity data entry for the supported activities (link to changelog).
• Reports API: Download reports of your carbon data or quantity data.

This introduction contains information that you should know before you get started. Diligent ESG provides the API, necessary documentation to communicate with the API and endpoints.

You can use the Activity Data API to send activity entry (usage) data. You can submit activity data for multiple environmental impact areas, including greenhouse gas (GHG) emissions, electricity consumption, fuel usage, water consumption, waste disposal, and employee travel.

For more information about the supported source categories, go to Changelog

Caution: This API interacts with your company's live data. It gives you the power to add important data that your company needs. Carefully consider the consequences of your actions when using this API. If you are not sure, contact the person or group who administers Diligent ESG in your company.

Important: You can only make one request per activity usage data. You cannot bulk send usage data.

With the Reports API you can generate and retrieve reports related to greenhouse gas emissions and quantity data. This set of endpoints enables users to generate detailed reports based on activity inputs, aggregation periods, specific reporting methodologies and more.

Currently we support two report types:

• Greenhouse gas emissions data grouping report, and
• Quantity data grouping report

Note: Diligent ESG will add further reports over time.

Diligent ESG provides the API, necessary documentation to communicate with the API, and endpoints so you can gather your data to construct the activity entry data that you will send to the Diligent ESG platform.

While Diligent provides these items and information, Diligent ESG’s engagement does not extend to:

• Interaction with third-party vendors: If you use third-party vendors for your integration, it is your responsibility to manage and coordinate with them.
• Direct involvement in your development process: Diligent ESG doesn’t directly engage in writing or maintaining the code between the API integration and your internal system.

When you purchase an API license, it is the responsibility of your technical team, internal or third-party, to successfully implement and provide ongoing maintenance of this API integration.

The Diligent ESG API is built around REST and is built on the OpenAPI 3.0 specification.

To start interacting with the Diligent ESG API, you need to complete the following:

• Request an API license
• Request that your site be enabled for API calls
• Login to Diligent ESG
• Copy your company’s ID to call API endpoints
• Create an API key
• Format and structure your activity usage data

The Diligent ESG API is available to clients upon request. To enquire about Diligent ESG API, contact your Customer Success Manager (CSM).

For each company, you must request that the API module is enabled. You can then create an API key that allows you to make API requests. To request that the module is enabled, contact your Customer Success Manager (CSM).

We recommend you create a dedicated user in Diligent ESG that is used solely for making API requests with the required user role rights or permissions. For example, to request data through the List all facilities and assets endpoint, the user must have access to facilities data.

To learn more about users and user role rights, go to the Managing user access section of the Diligent ESG support site.

The API key programmatically authenticates your identity to Diligent ESG. This allows applications to perform specific actions defined by the read, write, or admin permissions granted.

If you need an API key for yourself, go to Creating an API key for your profile.

If you are a regular user, request the administrator on the system to create an API key using Creating an API key for another user.

An API key is created which you can copy to use to authenticate your identity to Diligent ESG.

Important: You can only view the API key once after creation so immediately copy it to a safe location. Otherwise, you must delete the key and recreate it.

All requests require authentication. To authenticate, use Diligent ESG to create a token (API key) for your account. The token (API key) is a string that authenticates you and allows you to securely access the Diligent ESG API.

After you have created your token, you can provide it in the header of your request:

Authorization: Bearer <TOKEN>

Important: If you do not authenticate yourself, the API fails. The API responds to authentication failures with a 401 "Bad credentials" status.

You need the company's ID to call the API endpoints. Use this ID to get and send the data that you need for your business.

For further information about copying the company's ID, go to Copying your company’s ID.

The Diligent ESG service is provided from a single region to ensure secure and compliant data storage. All requests must use the following URL for access:

• Europe - https://esg-api-eu.diligentoneplatform.com

Important: All API requests must be made over HTTPS. Calls over HTTP respond with the 301 "Moved Permanently" status.

You need to format and structure your data to match the Diligent ESG API schema. You can use the help outlined in each endpoints.

Note: If you require further assistance matching the Diligent ESG schema, you can contact support@accuvio.com.

After you have completed the authentication process, you can start sending requests.

The API safeguards against bursts of usage to help maximize its stability. If you make too many requests, the API responds with a 429 "Too many requests" status.

When you create a record in Diligent ESG, a unique quick reference is assigned to it. This quick reference is unique throughout the lifecycle of the item.

As responses often contain many items, you can enable pagination to improve response time, reduce network traffic, and make the data set in the response easier to handle. Use the page_size and page ;parameters to configure pagination in the requests you send.

Additionally, responses include the links parameter, which provides the following URI's first_page, next_page, prev_page and last_page (or null values for next_page and prev_page if all the items are on one page) so you can use them for subsequent requests.

Use the Filters parameter to define the filter conditions. You can add multiple filters to a request. All GET queries support filtering and follow these two rules:

• Text is not case-sensitive: Text must be an exact match but does not have to exactly match the case, upper or lower.
• Multiple filters apply AND connection: If you combine multiple filters, then the API uses an AND connection between them. Diligent ESG only shows results when both filters are matched.

The Diligent ESG API uses standard HTTP response codes to indicate the success or failure of a request. The following table lists some common responses that are returned when sending requests.

Diligent ESG operates exclusively in the Coordinated Universal Time (UTC) time zone. All dates and times recorded within the system are stored and displayed in UTC by default. All data that you upload using the API will use UTC rather than your local time zone for dates and times.

All API endpoints use a version number in the path. As can be seen in the examples, /v1/ specifies version 1 of the API.

Over time, the API will evolve. New API versions will be introduced and existing versions may be updated.

Some API updates are considered a breaking change, requiring a new version of the API to be introduced. An example of a breaking change is fields being changed or removed. By introducing a new version, API consumers can safely continue to use prior API versions.

The other type of API update is a non-breaking change. You should expect non-breaking change updates to existing API versions. An example of a non-breaking change is adding a field to a response object. Non-breaking changes are additive. While they do change the response body, they should not impact the API consumer.

For further information about the current version and the recent version updates, go to Change Log.

You want to send 20kWh of used electricity (Scope 2) for Building A for a given period to Accuvio. To do this, you need to get the Activity ID and any other data from Diligent ESG to construct the payload and send it using the API.

1. Use the following query to identify your company’s assets: GET/v1/«company_id»/assets
   Note: Replace with your company’s ID. For further information, go to Copy the Company ID to call API endpoints

2. Use the following query to filter your company’s assets and receive your company’s activity IDs: GET/v1/«company_id>/activities

   Note: You require activity IDs to push activity data to the system.

3. Use the following query to request your company’s reference type IDs: GET/v1/«company_id»/common/reference_types

4. Use the following query to request your company’s meter reading type IDs: GET/v1/«company_id»/common/meter_reading_types

5. Use the following query to request your company’s unit IDs: GET/v1/«company_id»/common/units

6. Use the following query to request your company’s currency IDs: GET/v1/«company_id»/common/currencies

7. Use the following query to request your company’s supplier IDs: GET/v1/«company_id»/common/suppliers

8. Use the following query to push your company’s activity data to the system: POST/v1/«company_id»/electricity/activity_data Note: Include the activity IDs that you received in Step 2 in the Request body.

Important: We have updated the request URL for Diligent ESG:

• New URL: https://esg-api-eu.diligentoneplatform.com
• Deprecated URL: https://eco-api.accuvio.com

All requests to the old URL will be automatically redirected to the new one. However, no new integrations should be built using the deprecated URL. Please update your systems accordingly to ensure long-term compatibility.

Activity data: Air travel with airport codes

Reports API

Important: The Add data to a business travel activity endpoint has been changed to Add data to employee travel activity. The endpoint URL changed from /v1/{company_id}/business_travel/activity_data to /v1/{company_id}/employee_travel/activity_data. Additionally, the schemas have been updated, with adjustments made to the payload structure to align with the updated naming conventions.