Skip to content

SQUAKE API Documentation

Introduction

Trusted technology to achieve your carbon targets.

The SQUAKE Solution Suite is live with industry leaders from several travel and logistics segments and performs accurate carbon calculations for all types of activities (e.g. flights, road, accommodation amongst others) according to national and international standards. It automates carbon reductions and/or compensations along the supply chain, from supplier selection (SAF, DAC, ecological restoration) to inventory management, invoicing and credit retirement.

Customer Support

For any issues or inquiries, you can reach our dedicated customer support team through our Support Page. This is the best place to ask questions, report incidents, or get assistance with integrating or using SQUAKE's solutions.

Contact Forms

Our contact forms are designed to help you communicate with us effectively. Whether you want to get in contact with our support team or need to report an incident, we've got you covered. Please use the appropriate form below:

  • Contact Form: Get in contact with our customer support team or share your thoughts and suggestions about our services and processes.
  • Incident Form: Report any issues or incidents you've encountered, and our support team will respond as soon as possible.

Authentication

SQUAKE uses API keys to authenticate requests. You can create and revoke API keys in the Dashboard, which you can access by contacting us under product@squake.earth. You should securely store your API keys; and encrypt them on rest if possible. Be aware that each API key is shown exactly once in the UI during creation. SQUAKE advises rotating API keys on a regular basis.

To use the sandbox environment, a separate API key must be created. Switch to sandbox mode in the dashboard, then create an API key.

All requests must be authenticated and made over HTTPS. SQUAKE supports TLS 1.2 - TLS 1.3. Requests without authentication or via plain HTTP result in an error.

When using HTTP Basic Auth, the API key is the username; leave the password blank. For bearer auth, pass the API key as the token.

Example using HTTP Basic Auth (note: there is no password, but a colon is still required):

curl https://api.squake.earth/v2/pricing -u <YOUR_API_KEY>

Example using bearer auth:

curl https://api.squake.earth/v2/pricing -H "Authorization: Bearer <YOUR_API_KEY>"

Request ID

SQUAKE associates each API request with a unique identifier. Find this value in the SQUAKE-Request-Id header. If you need to contact us regarding a specific request, providing the request identifier helps the resolution process.

Uptime Monitoring

Please visit status.squake.earth to check our uptime monitor. You can subscribe to events to stay informed of any service disruption. We will also publish a post-mortem about any incident should one occur.

You can programmatically check if servers are reachable. Read the documentation of the Health Check endpoints for details. The health check endpoints are the only endpoints that do not require authentication.

Sandbox

There is a sandbox server available for testing at

https://api.sandbox.squake.earth

Sandbox and production are separate systems and share no data. Sandbox uses less computing power and may be slower than production. Both sandbox and production environments run the same version of the API; thus, they share the same feature set.

To use the sandbox environment, a separate API key must be created. Switch to sandbox mode in the dashboard, then create an API key.

Static IP Addresses

All outgoing traffic originates from one of the following static IP addresses. SQUAKE owns these IP addresses and never shares them for any other traffic.

EnvironmentIP AddressGeo Region
Production52.59.66.213Europa/Germany
Production52.7.39.159USA
Sandbox18.197.251.125Europa/Germany

Getting Started with SQUAKE API

This guide will help you make requests to the SQUAKE API in order to calculate emissions for a travel journey.

Choose a group of Endpoints

SQUAKE API has the following group of endpoints:

  • Calculations - Calculates carbon emissions for various activities in a low-latency process.
  • Pricing - Returns pricing for a given product and carbon quantity, valid for two weeks by default.
  • Combined Calculation & Pricing - Performs carbon calculation and pricing in a single call for convenience.
  • Carbon Comparison - Compares carbon quantities to recognizable items like cars or light bulbs.
  • Purchases - Registers a purchase to compensate for carbon emissions, requiring a prior pricing quote.
  • Products - Lists purchasable compensation options, including single climate projects and bundles.
  • Files - Manages file attachments related to purchases, such as compensation confirmations.
  • Webhooks - Allows you to receive notifications about events happening in SQUAKE.
  • Audits - Provides a list of audits or a specific audit for calculations.
  • Health Check - Verifies if SQUAKE's server is reachable.

