Skip to main content
PATCH
/
v1
/
employee-historic
/
{employee_historic_id}
Update Commuting Period
const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    start_date: '<string>',
    end_date: '<string>',
    commuting_type: '<string>',
    transport_type: '<string>',
    vehicle_size: '<string>',
    fuel_type: '<string>',
    renewable_energy: '<string>',
    carpool: true,
    total_km: 123,
    weekly_travels: {},
    daily_trips: 123,
    situation: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/employee-historic/{employee_historic_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

​
Update Commuting Period

Update an existing commuting period. You can modify transport details, dates, or other attributes. The CO2e will be recalculated automatically.
Transport Field Groups: When updating transport-related fields (transport_type, vehicle_size, fuel_type, renewable_energy, carpool), you must provide all five fields together.

​
Request

​
Headers

​
x-api-key
string
required
Your API key for authentication
​
x-organization-id
string
required
Your organization UUID

​
Path Parameters

​
employee_historic_id
string
required
The unique identifier (UUID) of the commuting periodExample: 660e8400-e29b-41d4-a716-446655440000

​
Body Parameters

All parameters are optional. Only include fields you want to update.
​
start_date
date
Period start date. Must provide end_date as well.
​
end_date
date
Period end date. Must provide start_date as well.
​
commuting_type
string
Type: in_itinere or in_labore
​
transport_type
string
Mode of transport. When provided, must include all transport fields.
​
vehicle_size
string
Vehicle size for cars. Part of transport field group.
​
fuel_type
string
Fuel type. Part of transport field group.
​
renewable_energy
string
Renewable energy source. Part of transport field group.
​
carpool
boolean
Carpooling status. Part of transport field group.
​
total_km
number
One-way distance in kilometers.
​
weekly_travels
array[integer]
Days of week for commuting.
​
daily_trips
integer
Round trips per day.
​
situation
string
Period status: active, inactive, terminated

​
Response

Returns the updated commuting period with recalculated CO2e.

​
Example

curl -X PATCH "https://api.dcycle.io/v1/employee-historic/660e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "transport_type": "train",
    "vehicle_size": null,
    "fuel_type": "electric",
    "renewable_energy": "yes",
    "carpool": false
  }'

​
Successful Response

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "employee_id": "550e8400-e29b-41d4-a716-446655440000",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "commuting_type": "in_itinere",
  "transport_type": "train",
  "vehicle_size": null,
  "fuel_type": "electric",
  "renewable_energy": "yes",
  "total_km": 15,
  "weekly_travels": [0, 1, 2, 3, 4],
  "daily_trips": 1,
  "carpool": false,
  "situation": "active",
  "origin": null,
  "destination": null,
  "response_medium": "manual",
  "co2e": 312.4,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-11-24T14:45:00Z"
}

​
Common Errors

​
422 Validation Error

Cause: Partial transport field update 
{
  "detail": [
    {
      "loc": ["body"],
      "msg": "When providing any transport field, all fields must be provided. Missing: vehicle_size, carpool",
      "type": "value_error"
    }
  ]
}
Solution: Include all transport fields: transport_type, vehicle_size, fuel_type, renewable_energy, carpool.

​
Use Cases

​
Update Distance

# Just update the distance
payload = {"total_km": 20}

​
Change Working Days

# Switch to hybrid (3 days/week)
payload = {"weekly_travels": [1, 2, 3]}

​
Update Date Range

# Both dates required together
payload = {
    "start_date": "2024-07-01",
    "end_date": "2024-12-31"
}

​
Switch Transport Mode

# All transport fields required together
payload = {
    "transport_type": "bicycle",
    "vehicle_size": None,
    "fuel_type": "not_fuel_based",
    "renewable_energy": None,
    "carpool": False
}

Create Period

Add new period

Delete Period

Remove period