Employees API

The Employees API allows you to create, retrieve, update, and delete employee records for tracking commuting patterns and calculating Scope 3 Category 7 (Employee Commuting) emissions. Each employee can have multiple commuting periods with detailed transport information for accurate CO2e calculations.

GHG Protocol Scope 3 Category 7Employee commuting covers emissions from transportation of employees between their homes and worksites. This API helps you collect and manage the data needed for accurate Category 7 reporting.

Key Features

Employee Management: Create and manage employee records with contact information
Commuting Periods: Track multiple commuting patterns per employee over time
Transport Modes: Support for cars, public transit, cycling, walking, and remote work
CO2e Calculation: Automatic emissions calculation based on distance, transport mode, and frequency
Survey Integration: Send surveys to employees to collect commuting data
Bulk Upload: Import employee data via CSV for large organizations
Pagination Support: Efficiently retrieve large employee lists

Authentication

All endpoints require authentication using an API key included in the x-api-key header.

Headers

All requests must include:

string

required

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

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

Available Endpoints

Employees

List Employees

Retrieve all employees with filtering and pagination

Get Employee

Get a specific employee by ID

Create Employee

Add a new employee to your organization

Update Employee

Modify employee details

Delete Employee

Remove an employee from your organization

Survey Templates

List Templates

Get all survey templates for your organization

Create Template

Create a customizable survey template

Clone Template

Duplicate an existing template

Set Default

Set a template as the organization default

Commuting Periods

List Commuting Periods

Get commuting periods for an employee

Create Commuting Period

Add a new commuting period

Update Commuting Period

Modify commuting period details

Delete Commuting Period

Remove a commuting period

Data Model

Employee Object

The employee object contains basic employee information:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John Smith",
  "email": "john.smith@company.com",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "situation": "active",
  "status": "uploaded",
  "periods": [...],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Employee Attributes

Field	Type	Description
`id`	UUID	Unique identifier for the employee
`name`	string	Employee’s full name
`email`	string	Employee’s email address
`organization_id`	UUID	Organization the employee belongs to
`situation`	string	Employment status: `active`, `inactive`, `terminated`
`status`	string	Data status: `uploaded`, `loading`
`periods`	array	List of commuting periods (when requested)
`created_at`	datetime	When the employee was created
`updated_at`	datetime	When the employee was last updated

Commuting Period Object

Commuting periods track how an employee commutes during a specific time range:

