Create Travel Data Items

Ingest trip records with nested activities via POST /v2/travel-data.

Push one or more complete trip records into SQUAKE for emissions calculation, reporting, and carbon accounting.

---

Endpoint

POST /v2/travel-data

Authentication

• Bearer Token or HTTP Basic Auth (API key as username, no password).

Content-Type

Content-Type: application/json

Environments

Environment	Base URL
Sandbox	https://api.sandbox.squake.earth
Production	https://api.squake.earth

---

Request envelope

{
  "trips": [ <Trip>, ... ]
}

You can send multiple trips per request. Each trip must include at least one activity and a start_date_utc.

---

Submitting on behalf of another client

If your account is set up to manage multiple clients (contact us to enable it), you can create child clients and push their travel data through your own credentials — no separate API key per child. Add an optional root-level client_id to store the trips under a descendant client:

{
  "client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
  "trips": [ <Trip>, ... ]
}

• client_id is a client id (UUID) as returned by the /v2/clients endpoints.

• Omit client_id to ingest for the authenticated client — existing integrations are unaffected.

• Providing client_id requires this to be enabled for your account (contact us). A client_id outside your hierarchy returns 404 with error code client_not_found, and nothing is written.

• All trips in one request are stored under the same target client, using that client's methodologies and configuration. Your authenticated credential remains the recorded actor.

CSV imports (/v2/travel-data/imports) do not support client_id. Sandbox and production hierarchies are separate: a client_id from one environment is never valid in the other. See Create Child Client for creating and listing the clients you can act for.

---

Trip fields

Field	Type	Required	Description
activities	array	✅	One or more activity objects.
start_date_utc	string (ISO 8601)	✅	Trip start date. Format: YYYY-MM-DD.
end_date_utc	string (ISO 8601)	—	Trip end date.
trip_reference	string	—	Your unique ID for this trip. Reusing a trip_reference appends activities to the existing trip rather than creating a new one.
trip_name	string	—	Human-readable label (e.g. "Business trip to London").
trip_purpose	string	—	Purpose of the trip (e.g. "Customer workshop").
trip_status	string	—	Status of the trip (e.g. "completed").
booking_provider	string	—	TMC or booking platform name.
pnr	string	—	Passenger Name Record (common in flight bookings).
amount_in_cents	integer	—	Total trip cost in the smallest currency unit.
currency	string	—	ISO 4217 currency code (e.g. "EUR").
cost_center	object	—	Cost center for attribution. See below.
audit_for	string	—	UUID of an Auditable entity — associates the trip with a legal entity in audit logs.
metadata	object	—	Arbitrary key-value pairs for your own use.
project_reference	string	—	Internal project or campaign reference.
booking_id	string	—	Booking system ID.
external_source	string	—	Name of the external system that created the trip.
external_source_id	string	—	ID of the trip in that external system.

trip_reference and upsert behaviour If you send a request with a trip_reference that already exists, the new activities are appended to that trip — no duplicate is created. Useful for incremental imports where segments are ticketed at different times. Omitting trip_reference creates a new trip on every call.

Cost center fields

Field	Type	Required	Description
name	string	✅	Name of the cost center.
email	string	✅	Contact email.
purpose	string	—	Description or purpose.
department	string	—	Department name — available as a filter in the SQUAKE UI.
business_unit	string	—	Business unit.
city	string	—	City.
country_alpha2	string	—	ISO 3166-1 alpha-2 country code (e.g. "DE").

---

Activity fields

All activities share a common base, then add type-specific fields.

Common fields

Field	Type	Required	Description
type	string	✅	flight, hotel, car, or train.
methodology	string	—	Optional calculation methodology override for this activity type.
external_reference	string	—	Your reference ID for this leg — echoed back in the response.
start_date_utc	string	—	Activity start date (YYYY-MM-DD).
end_date_utc	string	—	Activity end date (YYYY-MM-DD).
traveler	object	—	Traveler attached to this activity.

If you omit methodology, SQUAKE uses your account's configured default methodology for that activity type. Pass methodology only when you want to override that default for a specific activity. The fields needed for calculation still depend on the methodology that SQUAKE resolves.

Traveler fields

Field	Type	Required	Description
name	string	✅	Full name.
email	string	✅	Email address.
traveler_type	string	—	employee, contractor, or guest.
department	string	—	Traveler's department.

Flight-specific fields

Field	Description
origin	IATA airport code (e.g. "BER").
destination	IATA airport code (e.g. "LHR").
airline	IATA airline code (e.g. "LH").
flight_number	Flight number (e.g. "LH2472").
booking_class	economy, premium_economy, business, or first.
departure_date	Departure date (YYYY-MM-DD).
number_of_travelers	Passenger count.

