For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 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.


Response

200 OK β€” Example

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


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.

Last updated