# 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`. *** ## 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 | ✅ | Calculation methodology 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. | ### 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. | Methodologies: `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). | Methodologies: `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. | Methodologies: `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"`). | Methodologies: `ADEME`, `BASE-EMPREINTE`, `CO2-EMISSIEFACTOREN-NL`, `DEFRA`, `GREEN-TRAVEL-PLEDGE`, `SQUAKE`, `US-EPA`. *** ## Request example A complete business trip: outbound flight BER → LHR, hotel in London, taxi from Heathrow, and the return flight. ```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", "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", "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", "methodology": "DEFRA", "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": "jane.doe@example.com", "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": "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", "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", "type": "hotel", "methodology": { "carbon": { "quantity": 36.8, "unit": "kilogram" }, "meta": { "methodology": "DEFRA" } } }, { "carbon_quantity": 14.2, "carbon_unit": "kilogram", "external_reference": "ACTIVITY-CAR-001", "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", "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[].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. | | **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 **Always set `external_reference` on every activity.** It is the only way to reliably match response items to your input records, and it makes debugging much easier. **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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs-integration.squake.earth/travel-data/create-travel-data-items.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.