Methodology overrides: ADEME, BASE-EMPREINTE, CO2-EMISSIEFACTOREN-NL, DEFRA, GATE4, ICAO, TIM, TU-CHALMERS, US-EPA.

Hotel-specific fields

Field	Description
name	Hotel name — supports supplier analytics in the SQUAKE UI.
country	ISO 3166-1 alpha-2 country code (e.g. "GB").
city	City name.
number_of_nights	Length of stay.
number_of_travelers	Guest count.
stars	Star rating (used by some methodologies).

Methodology overrides: DEFRA, HCMI, GREENVIEW.

Car-specific fields

Field	Description
origin	Pickup location (free-text address, e.g. "London Heathrow Airport, United Kingdom").
destination	Drop-off location.
fuel_type	e.g. diesel, petrol, hev, electricity.
car_type	e.g. average, large.
usage_type	rental, taxi, company, or personal_car. Determines GHG scope.
provider_company	Rental or ride-hailing company (e.g. "Hertz", "Uber").
number_of_days	Rental duration in days.

Methodology overrides: ACRISS, BASIC, DEFRA, EU-EEA, US-EPA.

Train-specific fields

Field	Description
origin	Origin station or city.
destination	Destination station or city.
number_of_travelers	Passenger count.
train_type	e.g. high_speed, mainline, light, international.
fare_class	e.g. first_class, second_class.
fuel_type	Fuel type if applicable.
operator_name	Operator identifier (e.g. "sncf", "db").

Methodology overrides: ADEME, BASE-EMPREINTE, CO2-EMISSIEFACTOREN-NL, DEFRA, GREEN-TRAVEL-PLEDGE, REM, SQUAKE, US-EPA.

---

Request example

A complete business trip: outbound flight BER → LHR, hotel in London, taxi from Heathrow, and the return flight. The taxi activity omits methodology, so SQUAKE uses the account's configured car default.

{
  "trips": [
    {
      "amount_in_cents": 248500,
      "currency": "EUR",
      "trip_name": "Example business trip to London",
      "trip_purpose": "Customer workshop",
      "trip_reference": "TRIP-EXAMPLE-002",
      "trip_status": "completed",
      "start_date_utc": "2026-03-10",
      "end_date_utc": "2026-03-12",
      "booking_provider": "Example TMC",
      "pnr": "ABC123",
      "activities": [
        {
          "type": "flight",
          "methodology": "TIM",
          "external_reference": "ACTIVITY-FLIGHT-OUTBOUND",
          "origin": "BER",
          "destination": "LHR",
          "departure_date": "2026-03-10",
          "booking_class": "economy",
          "number_of_travelers": 1,
          "airline": "LH",
          "flight_number": "LH2472",
          "start_date_utc": "2026-03-10",
          "end_date_utc": "2026-03-10",
          "traveler": {
            "name": "Jane Doe",
            "email": "[e-mail]",
            "traveler_type": "employee"
          }
        },
        {
          "type": "hotel",
          "methodology": "DEFRA",
          "external_reference": "ACTIVITY-HOTEL-001",
          "name": "Example City Hotel",
          "number_of_nights": 2,
          "country": "GB",
          "city": "London",
          "start_date_utc": "2026-03-10",
          "end_date_utc": "2026-03-12",
          "number_of_travelers": 1,
          "traveler": {
            "name": "Jane Doe",
            "email": "[e-mail]",
            "traveler_type": "employee"
          }
        },
        {
          "type": "car",
          "external_reference": "ACTIVITY-CAR-001",
          "origin": "London Heathrow Airport, United Kingdom",
          "destination": "Canary Wharf, London, United Kingdom",
          "fuel_type": "hev",
          "car_type": "average",
          "usage_type": "taxi",
          "provider_company": "Example Ride Provider",
          "number_of_days": 1,
          "start_date_utc": "2026-03-11",
          "end_date_utc": "2026-03-11",
          "traveler": {
            "name": "Jane Doe",
            "email": "[e-mail]",
            "traveler_type": "employee"
          }
        },
        {
          "type": "flight",
          "methodology": "TIM",
          "external_reference": "ACTIVITY-FLIGHT-RETURN",
          "origin": "LHR",
          "destination": "BER",
          "departure_date": "2026-03-12",
          "booking_class": "economy",
          "number_of_travelers": 1,
          "airline": "LH",
          "flight_number": "LH2473",
          "start_date_utc": "2026-03-12",
          "end_date_utc": "2026-03-12",
          "traveler": {
            "name": "Jane Doe",
            "email": "[e-mail]",
            "traveler_type": "employee"
          }
        }
      ],
      "cost_center": {
        "name": "Example Cost Center",
        "purpose": "Sales",
        "email": "[e-mail]"
      }
    }
  ]
}

