Business Travel Tools

Manage Scope 3 business travel records — flights, train journeys, bus trips, and car travel with origin/destination, distance, and CO₂e emissions.

Business travel records can be large (origin/destination details, geocodes). The default page size is 10 — keep size ≤ 20 and use pagination to avoid oversized responses.

`list_business_travels`

List business travel records with optional filters. Parameters:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID
`transport_type`	string	No	—	Filter by transport mode (see below)
`start_date`	string	No	—	Filter trips from this date (YYYY-MM-DD)
`end_date`	string	No	—	Filter trips until this date (YYYY-MM-DD)
`page`	integer	No	1	Page number
`size`	integer	No	10	Results per page (keep ≤ 20)

Transport Types

Value	Description
`plane`	Air travel
`train`	Rail travel
`bus`	Bus travel
`car`	Car travel

Example response:

{
  "items": [
    {
      "id": "5822a93c-...",
      "transport_type": "train",
      "distance_km": 25.0,
      "fuel_type": "electric",
      "travel_type": "round",
      "travel_number": 1,
      "start_date": "2025-11-01",
      "end_date": "2025-11-26",
      "co2e": 3.56,
      "status": "active"
    }
  ],
  "total": 2349,
  "page": 1,
  "size": 10,
  "pages": 235
}

Key response fields:

Field	Description
`transport_type`	Mode of transport used
`distance_km`	Total distance in kilometers
`fuel_type`	Fuel/energy type (e.g. `electric`, `diesel`, `jet_fuel`)
`travel_type`	`one_way` or `round` trip
`travel_number`	Number of trips with this configuration
`co2e`	Calculated CO₂e emissions in kg

Example prompts:

"Show all business travel by plane"
"What were the highest-emission trips last year?"
"Show train travel records for Q1 2025"
"List business trips from Q4 2024"
"How much CO₂ did our flights generate in 2024?"

Write Operations

`create_business_travel`

Create a business travel record for Scope 3 employee travel emissions. CO₂e is calculated asynchronously after creation — the response will initially show co2e as null. Distance can be specified in two ways:

Provide origin + destination (addresses or city names) — distance is calculated automatically via Google Maps (or geodesic for aircraft).
Provide distance_km directly when the distance is already known.

At least one of these must be given. Parameters:

Parameter	Type	Required	Default	Description
`transport_type`	string	Yes	—	Mode of transport: `car`, `metro`, `train`, `trolleybus`, `bus`, `motorbike`, `aircraft`, `ferry`
`start_date`	string	Yes	—	Travel start date (`YYYY-MM-DD`)
`end_date`	string	Yes	—	Travel end date (`YYYY-MM-DD`), must be on or after `start_date`
`origin`	string	No	—	Origin address or city (e.g. `"Madrid, Spain"`)
`destination`	string	No	—	Destination address or city (e.g. `"Barcelona, Spain"`)
`distance_km`	number	No	—	Distance in kilometers (use instead of origin/destination if known)
`vehicle_size`	string	No	—	Car size: `small`, `medium`, `large`. Required when `transport_type=car`
`fuel_type`	string	No	—	Car fuel: `diesel`, `natural_gas`, `petrol`, `lpg`, `electric`, `hybrid`, `not_fuel_based`, `do_not_know`. Required when `transport_type=car`
`renewable_energy`	string	No	—	Renewable energy used: `yes`, `no`, `do_not_know`
`travel_type`	string	No	`one_way`	`round` (round trip) or `one_way`
`travel_number`	integer	No	1	Number of trips in the period (max 10,000)
`passenger_number`	integer	No	1	Number of passengers
`name`	string	No	—	Traveler or trip name for identification
`organization_id`	string	No	default org	Organization UUID

When transport_type is car, you must also provide vehicle_size and fuel_type. These fields are ignored for other transport types.

CO₂e emissions are calculated in the background after creation. The initial response will show co2e: null. Call list_business_travels after a few seconds to see the calculated value.

Example response:

