Skip to main content
POST
https://api.dcycle.io
/
v1
/
business-travels
Create Business Travel
const options = {
  method: 'POST',
  headers: {
    Authorization: '<authorization>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({
    travel_date: '<string>',
    transport_type: '<string>',
    distance_km: 123,
    origin: '<string>',
    destination: '<string>',
    travel_number: 123,
    round_trip: true,
    vehicle_size: '<string>',
    fuel_type: '<string>',
    flight_type: '<string>',
    cabin_class: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/business-travels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "<string>",
  "travel_date": "<string>",
  "transport_type": "<string>",
  "distance_km": 123,
  "origin": {},
  "destination": {},
  "travel_number": 123,
  "round_trip": true,
  "status": "<string>",
  "co2e": 123,
  "created_at": {}
}

​
Create Business Travel

Create a new business travel record in your organization. The system will automatically calculate CO2e emissions based on the transport type and distance.
Distance Options: You can provide either distance_km directly OR provide origin and destination addresses to have the distance calculated automatically.

​
Request

​
Headers

​
Authorization
string
required
Bearer token for authenticationExample: Bearer sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
travel_date
date
required
Date of the business travelFormat: YYYY-MM-DDExample: "2024-12-01"
​
transport_type
string
required
Mode of transportAvailable values: car, metro, train, trolleybus, bus, motorbike, aircraft, ferry
​
distance_km
number
Distance traveled in kilometers (required if origin/destination not provided)Constraints: Must be positiveExample: 350.5
​
origin
string
Starting location address (required if distance_km not provided)Example: "Madrid, Spain"
​
destination
string
Ending location address (required if distance_km not provided)Example: "Barcelona, Spain"
​
travel_number
integer
default:"1"
Number of travelersConstraints: 1 to 1000Example: 2
​
round_trip
boolean
default:"false"
Whether this is a round tripExample: true
​
vehicle_size
string
Vehicle size (only for car or motorbike)Available values: small, medium, large, average
​
fuel_type
string
Fuel type (only for car or motorbike)Available values: petrol, diesel, cng, lpg, unknown, plug_in_hybrid_electric, battery_electric
​
flight_type
string
Flight type (only for aircraft)Available values: domestic, short_haul_international, long_haul_international
​
cabin_class
string
Cabin class (only for aircraft)Available values: economy, premium_economy, business, first, average

​
Response

Returns the created business travel object with calculated emissions.
​
id
string
Unique identifier (UUID) for the new record
​
travel_date
date
Date of the business travel
​
transport_type
string
Mode of transport
​
distance_km
number
Distance traveled in kilometers (calculated if origin/destination provided)
​
origin
string | null
Starting location address
​
destination
string | null
Ending location address
​
travel_number
integer
Number of travelers
​
round_trip
boolean
Whether this is a round trip
​
status
string
Initial status (usually pending until emissions are calculated)
​
co2e
number
Calculated CO2 equivalent emissions in kg
​
created_at
datetime
Timestamp when the record was created

​
Examples

​
Train Travel with Direct Distance

curl -X POST "https://api.dcycle.io/v1/business-travels" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "travel_date": "2024-12-01",
    "transport_type": "train",
    "distance_km": 621.5,
    "travel_number": 2,
    "round_trip": false
  }'

​
Flight with Origin/Destination (Auto-Calculate Distance)

curl -X POST "https://api.dcycle.io/v1/business-travels" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "travel_date": "2024-12-05",
    "transport_type": "aircraft",
    "origin": "Madrid, Spain",
    "destination": "London, UK",
    "flight_type": "short_haul_international",
    "cabin_class": "economy",
    "round_trip": true
  }'

​
Car Travel with Vehicle Details

curl -X POST "https://api.dcycle.io/v1/business-travels" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "travel_date": "2024-12-10",
    "transport_type": "car",
    "origin": "Madrid, Spain",
    "destination": "Valencia, Spain",
    "vehicle_size": "medium",
    "fuel_type": "diesel",
    "travel_number": 3
  }'

​
Successful Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "travel_date": "2024-12-01",
  "transport_type": "train",
  "distance_km": 621.5,
  "origin": null,
  "destination": null,
  "travel_number": 2,
  "round_trip": false,
  "vehicle_size": null,
  "fuel_type": null,
  "flight_type": null,
  "cabin_class": null,
  "status": "pending",
  "co2e": 0,
  "created_at": "2024-12-01T10:30:00Z",
  "updated_at": "2024-12-01T10:30:00Z"
}
The co2e value may initially be 0 with status pending. The emissions calculation happens asynchronously and the value will be updated shortly. Use the Get Business Travel endpoint to check the updated value.

​
Common Errors

​
401 Unauthorized

Cause: Missing or invalid API key 
{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

​
403 Forbidden - Limit Reached

Cause: Organization has reached maximum business travel records 
{
  "detail": "Business travel limit reached for this organization",
  "code": "LIMIT_REACHED"
}
Solution: Contact support to increase your organization’s limit or delete unused records.

​
422 Validation Error - Invalid Input

Cause: Must provide either distance_km OR origin+destination 
{
  "detail": [
    {
      "loc": ["body"],
      "msg": "You must provide either distance_km or both origin and destination",
      "type": "value_error"
    }
  ]
}

​
422 Validation Error - Invalid Travel Mode

Cause: Transport type not valid for the route (e.g., train across an ocean) 
{
  "detail": "Invalid travel mode between the specified places",
  "code": "VALIDATION_ERROR"
}
Solution: Choose a valid transport type for the origin/destination pair, or provide distance_km directly.

​
Validation Rules

  1. Distance Input: Provide either distance_km OR both origin and destination, not both
  2. Travel Number: Must be between 1 and 1000
  3. Vehicle Details: vehicle_size and fuel_type only apply to car or motorbike
  4. Flight Details: flight_type and cabin_class only apply to aircraft

List Business Travels

Retrieve all business travels

Get Business Travel

Get a specific business travel

Update Business Travel

Modify business travel details

Delete Business Travel

Remove a business travel record