---

Response

200 OK — Example

{
  "carbon_quantity": 333.0,
  "carbon_unit": "kilogram",
  "items": [
    {
      "carbon_quantity": 142.6,
      "carbon_unit": "kilogram",
      "external_reference": "ACTIVITY-FLIGHT-OUTBOUND",
      "trip_reference": "TRIP-EXAMPLE-002",
      "type": "flight",
      "distance": 930.0,
      "distance_unit": "kilometer",
      "methodology": {
        "carbon": { "quantity": 142.6, "unit": "kilogram" },
        "distance": { "distance": 930.0, "unit": "kilometer" },
        "emission_factors": { "energy_scope": "ttw" },
        "meta": { "methodology": "TIM" }
      }
    },
    {
      "carbon_quantity": 36.8,
      "carbon_unit": "kilogram",
      "external_reference": "ACTIVITY-HOTEL-001",
      "trip_reference": "TRIP-EXAMPLE-002",
      "type": "hotel",
      "methodology": {
        "carbon": { "quantity": 36.8, "unit": "kilogram" },
        "meta": { "methodology": "DEFRA" }
      }
    },
    {
      "carbon_quantity": 14.2,
      "carbon_unit": "kilogram",
      "external_reference": "ACTIVITY-CAR-001",
      "trip_reference": "TRIP-EXAMPLE-002",
      "type": "car",
      "distance": 32.0,
      "distance_unit": "kilometer",
      "methodology": {
        "carbon": { "quantity": 14.2, "unit": "kilogram" },
        "distance": { "distance": 32.0, "unit": "kilometer" },
        "emission_factors": { "energy_scope": "ttw" },
        "meta": { "methodology": "DEFRA" }
      }
    },
    {
      "carbon_quantity": 139.4,
      "carbon_unit": "kilogram",
      "external_reference": "ACTIVITY-FLIGHT-RETURN",
      "trip_reference": "TRIP-EXAMPLE-002",
      "type": "flight",
      "distance": 930.0,
      "distance_unit": "kilometer",
      "methodology": {
        "carbon": { "quantity": 139.4, "unit": "kilogram" },
        "distance": { "distance": 930.0, "unit": "kilometer" },
        "emission_factors": { "energy_scope": "ttw" },
        "meta": { "methodology": "TIM" }
      }
    }
  ]
}

Response fields

Field	Description
carbon_quantity	Total emissions across all activities, in carbon_unit.
carbon_unit	Unit for all carbon values — typically kilogram.
items	Per-activity breakdown, one entry per activity in the request.
items[].external_reference	Echoed from your request — use this to match results to input.
items[].trip_reference	Reference of the trip this item belongs to, echoed from your request. items are flattened across all trips, so use this to match each result back to its source trip.
items[].type	Activity type (flight, hotel, car, train).
items[].carbon_quantity	Emissions for this activity.
items[].distance	Calculated or geocoded distance (where applicable).
items[].methodology	Detailed breakdown: carbon, distance, emission factors, methodology name.
items[].methodology.errors	Present only if this activity could not be calculated.

---

Errors

Status	Meaning
200	Success — check methodology.errors per item for partial failures.
400	Malformed request or missing required field.
401	Missing or invalid API key.
404	client_not_found — the client_id is not the authenticated client or one of its descendants. Nothing is written.
500	Internal server error.

---

cURL

curl --request POST "https://api.sandbox.squake.earth/v2/travel-data" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "trips": [ ... ] }'

---

Implementation notes

Set external_reference on every activity. Response items are flattened across all trips in the request, so use external_reference to identify each activity and the echoed trip_reference to know which trip it belongs to. Together they let you reconcile every response item back to your input.

Dates use ISO 8601 (YYYY-MM-DD). The _utc suffix means SQUAKE stores and interprets them as UTC. For same-day legs, start_date_utc and end_date_utc may be identical.

trip_reference is your idempotency key for trip identity. Reuse it to incrementally add activities to a trip as segments get ticketed. Omit it to always create a new trip.

usage_type determines GHG scope for car activities. Use rental or taxi for Scope 3.6 (third-party vehicles), company for Scope 1 (company fleet), and personal_car for Scope 3.6 (employee reimbursement).

Partial failures don't fail the whole request. An activity with an unrecognised or missing field returns methodology.errors — the HTTP status is still 200. Check each item individually in error-sensitive workflows.