List Employees

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

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

import requests

url = "https://api.dcycle.io/v1/employees"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": {
    "id": "<string>",
    "name": {},
    "email": {},
    "organization_id": "<string>",
    "situation": {},
    "status": "<string>",
    "periods": {
      "id": "<string>",
      "employee_id": "<string>",
      "start_date": "<string>",
      "end_date": {},
      "transport_type": {},
      "vehicle_size": {},
      "fuel_type": {},
      "renewable_energy": {},
      "carpool": true,
      "total_km": {},
      "weekly_travels": {},
      "weekly_telecommuting": {},
      "daily_trips": 123,
      "hours_worked_per_day": {},
      "total_commuting_days": {},
      "total_telecommuting_days": {},
      "situation": {},
      "commuting_type": "<string>",
      "response_medium": {},
      "origin": {},
      "destination": {},
      "co2e": {},
      "file_id": {},
      "file_name": {},
      "created_at": {},
      "updated_at": {}
    },
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123
}

GET

employees

List Employees

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

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

import requests

url = "https://api.dcycle.io/v1/employees"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": {
    "id": "<string>",
    "name": {},
    "email": {},
    "organization_id": "<string>",
    "situation": {},
    "status": "<string>",
    "periods": {
      "id": "<string>",
      "employee_id": "<string>",
      "start_date": "<string>",
      "end_date": {},
      "transport_type": {},
      "vehicle_size": {},
      "fuel_type": {},
      "renewable_energy": {},
      "carpool": true,
      "total_km": {},
      "weekly_travels": {},
      "weekly_telecommuting": {},
      "daily_trips": 123,
      "hours_worked_per_day": {},
      "total_commuting_days": {},
      "total_telecommuting_days": {},
      "situation": {},
      "commuting_type": "<string>",
      "response_medium": {},
      "origin": {},
      "destination": {},
      "co2e": {},
      "file_id": {},
      "file_name": {},
      "created_at": {},
      "updated_at": {}
    },
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123
}

List Employees

Retrieve a paginated list of employees in your organization with support for filtering and searching.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Query Parameters

string

Search employees by name or email (partial match)Example: "john"

array[string]

Filter by employment situationAvailable values: active, inactive, terminatedExample: situation=active

array[string]

Filter by data statusAvailable values: uploaded, loadingExample: status=uploaded

array[string]

Filter by transport type used in commuting periodsAvailable values: car, bus, train, metro, tram, motorbike, bicycle, walking, telecommuting, electric_kick_scooter, trolleybusExample: transport_type=car&transport_type=bus

array[string]

Filter by how commuting data was collectedAvailable values: manual, qr, form, file_uploadExample: response_medium=form

integer

default:"1"

Page number for paginationExample: 2

integer

default:"50"

Number of items per page (max 100)Example: 50

Response

array[object]

Array of employee objects

Show Employee Object

string

Unique identifier (UUID)

string | null

Employee’s full name

string | null

Employee’s email address

string

Organization UUID

string | null

Employment status: active, inactive, or terminated

string

Data status: uploaded or loading

array[object] | null

List of commuting periods with CO2e calculations

Show Commuting Period Object

string

UUID

string

Parent employee UUID

date

Period start date

date | null

Period end date

string | null

Mode of transport: car, bus, train, metro, tram, motorbike, bicycle, walking, telecommuting, electric_kick_scooter, trolleybus

string | null

Vehicle size: small, medium, large

string | null

Fuel type: petrol, diesel, electric, hybrid, lpg, natural_gas, not_fuel_based, do_not_know

string | null

Renewable energy: yes, no, do_not_know

boolean

Whether the employee carpools

number | null

One-way commute distance in km

array[integer] | null

Days of the week the employee commutes (0=Monday, 4=Friday)

array[integer] | null

Days of the week the employee telecommutes

integer

Number of one-way trips per commuting day

integer | null

Hours worked per day

integer | null

Total commuting days in the period

integer | null

Total telecommuting days in the period

string | null

Period-level situation: active, inactive, terminated

string

Commuting classification: in_itinere (home→office) or in_labore (work-related travel)

string | null

How data was collected: manual, qr, form, file_upload

string | null

Origin address

string | null

Destination address

number | null

Calculated CO2e emissions in kg

string | null

Source file UUID

string | null

Source file name

datetime

Record creation timestamp

datetime | null

Last update timestamp

datetime

Timestamp when the employee was created

datetime | null

Timestamp when the employee was last updated

integer

Total number of employees matching the filter

integer

Current page number

integer

Number of items per page

Example

curl -X GET "https://api.dcycle.io/v1/employees?page=1&size=50&situation=active" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id
}

params = {
    "page": 1,
    "size": 50,
    "situation": ["active"]
}

response = requests.get(
    "https://api.dcycle.io/v1/employees",
    headers=headers,
    params=params
)

result = response.json()
for employee in result["items"]:
    print(f"{employee['name'] or employee['email']}")
    for period in employee.get("periods", []):
        print(f"  - {period['transport_type']}: {period['co2e']} kg CO2e")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId
};

const params = {
  page: 1,
  size: 50,
  situation: ['active']
};

axios.get(
  'https://api.dcycle.io/v1/employees',
  { headers, params }
)
.then(response => {
  response.data.items.forEach(employee => {
    console.log(`${employee.name || employee.email}`);
    (employee.periods || []).forEach(period => {
      console.log(`  - ${period.transport_type}: ${period.co2e} kg CO2e`);
    });
  });
})
.catch(error => console.error(error));

Successful Response

