Gravity provisioning guide for TMCs
Set up SQUAKE Gravity for every corporate customer of a travel management company, from API keys to ongoing data maintenance.
This guide takes a travel management company (TMC) from first access to a fully maintained Gravity setup for all its corporate customers: five API steps, no support call.
It's for the tech team of a TMC that holds the booking data of many corporate customers. Each customer sees its own travel emissions in SQUAKE Gravity. Every step says what to call, what comes back and what to store on your side.
| Step | What you do | Endpoint | What you store |
|---|---|---|---|
| 0 | Get access and API keys | Through SQUAKE | Sandbox and production API keys |
| 1 | Create one client per corporate customer | POST /v2/clients | The client id against your customer record |
| 2 | Send travel data for that customer | POST /v2/travel-data | Your trip_reference, which is enough to read or delete the trip later |
| 3 | Load historic data, one time | POST /v2/travel-data, in batches | A load log per request |
| 4 | Give the customer access to reporting | POST /v2/invitations | The invitation id and accepted_at |
| 5 | Maintain the data | POST /v2/travel-data and DELETE /v2/travel-data/trips/{id} | Nothing new |
Setup runs one time per TMC and one time per customer. After go-live, new bookings flow in, and you delete changed bookings and send them again.
Step 0 Get access and API keys one time per TMC
│
Step 1 Create a client per customer one time per customer
│
Step 2 Send travel data build and test in the sandbox
│
Step 3 Load historic data one time per customer, at least 24 months
│
Step 4 Invite customer admins after the history is loaded
│
Step 5 Maintain the data ongoing: new and changed bookingsLoad the history before you invite anyone
Load the historic data (Step 3) before you invite any user (Step 4), so the customer's dashboard shows data at the first login. Load at least 24 months of history for every customer.
Terms used in this guide
- Gravity: SQUAKE's reporting and analytics platform, where your customers see their travel emissions.
- Client: an account in SQUAKE. Your TMC account is the parent client, and each corporate customer is a child client under it. You can nest clients further, because you can create a child under any client in your hierarchy: for example TMC, regional office, customer and subsidiary. See
parent_idin Step 1. - Trip: one booking or business journey. It carries dates, the booking amount, a cost center and one or more activities.
- Activity: one flight, hotel stay, car ride or train journey inside a trip. SQUAKE calculates emissions per activity.
trip_reference: your own unique, stable ID for a trip. You use it to address the trip later.external_reference: your own unique ID for one activity. SQUAKE echoes it back, so you can match each result to your input.- Methodology: the calculation standard used per activity type, for example TIM for flights or DEFRA for trains.
Step 0: Before you start
SQUAKE sets up your account by hand. After that, you create your own API keys and can start in the sandbox the same day.
Request access
Ask your SQUAKE account manager, or write to product@squake.earth, with the name of your company, a technical contact and the corporate customers you plan to connect first. SQUAKE then:
- Creates your TMC account, the parent client, in the sandbox and in production.
- Enables the features this guide needs: travel data ingestion and managing child clients.
- Agrees the default calculation methodologies for your customers with you.
- Sends a SQUAKE Dashboard login to your technical contact.
Create your API keys
- Sign in to the SQUAKE Dashboard, switch to sandbox mode and create an API key.
- Switch to production mode and create a second key.
- Store both keys in your secrets manager straight away. The Dashboard shows each key a single time.
Keys from one environment never work in the other.
| Environment | Base URL | Use for |
|---|---|---|
| Sandbox | https://api.sandbox.squake.earth | Building and testing. Data here never reaches production. |
| Production | https://api.squake.earth | Live customer data. |
The sandbox and production are fully separate. Client IDs, trips and users you create in the sandbox don't exist in production, so you repeat Step 1 in production at go-live.
Authenticate
Send the key as a Bearer token on every request. HTTP Basic Auth also works, with the key as the username and an empty password. All requests must use HTTPS (TLS 1.3+).
Check your setup
Call GET /v2/clients/me. It returns your own client: the root of your hierarchy and the default parent of every client you create. A 404 means the Clients API isn't enabled for your account yet. Contact SQUAKE.
export SQUAKE_API_KEY="<your sandbox API key>"
export BASE_URL="https://api.sandbox.squake.earth"
curl "$BASE_URL/v2/clients/me" \
--header "Authorization: Bearer $SQUAKE_API_KEY"The snippets in this guide reuse BASE_URL and the API key from above, with session in the Python snippets and headers in the Node snippets. The API reference documents every endpoint, and the OpenAPI description can generate a typed client in your language.
Every response carries a SQUAKE-Request-Id header. Log it: support uses it to trace a request.
Checkpoint for Step 0
- You have a sandbox key and a production key, both stored in your secrets manager.
GET /v2/clients/mewith the sandbox key returns200and your clientid.- The same call against the production base URL with the production key returns
200. A404means the Clients API isn't enabled yet. - Travel data ingestion and child clients are enabled in the sandbox and in production.
- Your code sends the key as a Bearer token over HTTPS and logs the
SQUAKE-Request-Idof every response.
Step 1: Create a client for each customer
Create one child client per corporate customer with POST /v2/clients, and store the id it returns in your database, against that customer.
The child client is where the customer's trips are stored and what the customer sees in Gravity. You can use it on the very next request. It has no API key of its own: you always call the API with your TMC key and name the target client. You can nest clients, for example your TMC client, a regional office, the customer and a subsidiary. Create each level with POST /v2/clients and set parent_id to the level above it.
Request
POST /v2/clients
| Field | Required | What to send |
|---|---|---|
name | Yes | The customer's display name, as it appears in Gravity. |
external_reference | Recommended | Your own customer ID. It must be unique among the children of one parent, and SQUAKE generates one from the name when you omit it. With your own ID, you can look the client up later without storing SQUAKE's id. |
parent_id | No | Defaults to your TMC client. Set it to the id of any client in your hierarchy to create the new client below it. For example, put an agency or business unit between your TMC and the customer, or a subsidiary below the customer. You can't move a client to another parent later. |
metadata | No | Key-value pairs for your own use. |
methodology_configuration | No | Overrides the calculation methodologies. Omit it and the new client gets a copy of its parent's methodologies. |
{
"name": "Example Industries GmbH",
"external_reference": "CUST-10042",
"parent_id": "0f1f3d3b-2775-4cc0-885e-8d51db6d6de1",
"metadata": { "crm_id": "0015g00000ABCDE" },
"methodology_configuration": {
"methodology_options": [
{ "activity_type": "flight", "methodology": "TIM", "version": "AT_TIME_OF_TRAVEL", "default": true },
{ "activity_type": "flight", "methodology": "DEFRA", "version": "AT_TIME_OF_TRAVEL", "default": false },
{ "activity_type": "train", "methodology": "DEFRA", "version": "AT_TIME_OF_TRAVEL", "default": true },
{ "activity_type": "car", "methodology": "DEFRA", "version": "AT_TIME_OF_TRAVEL", "default": true },
{ "activity_type": "hotel", "methodology": "GREENVIEW", "version": "AT_TIME_OF_TRAVEL", "default": true }
]
}
}Response
{
"id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"name": "Example Industries GmbH",
"external_reference": "CUST-10042",
"parent_id": "0f1f3d3b-2775-4cc0-885e-8d51db6d6de1",
"status": "active",
"metadata": { "crm_id": "0015g00000ABCDE" },
"methodology_options": [
{ "activity_type": "flight", "methodology": "TIM", "version": "AT_TIME_OF_TRAVEL", "default": true },
{ "activity_type": "flight", "methodology": "DEFRA", "version": "AT_TIME_OF_TRAVEL", "default": false },
{ "activity_type": "train", "methodology": "DEFRA", "version": "AT_TIME_OF_TRAVEL", "default": true },
{ "activity_type": "car", "methodology": "DEFRA", "version": "AT_TIME_OF_TRAVEL", "default": true },
{ "activity_type": "hotel", "methodology": "GREENVIEW", "version": "AT_TIME_OF_TRAVEL", "default": true }
]
}Store the id in your customer table, for example as squake_client_id. You pass it as client_id in Steps 2 to 4.
Make creation safe to repeat
Before you create a client, look the customer up by your own reference. If the client exists, reuse its id instead of creating a duplicate. external_reference only has to be unique among the children of one parent, so use a reference that is unique across your whole hierarchy, such as your own customer ID.
curl "$BASE_URL/v2/clients?external_reference=CUST-10042" \
--header "Authorization: Bearer $SQUAKE_API_KEY"Methodologies
Omit methodology_configuration and the new client gets a copy of its parent's methodologies. A client that has never been configured calculates flights with TIM, with DEFRA as a second methodology. It calculates trains and cars with DEFRA and hotels with GREENVIEW, always with the factors valid at the time of travel (AT_TIME_OF_TRAVEL).
To change this, send methodology_configuration.methodology_options: at most three methodologies per activity type, with exactly one marked default: true. Gravity reports the default methodology. SQUAKE calculates the others too, and you can read them through the API. See Methodology options for the methodologies available per activity type.
You can change the methodologies later with PATCH /v2/clients/{id}. Send the full list each time. SQUAKE then recalculates the customer's stored activities in the background.
Common errors
| Status | Code | Cause and fix |
|---|---|---|
400 | invalid_parent_client | parent_id isn't your client or one of its descendants. Nothing is created. |
400 | invalid_methodology_options | SQUAKE can't read the options as a list, or an entry has no boolean default. Nothing is created. |
422 | invalid_methodology_options | An unknown activity type or methodology, two defaults for one type, or more than three options per type. Nothing is created. |
404 | The Clients API isn't enabled for your account. Contact SQUAKE. |
Optional: auditable legal entities
If a customer needs immutable audit logs tied to a legal entity, for example for the assurance of its CSRD or SBTi reporting, create that entity with POST /v2/audits/entities. Send its legal_name, vat_id, external_id and address. Store the id it returns and pass it as audit_for on each trip of that entity in Step 2. Audit logging must be enabled for your account: ask SQUAKE if your customers need it.
A client and an auditable entity do different jobs, and neither overrides the other:
| Client | Auditable entity | |
|---|---|---|
| Created with | POST /v2/clients (this step) | POST /v2/audits/entities |
| What it decides | Where the trips are stored, who sees them in Gravity and which methodologies apply | Which legal entity the audit logs of a trip are linked to |
| How a trip refers to it | The root-level client_id of the request | audit_for on the trip |
Creating an entity never creates or changes a client. See Create an auditable entity.
Checkpoint for Step 1
- Every corporate customer has a client, and its
idis stored against your customer record, for example assquake_client_id. - Creation is safe to repeat: your code looks the customer up by
external_referencebefore it creates a client. - The response shows the
methodology_optionsyou expect, with exactly one default per activity type. - Every level between your TMC and a customer exists, and each client has the level above it as
parent_id. - If a customer needs audit logs for a legal entity, its auditable entity exists and you stored its
id.
Step 2: Send travel data
Push each customer's trips with POST /v2/travel-data, and set the root-level client_id to that customer's client. The response returns the emissions straight away. There's no rate limit per API key: the only limit is 50 activities per request.
The data model
client_id the customer's client ID from Step 1
trips[]
├── trip_reference your unique, stable trip ID (always send it)
├── start_date_utc required, YYYY-MM-DD
├── end_date_utc, trip_name, trip_purpose, trip_status
├── booking_provider, pnr, booking_id
├── amount_in_cents, currency
├── cost_center { name, email, department, business_unit, ... }
├── audit_for optional, auditable entity ID (Step 1)
└── activities[] at least one
├── type flight | hotel | car | train
├── external_reference your unique leg ID (always send it)
├── start_date_utc, end_date_utc
├── amount_in_cents, currency optional, per leg
├── traveler { name, email, traveler_type, department }
└── type-specific fields see the table belowRules that matter most
- Send
trip_referenceon every trip. Use an ID that never changes for that booking in your system. You can read and delete the trip with it later, so you never need to store SQUAKE's IDs. trip_referencedoesn't prevent duplicates. Sending atrip_referencethat already exists adds the activities to that trip, so sending the same trip twice doubles its emissions. Send each activity exactly one time, and correct data as described in Step 5.- Send
external_referenceon every activity, unique per leg. Theitemsof the response are a flat list across all trips, and this reference is how you match each result to its input. - Leave out
methodology. SQUAKE then uses the customer's configured default from Step 1. Only send it to override the methodology of one activity. - Don't send an
auditfield on activities. An audit log is an immutable record of how SQUAKE calculated one figure, and it's what an auditor opens to check that figure. The calculation endpoints take anauditswitch per item, but travel data doesn't need one from you: SQUAKE sets up audit logging for your account. When you read a trip's activities back withGET /v2/travel-data/trips/{trip_reference}/activities, each calculation links to the audit log it produced asaudit.id, andauditisnullif there is none. Ask SQUAKE to enable audit logging if a customer needs it. - Dates are
YYYY-MM-DDand read as UTC. For a same-day leg, send the same date as start and end. - Amounts are integers in the minor unit, so
248500withEURis 2,485.00 EUR. An amount on an activity takes precedence over the trip amount in activity-level reporting.
Fields per activity type
| Type | Needed for a good calculation | Strongly recommended |
|---|---|---|
flight | origin and destination as IATA airport codes, or routing for a multi-leg itinerary (BER-FRA-JFK) | departure_date, booking_class (economy, premium_economy, business or first), airline, flight_number, number_of_travelers |
hotel | country (ISO 3166-1 alpha-2 code), city, number_of_nights | name (enables supplier analytics), number_of_travelers, stars |
car | origin and destination as free-text addresses | usage_type (rental, taxi, company or personal_car, which decides the GHG scope), fuel_type, car_type, provider_company, number_of_days |
train | origin and destination as station or city | operator_name (for example db or sncf), fare_class, train_type, number_of_travelers |
For every field, see Create travel data items. The accepted values of fields such as train_type, fare_class, fuel_type and car_type depend on the methodology: see the methodology guides.
Send the traveler's name and email. SQUAKE matches travelers by their email address, in lowercase, within a customer. If you send a cost_center, its name is required, and its department becomes a filter in Gravity.
Send trip_status as one of these five values, and map your own booking states to them first:
planned: the booking exists, but nothing is held yet.confirmed: the booking is firm, and the trip is still ahead.in_progress: the trip is under way.completed: the trip has finished.canceled: the trip is called off.
The trip dates take precedence. A trip whose end date has passed reads completed, and a trip under way reads in_progress, whatever status you send. Only a cancellation outranks the dates. SQUAKE also recognizes common wordings such as ticketed or past, and a wording it doesn't recognize doesn't fail the request: the dates decide the status instead. See Trip status.
Sample data set
Two trips for one customer: a flight and hotel trip to London, and a rail and taxi trip to Paris. The train and the taxi use values that DEFRA accepts, because DEFRA is the customer's train and car methodology from Step 1.
{
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"trips": [
{
"trip_reference": "TMC-PNR-ABC123",
"trip_name": "Customer workshop London",
"trip_purpose": "Customer workshop",
"trip_status": "completed",
"start_date_utc": "2026-03-10",
"end_date_utc": "2026-03-12",
"booking_provider": "Example TMC",
"pnr": "ABC123",
"amount_in_cents": 148500,
"currency": "EUR",
"cost_center": { "name": "Sales DACH", "email": "sales-dach@example.com", "department": "Sales" },
"activities": [
{
"type": "flight",
"external_reference": "ABC123-SEG1",
"origin": "BER", "destination": "LHR",
"departure_date": "2026-03-10",
"booking_class": "economy",
"airline": "LH", "flight_number": "LH2472",
"number_of_travelers": 1,
"start_date_utc": "2026-03-10", "end_date_utc": "2026-03-10",
"traveler": { "name": "Jane Doe", "email": "jane.doe@example.com", "traveler_type": "employee" }
},
{
"type": "hotel",
"external_reference": "ABC123-HTL1",
"name": "Example City Hotel",
"country": "GB", "city": "London",
"number_of_nights": 2, "number_of_travelers": 1,
"start_date_utc": "2026-03-10", "end_date_utc": "2026-03-12",
"amount_in_cents": 52000, "currency": "EUR",
"traveler": { "name": "Jane Doe", "email": "jane.doe@example.com", "traveler_type": "employee" }
},
{
"type": "flight",
"external_reference": "ABC123-SEG2",
"origin": "LHR", "destination": "BER",
"departure_date": "2026-03-12",
"booking_class": "economy",
"airline": "LH", "flight_number": "LH2473",
"number_of_travelers": 1,
"start_date_utc": "2026-03-12", "end_date_utc": "2026-03-12",
"traveler": { "name": "Jane Doe", "email": "jane.doe@example.com", "traveler_type": "employee" }
}
]
},
{
"trip_reference": "TMC-BKG-778201",
"trip_name": "Supplier visit Paris",
"trip_status": "completed",
"start_date_utc": "2026-04-02",
"end_date_utc": "2026-04-02",
"booking_provider": "Example TMC",
"amount_in_cents": 31000,
"currency": "EUR",
"activities": [
{
"type": "train",
"external_reference": "778201-RAIL1",
"origin": "Frankfurt (Main) Hbf", "destination": "Paris Est",
"operator_name": "db", "fare_class": "second_class", "train_type": "international",
"number_of_travelers": 1,
"start_date_utc": "2026-04-02", "end_date_utc": "2026-04-02",
"traveler": { "name": "Max Mustermann", "email": "max.mustermann@example.com", "traveler_type": "employee" }
},
{
"type": "car",
"external_reference": "778201-TAXI1",
"origin": "Gare de l'Est, Paris, France",
"destination": "La Defense, Paris, France",
"usage_type": "taxi", "fuel_type": "hev", "car_type": "average",
"start_date_utc": "2026-04-02", "end_date_utc": "2026-04-02",
"traveler": { "name": "Max Mustermann", "email": "max.mustermann@example.com", "traveler_type": "employee" }
}
]
}
]
}Response
The example is shortened to the first item and the first trip.
{
"carbon_quantity": 333.0,
"carbon_unit": "kilogram",
"items": [
{
"type": "flight",
"trip_reference": "TMC-PNR-ABC123",
"external_reference": "ABC123-SEG1",
"carbon_quantity": 142.6,
"carbon_unit": "kilogram",
"distance": 930.0,
"distance_unit": "kilometer",
"methodology": { "meta": { "methodology": "TIM" } }
}
],
"trips": [
{
"id": "7c9e6f2a-4b81-4d3e-9a52-1f0c8b3d5e47",
"trip_reference": "TMC-PNR-ABC123",
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"submitted_by_client_id": "0f1f3d3b-2775-4cc0-885e-8d51db6d6de1",
"activity_ids": [
"2b4d6f81-9c3e-4a57-b0d2-6e1f8a4c7b93",
"5e1a9c34-7d62-4f08-b3a1-9c4e2d7f6b58",
"a1d3b5c7-2e94-4f68-9b0a-7c5d3e1f8a26"
]
}
]
}Store the carbon_quantity of each activity, in kilograms, against your external_reference if you show emissions in your own tools. Storing trips[].id and activity_ids is optional: your trip_reference is enough to read or delete a trip.
Check every item. If SQUAKE can't calculate an activity, its item carries methodology.errors, and the request still returns 200. The other activities are stored as usual. Log failed items with their external_reference, fix the input and send only that trip again, as described in Step 5.
items only reports the default methodology. To read every calculated methodology and the audit references, use GET /v2/travel-data/trips/{trip_reference}/activities. That endpoint reports co2_in_grams, in grams, not kilograms.
Code
curl --request POST "$BASE_URL/v2/travel-data" \
--header "Authorization: Bearer $SQUAKE_API_KEY" \
--header "Content-Type: application/json" \
--data @trips.jsonCommon errors
| Status | Meaning |
|---|---|
200 | Success. Check methodology.errors on each item for activities that couldn't be calculated. |
400 | The request is malformed, misses a required field, or holds more than 50 activities. Nothing is stored. |
401 | The API key is missing or invalid. |
404 | client_not_found: the client_id is neither the authenticated client nor one of its descendants. Nothing is written. |
404 | travel_data_not_found: ingesting travel data isn't enabled for your account yet. |
500 | Internal server error. |
After a 500 or a timeout, retry as described in Retries without duplicates.
Checkpoint for Step 2
- Every request names the
client_idof the customer and holds at most 50 activities across all its trips. - Every trip carries a stable
trip_reference, and every activity a uniqueexternal_reference. - You send each activity exactly one time. A repeated
trip_referenceappends activities instead of replacing them. - No response item carries
methodology.errors, or each failed item is logged with itsexternal_referenceand followed up. GET /v2/travel-data/trips/{trip_reference}returns200for a trip you sent, with theactivity_idsyou expect.- You store the
carbon_quantityperexternal_referenceif you show emissions in your own tools.
Step 3: Load historic data
Load past trips one time per customer, through the same POST /v2/travel-data endpoint, in batches of up to 50 activities, one customer at a time. Make every retry safe against duplicates.
Agree the scope with your customer
- Reporting period. Load at least the last 24 months for every customer, so the dashboard shows a trend from the first login. If the customer sets or tracks a CO₂ target, add its base or reference year, because Gravity compares against it.
- Record volume. Count trips and activities per customer and year before you start. You need these numbers to verify the load.
- Factors. With the default
AT_TIME_OF_TRAVELsetting, SQUAKE calculates each trip with the emission factors that were valid on its travel date. Historic years stay comparable with what the customer reported at the time.
Batching rules
- A request holds at most 50 activities in total, across all its trips. SQUAKE rejects a larger request before it stores anything.
- Keep all activities of one trip in the same request when they fit.
- Send a trip with more than 50 activities over several requests with the same
trip_reference. This is the one case where appending to an existing trip is what you want. - Send one customer (
client_id) per request. - Within one customer, send the requests one after another, and wait for each response before you send the next one. There's no rate limit per API key, so you can load several customers at the same time.
- Run the full load in the sandbox first, with one month of real data. Check it as described below, then repeat it in production.
Retries without duplicates
Because a repeated trip_reference appends activities, a blind retry after a timeout can store a trip twice. Before you send a batch again that failed with a timeout or a 5xx, check each of its trips with GET /v2/travel-data/trips/{trip_reference}:
404: SQUAKE didn't store the trip. Send it again.200: SQUAKE stored the trip, at least in part. If itsactivity_idscount matches what you sent, skip it. Otherwise, delete it withDELETE /v2/travel-data/trips/{trip_reference}and send it again in full.
A 4xx response fails again in the same way, so fix the input before you send the batch again.
import time
from urllib.parse import quote
def chunk_trips(trips: list[dict], max_activities: int = 50):
"""Group whole trips into batches of at most 50 activities."""
batch, count = [], 0
for trip in trips: # assumes that no single trip has more than 50 activities
n = len(trip["activities"])
if batch and count + n > max_activities:
yield batch
batch, count = [], 0
batch.append(trip)
count += n
if batch:
yield batch
def trip_url(ref: str) -> str:
return f"{BASE_URL}/v2/travel-data/trips/{quote(ref, safe='')}"
def still_to_send(batch: list[dict]) -> list[dict]:
"""After a failed request, keep the trips that didn't land in full."""
todo = []
for trip in batch:
r = session.get(trip_url(trip["trip_reference"]), timeout=30)
if r.status_code != 404:
r.raise_for_status()
if len(r.json()["activity_ids"]) == len(trip["activities"]):
continue # stored in full: don't send it again
session.delete(trip_url(trip["trip_reference"]), timeout=30).raise_for_status()
todo.append(trip) # not stored, or stored in part and now deleted
return todo
def load_history(client_id: str, trips: list[dict]) -> None:
for batch in chunk_trips(trips):
attempt = 0
while batch:
try:
send_trips(client_id, batch) # from Step 2
break
except requests.HTTPError as err:
if err.response.status_code < 500 or attempt == 2:
raise # a 4xx fails again in the same way: fix the input first
except (requests.ConnectionError, requests.Timeout):
if attempt == 2:
raise
time.sleep(5 * 2 ** attempt)
attempt += 1
batch = still_to_send(batch)URL-encode your trip_reference when you use it in a path, and avoid / in references.
Verify the load
- Count.
GET /v2/travel-data/trips?page=1&items=100returns aTotal-Countheader with the number of stored trips. The list holds the trips of all your clients, so compare the count with the total you sent, and readclient_idon each trip for a count per customer. - Spot check. Read at least 10 trips from at least 10 customers, or from every customer if you have fewer, with their activities. Compare dates, routes and travelers with your source.
- Failed items. Fix every item that returned
methodology.errorsand send its trip again, as described in Step 5. - Dashboard. After the first admin of a customer accepts the invitation (Step 4), check with them that the loaded history shows in Gravity. Gravity refreshes on a schedule, so allow some time before new data appears.
Checkpoint for Step 3
- You loaded at least 24 months of trips for every customer, plus the base year if the customer tracks a CO₂ target.
- You counted trips and activities per customer and year before the load, and the
Total-Countof stored trips matches your total. - The spot check of stored trips and activities matches your source.
- Every item with
methodology.errorsis fixed and sent again. - No request holds more than 50 activities, no trip went out twice, and every retry checks
GET /v2/travel-data/trips/{trip_reference}before it sends a trip again. - You keep a load log with the request and the
SQUAKE-Request-Idof every batch.
Step 4: Give your customer access to reporting
When the customer's history is loaded (Step 3), invite an admin of the customer into the customer's client with POST /v2/invitations. The admin gets an email, sets a password and lands in Gravity, where they only see their own company's data. As an admin, they can invite their colleagues from inside Gravity.
You have two options:
- You invite (recommended). Call the API from your own onboarding flow. It's fully self-service.
- SQUAKE invites. Send the names and email addresses of the admins and the customer's
external_referenceto your SQUAKE account manager. This suits the first few customers or a one-off.
You manage your own team's users in the SQUAKE Dashboard, not through this endpoint. You can't invite users into your own TMC client.
Request
POST /v2/invitations
| Field | Required | What to send |
|---|---|---|
client_id | Yes | The customer's client id from Step 1. It must be one of your child clients. |
user_email | Yes | The admin's work email address. |
role | Yes | Always admin. The admin invites the rest of the customer's team from inside Gravity. |
first_name, last_name | No | Shown in the invitation email. |
locale | No | Language of the email and the sign-up page: en (default), de or fr. |
{
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"user_email": "travel.manager@example.com",
"role": "admin",
"first_name": "Erika",
"last_name": "Musterfrau",
"locale": "de"
}Response
{
"id": "9a7c1e52-3b84-4d60-8f21-6c5d0e9b7a13",
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"user_email": "travel.manager@example.com",
"first_name": "Erika",
"last_name": "Musterfrau",
"role": "admin",
"locale": "de",
"sent_at": "2026-11-03T09:15:00Z",
"accepted_at": null,
"invitation_url": "https://app.squake.earth/accept-invite/..."
}Store the invitation id per user. Check progress with GET /v2/invitations/{id}: accepted_at stays null until the user has signed up.
Inviting the same email address to the same client again is safe. It sends the email again and keeps the same invitation_url, so older links keep working. Use it as your "resend invitation" button. After the user accepts, the invitation can't go out again.
Treat the invitation link like a password reset link
Whoever opens invitation_url can set the user's password. Only share it with the invited person.
Code
curl --request POST "$BASE_URL/v2/invitations" \
--header "Authorization: Bearer $SQUAKE_API_KEY" \
--header "Content-Type: application/json" \
--data '{"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5", "user_email": "travel.manager@example.com", "role": "admin", "first_name": "Erika", "last_name": "Musterfrau", "locale": "de"}'Common errors
| Status | Code | Cause and fix |
|---|---|---|
400 | invalid_role | role is missing, unknown or not a client-level role. Send admin. |
400 | invalid_locale | locale isn't en, de or fr. |
403 | client_not_invitable | client_id is missing or is your own TMC client. Invitations only go into child clients. |
404 | client_id isn't a client in your hierarchy. | |
404 | not_found | On GET /v2/invitations/{id}: the invitation doesn't exist or belongs to a client outside your hierarchy. |
422 | email_not_available | The email address already belongs to a user outside this customer's client. |
422 | invitation_already_accepted | The user has already accepted an invitation to this client. |
Checkpoint for Step 4
- Every invitation went out with the role
admin, and you stored itsidagainst the admin. GET /v2/invitations/{id}showssent_atfor every invitation, and at least one admin per customer hasaccepted_atset.- You send an open invitation again with the same call, and its
invitation_urlstays the same. - An admin who signs in sees only their own company's data, including the loaded history.
Step 5: Maintain the data
There's no update endpoint for trips or activities. You add new segments by appending them, and you correct anything else by deleting the trip and sending it again in full.
What to do when
| Situation in your system | What to call |
|---|---|
| New booking | POST /v2/travel-data with a new trip_reference (Step 2). |
| New segment added to an existing booking | POST /v2/travel-data with the existing trip_reference and only the new activities. |
| A field changed: date, route, class, price, traveler or cost center | DELETE /v2/travel-data/trips/{trip_reference}, then POST the complete, corrected trip. |
| One segment removed or refunded | Delete the trip, then send it again without that segment. |
| Whole booking canceled before travel | DELETE /v2/travel-data/trips/{trip_reference}. A canceled booking doesn't belong in reporting, and sending a trip again appends activities instead of changing its status. |
An item came back with methodology.errors | Fix the input, delete the trip and send it again in full. |
| The customer wants a different methodology | PATCH /v2/clients/{id} with the full methodology_configuration. SQUAKE recalculates the stored data. |
| New legal entity or subsidiary at the customer | POST /v2/clients with parent_id set to the customer's client (Step 1). |
Send new and changed bookings on a regular schedule that fits your system, for example a nightly job. Only send trips that are booked or traveled: quotes and drafts don't belong in reporting.
Delete a trip
DELETE /v2/travel-data/trips/{id} accepts SQUAKE's trip id or your trip_reference. It removes the trip with all its activities and calculations and returns 204 No Content.
- A delete is permanent. Sending the trip again recalculates it and creates new SQUAKE IDs.
- Audit logs stay. They're an immutable record of what SQUAKE calculated.
- Gravity refreshes on a schedule, so a deleted trip can still show there for a while.
curl --request DELETE "$BASE_URL/v2/travel-data/trips/TMC-PNR-ABC123" \
--header "Authorization: Bearer $SQUAKE_API_KEY"Reconcile regularly
Read back what SQUAKE stored and compare it with your system, for example every month:
| Endpoint | Returns |
|---|---|
GET /v2/travel-data/trips?page=1&items=100 | All stored trips of your clients, most recently ingested first, up to 100 per page. The totals come in the Total-Count and Total-Pages headers. |
GET /v2/travel-data/trips/{trip_reference} | One trip with its dates, amount, cost center and activity_ids. |
GET /v2/travel-data/trips/{trip_reference}/activities | All activities of the trip, with the traveler and every calculation (co2_in_grams). |
When you parse activities, read type first. origin and destination are absent, not null, for hotels, and fuel_type only exists for cars and trains.
Remove a customer
Delete the customer's trips first: list your trips and delete each one whose client_id is the customer's. Then delete the customer's client with DELETE /v2/clients/{id}. You can only delete a client without children, so delete its subsidiaries first, from the bottom of the hierarchy up. SQUAKE soft-deletes the client and removes it from your hierarchy. The users invited into the client are deleted with it: they no longer exist and can't sign in.
Checkpoint for Step 5
- A scheduled job sends new and changed bookings, for example every night.
- Every correction deletes the trip first and then sends the complete trip again.
- A new segment of an existing booking goes out with the existing
trip_referenceand only the new activities. - You delete canceled bookings, and you never send quotes or drafts.
- A regular reconciliation, for example every month, compares the
Total-CountofGET /v2/travel-data/tripswith your own system.
Error reference
Errors come back as an errors array. Each error has a code and a readable detail:
{
"errors": [
{
"code": "travel_data_not_found",
"detail": "The requested travel data does not exist or is not accessible."
}
]
}| Status | Code | Typical cause | Fix |
|---|---|---|---|
400 | A travel data request is malformed, misses a required field, or holds more than 50 activities. | Validate the JSON, add the missing field, or split the batch. | |
400 | invalid_parent_client | parent_id isn't your client or one of its descendants. | Use an id from your own hierarchy, in the same environment. |
400, 422 | invalid_methodology_options | The methodology list is unreadable or not allowed. | Send one default: true per activity type and at most three options per type. |
400 | parent_id_immutable | An update tried to move a client to another parent. | Not supported. Create a new client instead. |
400 | invalid_role, invalid_locale | An invitation has an unknown role or locale. | Send the role admin and the locale en, de or fr. |
401 | The API key is missing or invalid, for example a key from the other environment. | Check the key and the base URL. | |
403 | client_not_invitable | client_id is missing or is your own TMC client. | Use the id of a child client from Step 1. |
404 | client_not_found | client_id isn't one of your clients. | Use the id from Step 1, in the same environment. |
404 | travel_data_not_found | The trip doesn't exist or isn't yours, or travel data ingestion isn't enabled for your account. | Check the reference. Contact SQUAKE if every POST fails. |
404 | The Clients API isn't enabled for your account. | Contact SQUAKE. | |
422 | client_has_children | You tried to delete a client that still has child clients. | Delete from the bottom of the hierarchy up. |
422 | email_not_available | The invited email address belongs to a user outside the client. | Invite another address for this customer. |
422 | invitation_already_accepted | The user has already accepted an invitation to this client. | Nothing to send: the user can already sign in. |
500 | Internal server error. | Retry safely (Step 3) and check the status page. |
Go-live checklist
Run the checkpoint of every step against production, then confirm:
- The production API key is created and stored in your secrets manager.
GET /v2/clients/meworks in production.- The full flow is tested in the sandbox with one month of real data and reconciled.
- Every trip carries a stable
trip_reference, and every activity anexternal_reference. - Batches stay at 50 activities or fewer.
- Retries check for existing trips before they send a trip again.
- Items with
methodology.errorsare logged and followed up. - Every customer has a client in production, and its
idis stored. - At least 24 months of historic data are loaded and verified per customer.
- The customer admins are invited, and at least one admin per customer has accepted.
- The scheduled job for new and changed bookings is running.
- Your code logs the
SQUAKE-Request-Idof every call.
Get help
- Questions: the support request form or your SQUAKE account manager.
- Incidents: the same support request form. Include the
SQUAKE-Request-Idand thetrip_reference. - Feedback on this guide or the API: the feedback form.
- Service health: the status page.
Related
- Travel Data API
- Create travel data items
- Stored travel data
- Clients and Invitations
- Audit mode
- Calculation API examples, per methodology
- Create Child Client, Create Travel Data Items and Invite a User in the API reference