Create Business Travel

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({
    transport_type: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    distance_km: 123,
    origin: '<string>',
    destination: '<string>',
    name: '<string>',
    email: '<string>',
    travel_type: '<string>',
    travel_number: 123,
    passenger_number: 123,
    vehicle_size: '<string>',
    fuel_type: '<string>',
    renewable_energy: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/business-travels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/business-travels"

payload = {
    "transport_type": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "distance_km": 123,
    "origin": "<string>",
    "destination": "<string>",
    "name": "<string>",
    "email": "<string>",
    "travel_type": "<string>",
    "travel_number": 123,
    "passenger_number": 123,
    "vehicle_size": "<string>",
    "fuel_type": "<string>",
    "renewable_energy": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/business-travels \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "transport_type": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "distance_km": 123,
  "origin": "<string>",
  "destination": "<string>",
  "name": "<string>",
  "email": "<string>",
  "travel_type": "<string>",
  "travel_number": 123,
  "passenger_number": 123,
  "vehicle_size": "<string>",
  "fuel_type": "<string>",
  "renewable_energy": "<string>"
}
'

{
  "id": "<string>",
  "organization_id": "<string>",
  "name": {},
  "email": {},
  "transport_type": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "distance_km": {},
  "distance_source": {},
  "origin": {},
  "destination": {},
  "origin_geocode": {},
  "destination_geocode": {},
  "travel_type": "<string>",
  "travel_number": 123,
  "passenger_number": 123,
  "vehicle_size": {},
  "fuel_type": {},
  "renewable_energy": {},
  "status": "<string>",
  "source": "<string>",
  "co2e": {},
  "file_id": {},
  "file_name": {},
  "uploaded_by": {},
  "created_at": {},
  "updated_at": {}
}

POST

business-travels

Create Business Travel

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({
    transport_type: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    distance_km: 123,
    origin: '<string>',
    destination: '<string>',
    name: '<string>',
    email: '<string>',
    travel_type: '<string>',
    travel_number: 123,
    passenger_number: 123,
    vehicle_size: '<string>',
    fuel_type: '<string>',
    renewable_energy: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/business-travels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/business-travels"

payload = {
    "transport_type": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "distance_km": 123,
    "origin": "<string>",
    "destination": "<string>",
    "name": "<string>",
    "email": "<string>",
    "travel_type": "<string>",
    "travel_number": 123,
    "passenger_number": 123,
    "vehicle_size": "<string>",
    "fuel_type": "<string>",
    "renewable_energy": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/business-travels \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "transport_type": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "distance_km": 123,
  "origin": "<string>",
  "destination": "<string>",
  "name": "<string>",
  "email": "<string>",
  "travel_type": "<string>",
  "travel_number": 123,
  "passenger_number": 123,
  "vehicle_size": "<string>",
  "fuel_type": "<string>",
  "renewable_energy": "<string>"
}
'

{
  "id": "<string>",
  "organization_id": "<string>",
  "name": {},
  "email": {},
  "transport_type": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "distance_km": {},
  "distance_source": {},
  "origin": {},
  "destination": {},
  "origin_geocode": {},
  "destination_geocode": {},
  "travel_type": "<string>",
  "travel_number": 123,
  "passenger_number": 123,
  "vehicle_size": {},
  "fuel_type": {},
  "renewable_energy": {},
  "status": "<string>",
  "source": "<string>",
  "co2e": {},
  "file_id": {},
  "file_name": {},
  "uploaded_by": {},
  "created_at": {},
  "updated_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

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

string

required

Must be application/json

Body Parameters

string

required

Mode of transportAvailable values: car, metro, train, trolleybus, bus, motorbike, aircraft, ferry

date

required

Start date of the business travelFormat: YYYY-MM-DDExample: "2024-12-01"

date

required

End date of the business travel. Must be on or after start_dateFormat: YYYY-MM-DDExample: "2024-12-01"

number

Distance traveled in kilometers (required if origin/destination not provided)Constraints: Must be greater than 0Example: 350.5

string

Starting location address (required if distance_km not provided)Constraints: Max 500 charactersExample: "Madrid, Spain"

string

Ending location address (required if distance_km not provided). Cannot be the same as origin unless distance_km is also provided.Constraints: Max 500 charactersExample: "Barcelona, Spain"

string

Optional label for this travel recordConstraints: Max 255 charactersExample: "Q4 Sales Conference"

string

Email of the travelerExample: "j.garcia@example.com"

string

default:"one_way"

Whether this is a one-way or round tripAvailable values: one_way, round

integer

default:"1"

Number of tripsConstraints: 1 to 10,000 (further limited by date range — max 100 per day)Example: 2

integer

default:"1"

Number of passengers per tripConstraints: Must be at least 1Example: 3

string

Vehicle size. Required when transport_type is car, not allowed for other types.Available values: small, medium, large

string

Fuel type. Required when transport_type is car, not allowed for other types.Available values: diesel, petrol, natural_gas, lpg, electric, hybrid, not_fuel_based, do_not_know

string

Whether the vehicle uses renewable energyAvailable values: yes, no, do_not_know

Response

Returns the created business travel object with HTTP status 201 Created.

The co2e value may initially be 0 with status: "pending". Emissions are calculated asynchronously and the value will be updated shortly. Use the Get Business Travel endpoint to check the updated value.

string

Unique identifier (UUID) for the new record

string

Organization UUID

string | null

Travel record label

string | null

Traveler email

string

Mode of transport

date

Start date of travel

date

End date of travel

number | null

Distance in km (calculated if origin/destination provided)

string | null

How the distance was obtained: manual (provided directly), geodesic (great-circle for aircraft), or google_maps (other transport types with origin/destination)

string | null

Starting location address

string | null

Ending location address

object | null

Geocoded origin location resolved from the origin address

Field	Type	Description
`country_code`	string	ISO-2 country code
`place_id`	string	Place identifier
`address_formatted`	string	Full formatted address
`latitude`	number	Latitude coordinate
`longitude`	number	Longitude coordinate

object | null

Geocoded destination location (same structure as origin_geocode)

string

Trip type: one_way or round

integer

Number of trips

integer

Number of passengers per trip

string | null

Vehicle size (car only)

string | null

Fuel type (car only)

string | null

Renewable energy usage

string

Record status: pending immediately after creation, active once calculation completes, error if calculation failed

string

Record source: api for records created via this endpoint

number | null

Calculated CO2 equivalent emissions in kg. null or 0 while calculation is pending

string | null

File UUID if created via bulk upload (always null for API-created records)

string | null

Name of the source file, if created via bulk upload

object | null

The authenticated user who created this record

datetime

Creation timestamp

datetime | null

Last update timestamp

Example

Train Travel with Direct Distance

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

import requests
import os

response = requests.post(
    "https://api.dcycle.io/v1/business-travels",
    headers={
        "x-api-key": os.getenv("DCYCLE_API_KEY"),
        "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    },
    json={
        "transport_type": "train",
        "start_date": "2024-12-01",
        "end_date": "2024-12-01",
        "distance_km": 621.5,
        "travel_number": 2,
        "travel_type": "one_way",
    },
)

travel = response.json()
print(f"Created travel: {travel['id']}")
print(f"Status: {travel['status']}")

const axios = require('axios');

axios.post(
  'https://api.dcycle.io/v1/business-travels',
  {
    transport_type: 'train',
    start_date: '2024-12-01',
    end_date: '2024-12-01',
    distance_km: 621.5,
    travel_number: 2,
    travel_type: 'one_way',
  },
  {
    headers: {
      'x-api-key': process.env.DCYCLE_API_KEY,
      'x-organization-id': process.env.DCYCLE_ORG_ID,
    },
  }
)
.then(({ data: travel }) => {
  console.log(`Created travel: ${travel.id}`);
  console.log(`Status: ${travel.status}`);
})
.catch(error => console.error(error));

Flight with Origin/Destination

curl -X POST "https://api.dcycle.io/v1/business-travels" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "transport_type": "aircraft",
    "start_date": "2024-12-05",
    "end_date": "2024-12-05",
    "origin": "Madrid, Spain",
    "destination": "London, UK",
    "travel_type": "round",
    "passenger_number": 1
  }'

response = requests.post(
    "https://api.dcycle.io/v1/business-travels",
    headers={
        "x-api-key": os.getenv("DCYCLE_API_KEY"),
        "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    },
    json={
        "transport_type": "aircraft",
        "start_date": "2024-12-05",
        "end_date": "2024-12-05",
        "origin": "Madrid, Spain",
        "destination": "London, UK",
        "travel_type": "round",
        "passenger_number": 1,
    },
)

travel = response.json()
print(f"Distance: {travel['distance_km']} km ({travel['distance_source']})")
print(f"Status: {travel['status']}")

Car Travel with Vehicle Details

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

response = requests.post(
    "https://api.dcycle.io/v1/business-travels",
    headers={
        "x-api-key": os.getenv("DCYCLE_API_KEY"),
        "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    },
    json={
        "transport_type": "car",
        "start_date": "2024-12-10",
        "end_date": "2024-12-10",
        "origin": "Madrid, Spain",
        "destination": "Valencia, Spain",
        "vehicle_size": "medium",
        "fuel_type": "diesel",
        "travel_number": 3,
    },
)

Successful Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "name": null,
  "email": null,
  "transport_type": "train",
  "start_date": "2024-12-01",
  "end_date": "2024-12-01",
  "distance_km": 621.5,
  "distance_source": "manual",
  "origin": null,
  "destination": null,
  "origin_geocode": null,
  "destination_geocode": null,
  "travel_type": "one_way",
  "travel_number": 2,
  "passenger_number": 1,
  "vehicle_size": null,
  "fuel_type": null,
  "renewable_energy": null,
  "status": "pending",
  "source": "api",
  "co2e": 0,
  "file_id": null,
  "file_name": null,
  "uploaded_by": {
    "id": "user-123",
    "first_name": "Maria",
    "last_name": "García",
    "profile_img_url": null
  },
  "created_at": "2024-12-01T10:30:00Z",
  "updated_at": "2024-12-01T10:30:00Z"
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

422 Unprocessable Entity

Cause: Missing required fields — must provide either distance_km OR both origin and destination

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "Either distance_km or origin+destination must be provided",
      "type": "value_error"
    }
  ]
}

Cause: Missing vehicle_size or fuel_type when transport_type is car

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "vehicle_size is required for car transport",
      "type": "value_error"
    }
  ]
}

Cause: end_date is before start_date

{
  "detail": [
    {
      "loc": ["body", "end_date"],
      "msg": "end_date must be on or after start_date",
      "type": "value_error"
    }
  ]
}

Cause: Unknown field sent in request body (this endpoint rejects extra fields)

{
  "detail": [
    {
      "loc": ["body", "round_trip"],
      "msg": "extra fields not permitted",
      "type": "value_error.extra"
    }
  ]
}

Validation Rules

Distance Input: Provide either distance_km OR both origin and destination
Date Range: end_date must be on or after start_date
Travel Number: 1 to 10,000, further limited to max 100 per day in the date range
Car Transport: vehicle_size and fuel_type are required when transport_type is car
Vehicle Size Restriction: vehicle_size is only allowed for car transport
Extra Fields: This endpoint rejects any fields not listed above (e.g. flight_type, cabin_class, round_trip)

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

Version History Update Business Travel

​Create Business Travel

​Request

​Headers

​Body Parameters

​Response

​Example

​Train Travel with Direct Distance

​Flight with Origin/Destination

​Car Travel with Vehicle Details

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​Validation Rules

​Related Endpoints

List Business Travels

Get Business Travel

Update Business Travel

Delete Business Travel

Create Business Travel

Request

Headers

Body Parameters

Response

Example

Train Travel with Direct Distance

Flight with Origin/Destination

Car Travel with Vehicle Details

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

Validation Rules

Related Endpoints