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.

StepWhat you doEndpointWhat you store
0Get access and API keysThrough SQUAKESandbox and production API keys
1Create one client per corporate customerPOST /v2/clientsThe client id against your customer record
2Send travel data for that customerPOST /v2/travel-dataYour trip_reference, which is enough to read or delete the trip later
3Load historic data, one timePOST /v2/travel-data, in batchesA load log per request
4Give the customer access to reportingPOST /v2/invitationsThe invitation id and accepted_at
5Maintain the dataPOST /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 bookings

Load 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_id in 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

  1. Sign in to the SQUAKE Dashboard, switch to sandbox mode and create an API key.
  2. Switch to production mode and create a second key.
  3. 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.

EnvironmentBase URLUse for
Sandboxhttps://api.sandbox.squake.earthBuilding and testing. Data here never reaches production.
Productionhttps://api.squake.earthLive 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/me with the sandbox key returns 200 and your client id.
  • The same call against the production base URL with the production key returns 200. A 404 means 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-Id of 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

FieldRequiredWhat to send
nameYesThe customer's display name, as it appears in Gravity.
external_referenceRecommendedYour 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_idNoDefaults 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.
metadataNoKey-value pairs for your own use.
methodology_configurationNoOverrides 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

201 Createdapplication/json
{
  "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

StatusCodeCause and fix
400invalid_parent_clientparent_id isn't your client or one of its descendants. Nothing is created.
400invalid_methodology_optionsSQUAKE can't read the options as a list, or an entry has no boolean default. Nothing is created.
422invalid_methodology_optionsAn unknown activity type or methodology, two defaults for one type, or more than three options per type. Nothing is created.
404The Clients API isn't enabled for your account. Contact SQUAKE.

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:

ClientAuditable entity
Created withPOST /v2/clients (this step)POST /v2/audits/entities
What it decidesWhere the trips are stored, who sees them in Gravity and which methodologies applyWhich legal entity the audit logs of a trip are linked to
How a trip refers to itThe root-level client_id of the requestaudit_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 id is stored against your customer record, for example as squake_client_id.
  • Creation is safe to repeat: your code looks the customer up by external_reference before it creates a client.
  • The response shows the methodology_options you 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 below

Rules that matter most

  • Send trip_reference on 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_reference doesn't prevent duplicates. Sending a trip_reference that 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_reference on every activity, unique per leg. The items of 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 audit field 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 an audit switch 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 with GET /v2/travel-data/trips/{trip_reference}/activities, each calculation links to the audit log it produced as audit.id, and audit is null if there is none. Ask SQUAKE to enable audit logging if a customer needs it.
  • Dates are YYYY-MM-DD and read as UTC. For a same-day leg, send the same date as start and end.
  • Amounts are integers in the minor unit, so 248500 with EUR is 2,485.00 EUR. An amount on an activity takes precedence over the trip amount in activity-level reporting.

Fields per activity type

TypeNeeded for a good calculationStrongly recommended
flightorigin 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
hotelcountry (ISO 3166-1 alpha-2 code), city, number_of_nightsname (enables supplier analytics), number_of_travelers, stars
carorigin and destination as free-text addressesusage_type (rental, taxi, company or personal_car, which decides the GHG scope), fuel_type, car_type, provider_company, number_of_days
trainorigin and destination as station or cityoperator_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.

200 OKapplication/json
{
  "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.json

Common errors

StatusMeaning
200Success. Check methodology.errors on each item for activities that couldn't be calculated.
400The request is malformed, misses a required field, or holds more than 50 activities. Nothing is stored.
401The API key is missing or invalid.
404client_not_found: the client_id is neither the authenticated client nor one of its descendants. Nothing is written.
404travel_data_not_found: ingesting travel data isn't enabled for your account yet.
500Internal server error.

After a 500 or a timeout, retry as described in Retries without duplicates.

Checkpoint for Step 2

  • Every request names the client_id of the customer and holds at most 50 activities across all its trips.
  • Every trip carries a stable trip_reference, and every activity a unique external_reference.
  • You send each activity exactly one time. A repeated trip_reference appends activities instead of replacing them.
  • No response item carries methodology.errors, or each failed item is logged with its external_reference and followed up.
  • GET /v2/travel-data/trips/{trip_reference} returns 200 for a trip you sent, with the activity_ids you expect.
  • You store the carbon_quantity per external_reference if 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_TRAVEL setting, 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 its activity_ids count matches what you sent, skip it. Otherwise, delete it with DELETE /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=100 returns a Total-Count header 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 read client_id on 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.errors and 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-Count of stored trips matches your total.
  • The spot check of stored trips and activities matches your source.
  • Every item with methodology.errors is 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-Id of 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_reference to 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

FieldRequiredWhat to send
client_idYesThe customer's client id from Step 1. It must be one of your child clients.
user_emailYesThe admin's work email address.
roleYesAlways admin. The admin invites the rest of the customer's team from inside Gravity.
first_name, last_nameNoShown in the invitation email.
localeNoLanguage 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

201 Createdapplication/json
{
  "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

StatusCodeCause and fix
400invalid_rolerole is missing, unknown or not a client-level role. Send admin.
400invalid_localelocale isn't en, de or fr.
403client_not_invitableclient_id is missing or is your own TMC client. Invitations only go into child clients.
404client_id isn't a client in your hierarchy.
404not_foundOn GET /v2/invitations/{id}: the invitation doesn't exist or belongs to a client outside your hierarchy.
422email_not_availableThe email address already belongs to a user outside this customer's client.
422invitation_already_acceptedThe user has already accepted an invitation to this client.

Checkpoint for Step 4

  • Every invitation went out with the role admin, and you stored its id against the admin.
  • GET /v2/invitations/{id} shows sent_at for every invitation, and at least one admin per customer has accepted_at set.
  • You send an open invitation again with the same call, and its invitation_url stays 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 systemWhat to call
New bookingPOST /v2/travel-data with a new trip_reference (Step 2).
New segment added to an existing bookingPOST /v2/travel-data with the existing trip_reference and only the new activities.
A field changed: date, route, class, price, traveler or cost centerDELETE /v2/travel-data/trips/{trip_reference}, then POST the complete, corrected trip.
One segment removed or refundedDelete the trip, then send it again without that segment.
Whole booking canceled before travelDELETE /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.errorsFix the input, delete the trip and send it again in full.
The customer wants a different methodologyPATCH /v2/clients/{id} with the full methodology_configuration. SQUAKE recalculates the stored data.
New legal entity or subsidiary at the customerPOST /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:

EndpointReturns
GET /v2/travel-data/trips?page=1&items=100All 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}/activitiesAll 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_reference and 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-Count of GET /v2/travel-data/trips with 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."
    }
  ]
}
StatusCodeTypical causeFix
400A 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.
400invalid_parent_clientparent_id isn't your client or one of its descendants.Use an id from your own hierarchy, in the same environment.
400, 422invalid_methodology_optionsThe methodology list is unreadable or not allowed.Send one default: true per activity type and at most three options per type.
400parent_id_immutableAn update tried to move a client to another parent.Not supported. Create a new client instead.
400invalid_role, invalid_localeAn invitation has an unknown role or locale.Send the role admin and the locale en, de or fr.
401The API key is missing or invalid, for example a key from the other environment.Check the key and the base URL.
403client_not_invitableclient_id is missing or is your own TMC client.Use the id of a child client from Step 1.
404client_not_foundclient_id isn't one of your clients.Use the id from Step 1, in the same environment.
404travel_data_not_foundThe 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.
404The Clients API isn't enabled for your account.Contact SQUAKE.
422client_has_childrenYou tried to delete a client that still has child clients.Delete from the bottom of the hierarchy up.
422email_not_availableThe invited email address belongs to a user outside the client.Invite another address for this customer.
422invitation_already_acceptedThe user has already accepted an invitation to this client.Nothing to send: the user can already sign in.
500Internal 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/me works 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 an external_reference.
  • Batches stay at 50 activities or fewer.
  • Retries check for existing trips before they send a trip again.
  • Items with methodology.errors are logged and followed up.
  • Every customer has a client in production, and its id is 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-Id of every call.

Get help

On this page

POST/v2/travel-data

Run this request against the sandbox with your test key.

Open in API reference