> For the complete documentation index, see [llms.txt](https://docs-integration.squake.earth/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-integration.squake.earth/travel-data/create-travel-data-items.md). # Create Travel Data Items 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 ```json { "trips": [ , ... ] } ``` 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: ```json { "client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5", "trips": [ , ... ] } ``` * `client_id` is a client `id` (UUID) as returned by the [`/v2/clients`](https://docs-v2.squake.earth/docs/openapi/clients/get-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](https://docs-v2.squake.earth/docs/openapi/clients/post-v2-clients) 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. Must be positive when `currency` is provided. | | `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. | | `amount_in_cents` | integer | — | Cost of this activity in the smallest currency unit. Must be positive when `currency` is provided. | | `currency` | string | — | ISO 4217 currency code for this activity (e.g. `"EUR"`). | | `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. Trip-level and activity-level monetary values can be sent together and do not have to match. Use trip-level values for the overall booking and activity-level values to attribute spend to individual legs. In reporting flows that use activity spend, an activity's `amount_in_cents` and `currency` take precedence over the trip-level values. Do not send `amount_base_currency`; the API neither accepts nor returns that field. ### 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. ```json { "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", "amount_in_cents": 65000, "currency": "EUR", "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": "jane.doe@example.com", "traveler_type": "employee" } }, { "type": "hotel", "methodology": "DEFRA", "external_reference": "ACTIVITY-HOTEL-001", "amount_in_cents": 98500, "currency": "EUR", "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": "jane.doe@example.com", "traveler_type": "employee" } }, { "type": "car", "external_reference": "ACTIVITY-CAR-001", "amount_in_cents": 20000, "currency": "EUR", "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": "jane.doe@example.com", "traveler_type": "employee" } }, { "type": "flight", "methodology": "TIM", "external_reference": "ACTIVITY-FLIGHT-RETURN", "amount_in_cents": 65000, "currency": "EUR", "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": "jane.doe@example.com", "traveler_type": "employee" } } ], "cost_center": { "name": "Example Cost Center", "purpose": "Sales", "email": "cost-center@example.com" } } ] } ``` *** ## Response ### 200 OK — Example ```json { "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" } } } ], "trips": [ { "id": "7c9e6f2a-4b81-4d3e-9a52-1f0c8b3d5e47", "trip_reference": "TRIP-EXAMPLE-002", "client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5", "submitted_by_client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5", "activity_ids": [ "2b4d6f81-9c3e-4a57-b0d2-6e1f8a4c7b93", "5e1a9c34-7d62-4f08-b3a1-9c4e2d7f6b58", "c84f1d27-3e95-4b60-a7d8-2f1b9e6c4a03", "a1d3b5c7-2e94-4f68-9b0a-7c5d3e1f8a26" ] } ] } ``` ### 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. | | `trips` | The trips this request persisted — one entry per trip, with the IDs you need to read the data back. | | `trips[].id` | SQUAKE's identifier for the trip. | | `trips[].trip_reference` | Echoed from your request. Usable in place of `id` when addressing the trip. | | `trips[].client_id` | The client that **owns** the trip — the target client when you submitted with a root-level `client_id`. | | `trips[].submitted_by_client_id` | The client whose credentials **submitted** the trip. | | `trips[].activity_ids` | IDs of the activities **this request** wrote under the trip, in payload order. | A `trips` entry reports the trip's **identity**, not the content you sent: it does not echo `trip_name`, `trip_status`, the dates, the amount or the cost center. Reading the trip back returns those five fields plus everything SQUAKE stored — see [Trip fields](/travel-data/retrieve-travel-data.md#trip-fields). *** ## Reading the data back The `trips` array is your handle on the stored records. With those IDs — or with your own `trip_reference` — you can retrieve the trip, list its activities with the calculations persisted for each, look up the audit log behind a calculation, or delete the trip again. Four things are only visible there, never in `items` or in the `trips` array: * **Additional methodologies.** `items` reports the primary methodology per activity; if your account is configured with more, each additional calculation is readable through the activity's ID. * **Audit references.** The ID of the audit log a calculation produced. * **The trip as stored.** A trip read returns its name, purpose, status, dates, booking provider, amount and cost center — useful for checking what SQUAKE actually kept of what you sent. * **The activity as stored.** An activity read returns its route (`origin`/`destination`), its `fuel_type` where the type has one, and the `traveler` it was booked for. Note that `activity_ids` lists only what this request wrote. Because re-using a `trip_reference` appends activities to an existing trip, that trip may hold more than the response shows — read the trip for the full list. → [Retrieve & Delete Travel Data](/travel-data/retrieve-travel-data.md) *** ## 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 ```bash 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. **Use activity-level monetary values for per-leg spend.** You can retain the overall booking cost on the trip and add `amount_in_cents` and `currency` to each activity. Activity values take precedence in activity-based reporting. `amount_base_currency` is not part of the public API. **`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.