{
  "id": "5822a93c-...",
  "transport_type": "train",
  "origin": "Madrid, Spain",
  "destination": "Barcelona, Spain",
  "distance_km": 621.0,
  "start_date": "2025-03-01",
  "end_date": "2025-03-01",
  "travel_type": "one_way",
  "travel_number": 1,
  "passenger_number": 1,
  "status": "active",
  "co2e": null,
  "created_at": "2025-03-01T10:30:00Z"
}

Example prompts:

"Log a train trip from Madrid to Barcelona on March 1st"
"Create a round-trip flight from London to New York, 2 passengers"
"Add a car trip, 150 km, diesel medium car"
"Record 5 daily bus commutes of 20 km each for January"

Common errors:

Error	Cause
422: “Either distance_km or origin+destination must be provided”	Neither distance nor locations were given
422: “vehicle_size is required for car transport”	Missing `vehicle_size` when `transport_type=car`
422: “fuel_type is required for car transport”	Missing `fuel_type` when `transport_type=car`
422: “end_date must be on or after start_date”	`end_date` is before `start_date`

`update_business_travel`

Update an existing business travel record. Only the fields you provide are changed. CO₂e is recalculated after update.

The API requires either distance_km or origin + destination to remain valid after update. If changing the route, provide either a new origin/destination pair or a new distance_km.

Parameters:

Parameter	Type	Required	Default	Description
`business_travel_id`	string	Yes	—	UUID of the record. Use `list_business_travels` to find it
`transport_type`	string	No	—	`car`, `metro`, `train`, `trolleybus`, `bus`, `motorbike`, `aircraft`, `ferry`
`start_date`	string	No	—	New start date (`YYYY-MM-DD`)
`end_date`	string	No	—	New end date (`YYYY-MM-DD`)
`origin`	string	No	—	New origin address
`destination`	string	No	—	New destination address
`distance_km`	number	No	—	New distance in km (> 0)
`vehicle_size`	string	No	—	`small`, `medium`, `large` (for cars)
`fuel_type`	string	No	—	`diesel`, `petrol`, `electric`, `hybrid`, etc. (for cars)
`renewable_energy`	string	No	—	`yes`, `no`, `do_not_know`
`travel_type`	string	No	—	`round` or `one_way`
`travel_number`	integer	No	—	Number of trips (1–10000)
`passenger_number`	integer	No	—	Number of passengers (>= 1)
`name`	string	No	—	Traveler or trip name
`organization_id`	string	No	default org	Organization UUID

Example prompts:

"Change business travel abc-123 to 250 km"
"Update the trip to use aircraft instead of train"
"Fix the destination of travel xyz to 'Barcelona, Spain'"

Common errors:

Error	Cause
404: “Business travel not found”	Invalid business travel UUID
422: “Either distance_km or origin+destination must be provided”	Update would leave the record without a valid distance

Workflows

Querying travel records

List travel records — list_business_travels filtered by transport type or date range
View hotel stays — list_hotel_stays for accommodation linked to business trips
View emissions — get_greenhouse_gas_emissions with category=travels for aggregated totals

Logging a new business trip

Create the travel record — create_business_travel with transport type, dates, and origin/destination or distance
Verify — list_business_travels after a few seconds to confirm creation and CO₂e calculation
Log accommodation — if applicable, create a hotel stay record for the same trip

API: Create Business Travel

REST API endpoint for business travel creation

API: List Business Travels

REST API equivalent with additional filters

Hotel Stays

Accommodation records for business trips

Emissions

Aggregated Scope 3 travel emissions

Getting Started

Tools Reference

Reference Data

Business Travel Tools

Business Travel Tools

`list_business_travels`

Transport Types

Write Operations

`create_business_travel`

`update_business_travel`

Workflows

Querying travel records

Logging a new business trip

API: Create Business Travel

API: List Business Travels

Hotel Stays

Emissions

​Business Travel Tools

​list_business_travels

​Transport Types

​Write Operations

​create_business_travel

​update_business_travel

​Workflows

​Querying travel records

​Logging a new business trip

​Related

API: Create Business Travel

API: List Business Travels

Hotel Stays

Emissions

Business Travel Tools

`list_business_travels`

Transport Types

Write Operations

`create_business_travel`

`update_business_travel`

Workflows

Querying travel records

Logging a new business trip

Related