{
  "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": "car",
  "vehicle_size": "medium",
  "fuel_type": "petrol",
  "total_km": 15,
  "weekly_travels": [0, 1, 2, 3, 4],
  "daily_trips": 1,
  "carpool": false,
  "situation": "active",
  "co2e": 1245.5,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Transport Types

Transport Type	Description	Requires Fuel Type	Requires Vehicle Size
`car`	Personal vehicle	Yes	Yes
`bus`	Public bus	Yes	No
`train`	Commuter rail	Optional	No
`metro`	Urban subway	Optional	No
`tram`	Light rail	No	No
`motorbike`	Motorcycle	Yes	No
`bicycle`	Cycling (including e-bike)	Optional	No
`walking`	Walking	No	No
`telecommuting`	Remote work	No	No
`electric_kick_scooter`	Electric scooter	No	No
`trolleybus`	Electric bus	Optional	No

Fuel Types

Fuel Type	Description	Applicable Transport
`petrol`	Gasoline	car, motorbike, bus
`diesel`	Diesel fuel	car, motorbike, bus
`electric`	Electric vehicle	car, motorbike, metro, train, bicycle
`hybrid`	Hybrid vehicle	car
`lpg`	Liquefied petroleum gas	car, bus
`natural_gas`	Natural gas	car, bus
`not_fuel_based`	No fuel (human powered)	bicycle
`do_not_know`	Unknown fuel type	Any motorized

Vehicle Sizes (Cars Only)

Size	Description
`small`	Compact cars (e.g., city cars, superminis)
`medium`	Mid-size sedans and hatchbacks
`large`	SUVs, large sedans, minivans

Weekly Travels

The weekly_travels field is an array of integers representing which days the employee commutes:

Value	Day
`0`	Monday
`1`	Tuesday
`2`	Wednesday
`3`	Thursday
`4`	Friday
`5`	Saturday
`6`	Sunday

Examples:

[0, 1, 2, 3, 4] - Monday to Friday (5-day week)
[1, 3] - Tuesday and Thursday only (hybrid)
[] - Fully remote (telecommuting)

CO2e Calculation

Emissions are calculated using the formula:

CO2e = Distance (km) × Working Days × Daily Trips × Emission Factor × 2 (round trip)

Distance: One-way distance from home to work (total_km)
Working Days: Calculated from weekly_travels and date range
Daily Trips: Number of round trips per day
Emission Factor: Based on transport type, fuel, and vehicle size (from Ecoinvent database)
Carpool Factor: If carpool: true, emissions are divided by 3

Workflow

Tracking Employee Commuting

Create Employee: Add employee with name or email
Create Commuting Period: Define the commuting pattern for a date range
Query Emissions: Retrieve employee with periods to see calculated CO2e

Using Surveys

Upload Employees via CSV: Bulk create employees with email addresses
Send Survey: Use the resend-survey endpoint to collect commuting data
Review Results: Employees fill in the survey, creating commuting periods automatically

Error Handling

Common HTTP Status Codes

Status	Meaning	Solution
200	Success	-
201	Created	-
204	No Content (delete successful)	-
400	Bad Request	Check request parameters and format
401	Unauthorized	Verify API key
404	Not Found	Check resource ID or organization
422	Validation Error	Review error details in response
500	Server Error	Contact support if persists

Error Response Format

{
  "detail": "Error description",
  "code": "ERROR_CODE"
}

Use Cases

Track Office Commuting

Monitor CO2e emissions for employees commuting to the office:

import requests

# Create employee
employee = requests.post(
    "https://api.dcycle.io/v1/employees",
    headers=headers,
    json={
        "name": "John Smith",
        "email": "john@company.com",
        "situation": "active",
        "status": "uploaded"
    }
).json()

# Add commuting period
period = requests.post(
    "https://api.dcycle.io/v1/employee-historic",
    headers=headers,
    json={
        "employee_id": employee["id"],
        "start_date": "2024-01-01",
        "end_date": "2024-12-31",
        "commuting_type": "in_itinere",
        "transport_type": "car",
        "vehicle_size": "medium",
        "fuel_type": "petrol",
        "total_km": 15,
        "weekly_travels": [0, 1, 2, 3, 4],
        "daily_trips": 1,
        "carpool": False,
        "situation": "active",
        "response_medium": "manual"
    }
).json()

print(f"Annual CO2e: {period['co2e']} kg")

Calculate Category 7 Totals

Sum up all employee commuting emissions:

# Get all employees with periods
response = requests.get(
    "https://api.dcycle.io/v1/employees",
    headers=headers,
    params={"size": 100}
).json()

total_co2e = 0
for employee in response["items"]:
    for period in employee.get("periods", []):
        total_co2e += period.get("co2e", 0)

print(f"Scope 3 Category 7 Total: {total_co2e} kg CO2e")

Employee Commuting Guide

Complete tutorial for tracking Scope 3 Category 7 emissions

GHG Protocol Tutorial

Learn about GHG Protocol and emissions tracking

Authentication Guide

Learn how to authenticate API requests

Vehicles API

Track company fleet emissions (Scope 1)

MCP Tools

Query employee data from AI assistants via MCP

CSV Upload List Employees

​Employees API

​Key Features

​Authentication

​Headers

​Available Endpoints

​Employees

List Employees

Get Employee

Create Employee

Update Employee

Delete Employee

​Survey Templates

List Templates

Create Template

Clone Template

Set Default

​Commuting Periods

List Commuting Periods

Create Commuting Period

Update Commuting Period

Delete Commuting Period

​Data Model

​Employee Object

​Employee Attributes

​Commuting Period Object

​Transport Types

​Fuel Types

​Vehicle Sizes (Cars Only)

​Weekly Travels

​CO2e Calculation

​Workflow

​Tracking Employee Commuting

​Using Surveys

​Error Handling

​Common HTTP Status Codes

​Error Response Format

​Use Cases

​Track Office Commuting

​Calculate Category 7 Totals

​Related Documentation

Employee Commuting Guide

GHG Protocol Tutorial

Authentication Guide

Vehicles API

MCP Tools

Employees API

Key Features

Authentication

Headers

Available Endpoints

Employees

Survey Templates

Commuting Periods

Data Model

Employee Object

Employee Attributes

Commuting Period Object

Transport Types

Fuel Types

Vehicle Sizes (Cars Only)

Weekly Travels

CO2e Calculation

Workflow

Tracking Employee Commuting

Using Surveys

Error Handling

Common HTTP Status Codes

Error Response Format

Use Cases

Track Office Commuting

Calculate Category 7 Totals

Related Documentation