Precision of Calculations

Bus Databases

If you want operator-specific calculations for buses, then use the following dataset supported by SQUAKE's methodology.

Car Databases

If you have specific information about car models, then use one of the following methodologies: ADEME (France), US-EPA (USA) and EU-EEA (EU).

Hotel Databases

Use the HCMI and GreenView methodologies to obtain more accurate emissions.

GLEC Databases

For road and sea logistics activities according to GLEC, use the GLEC dataset.

Train Databases

For operator-specific calculations for trains, use the train dataset.

Van Databases

For van calculations, use the EU-EEA supported dataset.

Carbon Comparison

Compare carbon quantities to more recognizable items like cars or kettles. View accepted units in this comparison database.


Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL

https://www.squake.earth/contact-us

SQUAKE.earth

product@squake.earth

Terms of Service

Languages
Servers
Production

https://api.squake.earth/

Sandbox

https://api.sandbox.squake.earth/

Calculations

Operations

Pricing

Operations

Combined Calculation & Pricing

Operations

Carbon Comparison

Operations

Purchases

Operations

Products

Operations

Files

Operations

Webhooks

Operations

Audits

Audit logs are created when enabled on calculation requests.

ℹ️ To use this feature you need to have it enabled for your account, please contact us for more information.

When Audit mode is enabled for a client, SQUAKE will generate audit logs if it's requested within the calculations request body. These logs are immutable; once they are created they cannot be altered—please use this feature only for final calculations.

Operational notes:

  • Use audit mode whenever a calculation is for past activity / post-booking (post-validated) (e.g., ticketed & already-flown flights, completed stays/trips, historical backfills, invoice reconciliation/true-ups, corrections). These records are final and must be immutable.
  • Audit mode must not be used for future-looking / pre-booking or other non-final use cases (e.g., shopping/quotes, draft or tentative itineraries, forecasting/scenario planning, preliminary estimates, or POS value requests). These are expected to change.
  • Post-booking (finalized) calculations MUST be performed with audit mode enabled.
  • Pre-booking (non-audit) calculated values must not be carried over into post-booking reporting; after the activity is finalized, the calculation must be re-run with audit mode enabled.
  • Requests that handle points-of-sale (POS) values or other preview/estimation-only calls MUST be sent without audit mode.

Rule of thumb: Past/post-validated = audit mode; Future/pre-booking = no audit mode.

If you are calculating on behalf of a legal entity, you can create an Auditable entity via the /v2/audits/entities endpoint and use the ID from the response as the audit_for property in the calculation request. This will associate all audit logs created for that calculation with the given Auditable entity.

Operations

Health Check

Check if SQUAKE's server can be reached.

Operations

Travel Data

Create travel trip data and activities for reporting and analytics.

Operations

Clients

Manage a hierarchy of clients and submit travel data on their behalf. One authenticated integration can create child clients and act for any of its descendants — no separate credential per child.

To use these endpoints you need to have this feature enabled for your account — please contact us. Until then, every /v2/clients endpoint responds with 404.

Environment isolation: sandbox and production hierarchies are entirely separate. Clients created in sandbox exist only in sandbox, ids and external_references have no parity across environments, and there is no sync in either direction (the same test/live model you may know from other providers).

Operations

List Clients

Request

Returns the authenticated client together with all of its descendants. Only clients you can act for are ever returned — never a parent, sibling, or unrelated client.

Results are paginated with the standard page / per_page query parameters; pagination metadata is returned in the response headers.

Requires this feature to be enabled for your account (contact us); otherwise this endpoint responds with 404.

