Skip to main content

Getting started

This API allows users to interact with the Green Project Technology (GPT) system and perform various operations.

The GPT API provides functionality for:

  • Retrieving data from the GPT system
  • Sending data to the GPT system

Requesting access​

Please request access to our API by contacting your GPT CSM. Once the request has been processed, continue onto the below sections.

Authentication​

To authenticate with the GPT API, you need to create a new API key in your Company settings. Follow these steps:

  1. Log in to your GPT account.
  2. Go to Company settings.
  3. Navigate to the API Keys section.
  4. Click on "Create New API Key".
  5. Provide a name for your API key and click "Create".

Remember to keep your API key and secret secure and avoid sharing it publicly. If you suspect that your API key has been compromised, you can regenerate it in your Company settings.

By authenticating with your API key, you can securely access and interact with the GPT API to manage your emissions data and perform various operations.

Facilities​

Facilities are specific places or areas that are relevant to your application or system. They can represent physical locations, such as offices or factories, or virtual locations, such as business units.

When working with the GPT API, you can use locations to track and manage emissions data associated with different areas of your organization. Each facility can have its own set of emissions data, allowing you to analyse and report on emissions at a granular level.

By organizing your emissions data into different facilities, you can gain insights into the environmental impact of specific areas within your organization and take targeted actions to reduce emissions.

Projects​

Projects in the GPT API represent specific initiatives or activities within your organization that are related to emissions tracking and management. They allow you to group emissions data and analyze the environmental impact of different projects.

By organizing your emissions data into different projects, you can track the progress and effectiveness of specific sustainability initiatives and make data-driven decisions to achieve your environmental goals.

Schema​

The schema in the GPT API defines the structure and format of the data that can be stored and managed. It specifies the fields, data types, and relationships between different entities.

To retrieve the schema information, you can make a GET request to the /schema endpoint of the GPT API. This endpoint will return a JSON response containing the schema definition.

The schema provides a blueprint for organizing and managing your emissions data. It helps ensure consistency and integrity of the data by enforcing predefined rules and constraints.

By understanding the schema, you can effectively work with the GPT API and leverage its capabilities to analyze and report on emissions data in a structured manner.

Files​

Files represent the activity data you want to calculate emissions for. The file must be in tabular format and match our schema.

To upload a new file, you can make a POST request to the /files endpoint of the GPT API. This endpoint accepts the file data as a request parameter, along with any other relevant details.

Once a file is uploaded, you can retrieve its details, update its information.

By organizing your emissions data into different files, you can easily manage and analyze the environmental impact of specific data sources or documents within your organization.

Suppliers​

Suppliers are the entities that provide goods or services to your organization. They can be companies, individuals, or other organizations that you do business with. They are automatically identified from your spend data.

By default, every unique supplier description is considered a new supplier. However, we allow mapping multiple supplier descriptions to a single supplier. This is currently possible by contacting GPT support.

To retrieve aggregated supplier data, you can use the paginated POST /suppliers/list endpoint. This endpoint accepts a JSON payload with parameters to control the pagination and filtering of the results.

By default (groupBy: "supplier"), multiple aliased descriptions are collapsed into one row with supplierAliases listing every description. Set groupBy: "alias" to return one row per distinct activity supplier description (exact string as ingested, with per-description emissions) while still sharing the same supplierId across descriptions that map to the same group supplier. Unused registered aliases are not separate rows. Do not reuse pagination cursors across different groupBy values.

Collected PCFs​

A collected PCF is a product carbon footprint (PCF) that one of your suppliers has shared with you for one of their products. The API returns only footprints that have passed review.

Each collected PCF has the same fields, grouped the same way, as the collected PCF CSV export in the GPT app. Enum values are the same display strings as the export. A field that holds a list is one string joined with "; ", matching the CSV cell. A field with no value is null.

Listing collected PCFs​

To list your collected PCFs, make a GET request to the /collected-pcfs endpoint. Results are paginated:

  • limit sets the page size, from 1 to 200 (default 20).
  • To get the next page, set afterId to pageInfo.lastId from the current page. To get the previous page, set beforeId to pageInfo.firstId. Do not send afterId and beforeId in the same request.
  • pageInfo.hasNextPage and pageInfo.hasPreviousPage tell you whether there is another page in each direction.
  • total is the number of collected PCFs across all pages.

Fetching only updated PCFs​

Every collected PCF has an updatedAt timestamp. Set updatedAfter to return only PCFs updated strictly after that time. With updatedAfter set, total counts only the matching PCFs. To keep a copy of your collected PCFs up to date:

  1. Call GET /collected-pcfs?updatedAfter=<checkpoint>. Omit updatedAfter on the first sync to fetch everything.
  2. While pageInfo.hasNextPage is true, request the next page with afterId=<pageInfo.lastId>. Send the same updatedAfter value on every page, because afterId and beforeId only page through PCFs that match the filter.
  3. When the last page has been fetched, store the latest updatedAt you received as the checkpoint for the next sync.

For example:

GET /collected-pcfs?updatedAfter=2026-10-01T00:00:00Z&limit=100
GET /collected-pcfs?updatedAfter=2026-10-01T00:00:00Z&limit=100&afterId=674970a2-59b2-41dc-ae7b-8f9d67dceda5

Getting a single collected PCF​

To get one collected PCF, make a GET request to the /collected-pcfs/{productId} endpoint, where productId is the id of the supplier's product. The response has the same fields as an item in the list. The endpoint returns 404 if the product has no PCF that has passed review or the product is not visible to you.

Choosing the electricity calculation method​

Both endpoints accept an optional calculationMethod parameter. It sets which electricity accounting method is used for the headline emissions of a PCF calculated in the GPT app:

  • MarketBased, or no value: market-based emissions are used when they are available.
  • LocationBased: location-based emissions are used when they are available.

An imported PCF always uses the method its supplier declared. Each response gives the method that was used in electricityCalculationMethod. An invalid query parameter, such as an unknown calculationMethod or a malformed updatedAfter, returns 400.