{
  "items": [
    {
      "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": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440000",
          "employee_id": "550e8400-e29b-41d4-a716-446655440000",
          "start_date": "2024-01-01",
          "end_date": "2024-12-31",
          "transport_type": "car",
          "vehicle_size": "medium",
          "fuel_type": "petrol",
          "renewable_energy": "no",
          "carpool": false,
          "total_km": 15,
          "weekly_travels": [0, 1, 2, 3, 4],
          "weekly_telecommuting": null,
          "daily_trips": 1,
          "situation": "active",
          "commuting_type": "in_itinere",
          "response_medium": "form",
          "origin": "Calle Gran Vía 1, Madrid",
          "destination": "Paseo de la Castellana 100, Madrid",
          "co2e": 1245.5,
          "file_id": null,
          "file_name": null,
          "created_at": "2024-01-15T10:30:00Z",
          "updated_at": "2024-01-15T10:30:00Z"
        }
      ],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Alice Johnson",
      "email": "alice.johnson@company.com",
      "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
      "situation": "active",
      "status": "uploaded",
      "periods": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "employee_id": "550e8400-e29b-41d4-a716-446655440001",
          "start_date": "2024-01-01",
          "end_date": "2024-12-31",
          "transport_type": "train",
          "vehicle_size": null,
          "fuel_type": "electric",
          "renewable_energy": "yes",
          "carpool": false,
          "total_km": 25,
          "weekly_travels": [1, 2, 3],
          "weekly_telecommuting": null,
          "daily_trips": 1,
          "situation": "active",
          "commuting_type": "in_itinere",
          "response_medium": "manual",
          "origin": null,
          "destination": null,
          "co2e": 456.2,
          "file_id": null,
          "file_name": null,
          "created_at": "2024-01-15T11:00:00Z",
          "updated_at": "2024-01-15T11:00:00Z"
        }
      ],
      "created_at": "2024-01-15T11:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

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

Solution: Verify your API key is valid and active. Get a new one from Settings -> API.

404 Not Found

Cause: Organization not found

{
  "code": "ORGANIZATION_NOT_FOUND",
  "detail": "Organization with id=UUID('...') not found"
}

Solution: Verify that the x-organization-id header contains a valid organization UUID.

422 Validation Error

Cause: Invalid query parameters

{
  "detail": [
    {
      "loc": ["query", "size"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}

Solution: Check that page size is between 1 and 100, and that filter values are valid enums.

Use Cases

Get All Active Employees

Retrieve only employees currently working:

def get_active_employees():
    """Get all active employees in the organization"""
    response = requests.get(
        "https://api.dcycle.io/v1/employees",
        headers=headers,
        params={"situation": ["active"], "size": 100}
    )
    return response.json()["items"]

active_employees = get_active_employees()
print(f"Active employees: {len(active_employees)}")

Calculate Total Category 7 Emissions

Sum up all employee commuting emissions:

def get_category_7_total():
    """Calculate total Scope 3 Category 7 emissions"""
    total_co2e = 0
    page = 1

    while True:
        response = requests.get(
            "https://api.dcycle.io/v1/employees",
            headers=headers,
            params={"page": page, "size": 100, "situation": ["active"]}
        )
        data = response.json()

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

        if len(data["items"]) < 100:
            break
        page += 1

    return total_co2e

total = get_category_7_total()
print(f"Scope 3 Category 7: {total:,.0f} kg CO2e ({total/1000:.1f} tonnes)")

Search Employees by Name

Find employees matching a search term:

def search_employees(search_term):
    """Search employees by name or email"""
    response = requests.get(
        "https://api.dcycle.io/v1/employees",
        headers=headers,
        params={"search": search_term, "size": 100}
    )
    return response.json()["items"]

# Find all employees with "john" in name or email
employees = search_employees("john")
for emp in employees:
    print(f"{emp['name']} - {emp['email']}")

Filter by Transport Mode

Find employees using specific transport:

def get_employees_by_transport(transport_types):
    """Get employees using specific transport modes"""
    response = requests.get(
        "https://api.dcycle.io/v1/employees",
        headers=headers,
        params={"transport_type": transport_types, "size": 100}
    )
    return response.json()["items"]

# Get employees who drive or take the bus
commuters = get_employees_by_transport(["car", "bus"])
print(f"Car/bus commuters: {len(commuters)}")

Pagination Guide

Navigate through large employee lists efficiently:

def iterate_all_employees(batch_size=50):
    """Iterate through all employees in organization"""
    page = 1
    while True:
        response = requests.get(
            "https://api.dcycle.io/v1/employees",
            headers=headers,
            params={"page": page, "size": batch_size}
        )
        data = response.json()

        for employee in data["items"]:
            yield employee

        if len(data["items"]) < batch_size:
            break
        page += 1

# Process all employees
for employee in iterate_all_employees():
    print(f"Processing {employee['name'] or employee['email']}")

Get Employee

Get a specific employee by ID

Create Employee

Add a new employee to your organization

Update Employee

Modify employee details

Commuting Periods

Manage commuting periods

​List Employees

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​422 Validation Error

​Use Cases

​Get All Active Employees

​Calculate Total Category 7 Emissions

​Search Employees by Name

​Filter by Transport Mode

​Pagination Guide

​Related Endpoints

Get Employee

Create Employee

Update Employee

Commuting Periods

List Employees

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

Use Cases

Get All Active Employees

Calculate Total Category 7 Emissions

Search Employees by Name

Filter by Transport Mode

Pagination Guide

Related Endpoints