Security
Bearer-Auth
Query
parent_idstring(uuid)

Return only the direct children of this client (its UUID). Must be the authenticated client or one of its descendants, otherwise client_not_found is returned.

external_referencestring

Return only the client with this exact external_reference.

querystring

Case-insensitive search across client name and external_reference.

pagenumber>= 1

Page number for pagination (starts at 1).

per_pagenumber>= 1

Number of clients per page. Falls back to the default when omitted or invalid.

curl -i -X GET \
  'https://api.squake.earth/v2/clients?parent_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&external_reference=string&query=string&page=1&per_page=1' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/jsonArray [
idstring(uuid)required

The client's unique identifier (UUID). Use this value as a parent_id or as the travel-data client_id.

namestring or null

The client's display name.

external_referencestring or null

Your own reference for this client, unique among the children of a given parent. Generated from the name when omitted on creation.

parent_idstring or null(uuid)required

The UUID of this client's parent, or null for the authenticated (root) client.

statusstringrequired

The client's lifecycle status.

Value"active"
metadataobjectrequired

A set of key-value pairs of yours that helps you link this record in your system.

]
Response
application/json
[
  {
    "id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
    "name": "BMW Germany",
    "external_reference": "bmw-de",
    "parent_id": "0f1f3d3b-2775-4cc0-885e-8d51db6d6de1",
    "status": "active",
    "metadata": {}
  }
]

Create Child Client

Request

Creates a new child client under the authenticated client (or under a visible descendant via parent_id). The child is created for travel-data ingestion only: it inherits address, tax, currency, and methodology defaults from its parent, but has no credentials, no billing or purchasing capability, and no product or project access.

Submit travel data for the new client by passing its id as the client_id on POST /v2/travel-data. The child is usable on the very next request after creation.

Requires this feature to be enabled for your account (contact us); otherwise this endpoint responds with 404.

Security
Bearer-Auth
Bodyapplication/json
namestringrequired

The child client's display name.

external_referencestring

Your own reference for the client, unique among the children of the same parent. Generated from the name when omitted.

parent_idstring(uuid)

The parent to create the child under. Defaults to the authenticated client; must be the authenticated client or one of its descendants.

metadataobject

A set of key-value pairs of yours that helps you link this record in your system.

curl -i -X POST \
  https://api.squake.earth/v2/clients \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "BMW Germany",
    "external_reference": "bmw-de",
    "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
    "metadata": {}
  }'

Responses

Created

Bodyapplication/json
idstring(uuid)required

The client's unique identifier (UUID). Use this value as a parent_id or as the travel-data client_id.

namestring or null

The client's display name.

external_referencestring or null

Your own reference for this client, unique among the children of a given parent. Generated from the name when omitted on creation.

parent_idstring or null(uuid)required

The UUID of this client's parent, or null for the authenticated (root) client.

statusstringrequired

The client's lifecycle status.

Value"active"
metadataobjectrequired

A set of key-value pairs of yours that helps you link this record in your system.

Response
application/json
{
  "id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
  "name": "BMW Germany",
  "external_reference": "bmw-de",
  "parent_id": "0f1f3d3b-2775-4cc0-885e-8d51db6d6de1",
  "status": "active",
  "metadata": {}
}

Retrieve the Authenticated Client

Request

Returns the public representation of the authenticated client. Use it to discover your own client id before creating children or submitting travel data on behalf of a descendant.

Requires this feature to be enabled for your account (contact us); otherwise this endpoint responds with 404.

Security
Bearer-Auth
curl -i -X GET \
  https://api.squake.earth/v2/clients/me \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idstring(uuid)required

The client's unique identifier (UUID). Use this value as a parent_id or as the travel-data client_id.

namestring or null

The client's display name.

external_referencestring or null

Your own reference for this client, unique among the children of a given parent. Generated from the name when omitted on creation.

parent_idstring or null(uuid)required

The UUID of this client's parent, or null for the authenticated (root) client.

