Skip to main content
GET
/
v1
/
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));
{
  "items": {
    "id": "<string>",
    "name": {},
    "email": {},
    "organization_id": "<string>",
    "situation": {},
    "status": "<string>",
    "periods": {},
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "pages": 123
}

​
List Employees

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

​
Request

​
Headers

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Query Parameters

​
search
string
Search employees by name or email (partial match)Example: "john"
​
situation
array[string]
Filter by employment situationAvailable values: active, inactive, terminatedExample: situation=active
​
status
array[string]
Filter by data statusAvailable values: uploaded, loadingExample: status=uploaded
​
transport_type
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
​
response_medium
array[string]
Filter by how commuting data was collectedAvailable values: manual, qr, formExample: response_medium=form
​
page
integer
default:"1"
Page number for paginationExample: 2
​
size
integer
default:"50"
Number of items per page (max 100)Example: 50

​
Response

​
items
array[object]
Array of employee objects
​
total
integer
Total number of employees matching the filter
​
page
integer
Current page number
​
size
integer
Number of items per page
​
pages
integer
Total number of pages

​
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}"

​
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",
          "total_km": 15,
          "weekly_travels": [0, 1, 2, 3, 4],
          "daily_trips": 1,
          "carpool": false,
          "co2e": 1245.5,
          "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",
          "total_km": 25,
          "weekly_travels": [1, 2, 3],
          "daily_trips": 1,
          "carpool": false,
          "co2e": 456.2,
          "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,
  "pages": 1
}

​
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 page >= data["pages"]:
            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 page >= data["pages"]:
            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