statusstringrequired

The client's lifecycle status.

Value"active"
metadataobjectrequired

A set of key-value pairs of yours that helps you link this record in your system.

Response
application/json
{
  "id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
  "name": "BMW Germany",
  "external_reference": "bmw-de",
  "parent_id": "0f1f3d3b-2775-4cc0-885e-8d51db6d6de1",
  "status": "active",
  "metadata": {}
}

Retrieve a Client

Request

Returns a single visible client by id (the authenticated client or one of its descendants). Clients outside your hierarchy are indistinguishable from missing ones: both return client_not_found (404).

Requires this feature to be enabled for your account (contact us); otherwise this endpoint responds with 404.

Security
Bearer-Auth
Path
idstring(uuid)required
curl -i -X GET \
  'https://api.squake.earth/v2/clients/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idstring(uuid)required

The client's unique identifier (UUID). Use this value as a parent_id or as the travel-data client_id.

namestring or null

The client's display name.

external_referencestring or null

Your own reference for this client, unique among the children of a given parent. Generated from the name when omitted on creation.

parent_idstring or null(uuid)required

The UUID of this client's parent, or null for the authenticated (root) client.

statusstringrequired

The client's lifecycle status.

Value"active"
metadataobjectrequired

A set of key-value pairs of yours that helps you link this record in your system.

Response
application/json
{
  "id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
  "name": "BMW Germany",
  "external_reference": "bmw-de",
  "parent_id": "0f1f3d3b-2775-4cc0-885e-8d51db6d6de1",
  "status": "active",
  "metadata": {}
}

Update a Client

Request

Updates the editable fields of a visible client: name, external_reference, and metadata. Only the fields you send are changed; the others keep their current values.

Re-parenting is not supported. A parent_id that would move the client — including null, which reads as a request to make it a root — is rejected with parent_id_immutable (400) and nothing is written. Sending the client's current parent_id is accepted and ignored, so you can read a client, change a field, and send the whole object back unchanged in shape.

Requires this feature to be enabled for your account (contact us); otherwise this endpoint responds with 404.

Security
Bearer-Auth
Path
idstring(uuid)required
Bodyapplication/json
namestring
external_referencestring
metadataobject

A set of key-value pairs of yours that helps you link this record in your system.

curl -i -X PATCH \
  'https://api.squake.earth/v2/clients/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "BMW Germany GmbH",
    "external_reference": "bmw-de",
    "metadata": {}
  }'

Responses

OK

Bodyapplication/json
idstring(uuid)required

The client's unique identifier (UUID). Use this value as a parent_id or as the travel-data client_id.

namestring or null

The client's display name.

external_referencestring or null

Your own reference for this client, unique among the children of a given parent. Generated from the name when omitted on creation.

parent_idstring or null(uuid)required

The UUID of this client's parent, or null for the authenticated (root) client.

statusstringrequired

The client's lifecycle status.

Value"active"
metadataobjectrequired

A set of key-value pairs of yours that helps you link this record in your system.

Response
application/json
{
  "id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
  "name": "BMW Germany",
  "external_reference": "bmw-de",
  "parent_id": "0f1f3d3b-2775-4cc0-885e-8d51db6d6de1",
  "status": "active",
  "metadata": {}
}

Delete a Client

Request

Soft-deletes a descendant client and removes it from the client hierarchy. Only leaf clients can be deleted. If the client still has children, this endpoint returns client_has_children (422); delete its descendants first, from the bottom of the hierarchy upwards.

The authenticated client cannot delete itself. The authenticated client, an unknown or already deleted client, and a client outside your hierarchy all return client_not_found (404).

Requires this feature to be enabled for your account (contact us); otherwise this endpoint responds with 404.

Security
Bearer-Auth
Path
idstring(uuid)required
curl -i -X DELETE \
  'https://api.squake.earth/v2/clients/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

No Content

Response
No content