List Employees (V2)

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

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

import requests

url = "https://api.dcycle.io/v2/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": {},
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>",
  "select_all_matching_enabled": true
}

GET

employees

List Employees (V2)

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

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

import requests

url = "https://api.dcycle.io/v2/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": {},
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>",
  "select_all_matching_enabled": true
}

← Employees API Retrieve a paginated list of employees with advanced filtering. This V2 endpoint extends the V1 list with additional filters (co2e_status, file_id, created_at range) and returns a filter_hash required by the bulk delete by filters endpoint.

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 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 employment situationAvailable values: active, inactive, terminatedExample: situation[]=active

array[string]

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

array[string]

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

array[string]

Filter by source file UUID(s)Example: file_id[]=550e8400-e29b-41d4-a716-446655440000

string

Filter by emission calculation statusAvailable values: calculated, not_calculatedExample: not_calculated

datetime

Filter employees created on or after this date (ISO 8601)Example: 2024-01-01T00:00:00Z

datetime

Filter employees created on or before this date (ISO 8601)Example: 2024-12-31T23:59:59Z

integer

default:"1"

Page number for paginationExample: 1

integer

default:"10"

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

Response

Returns a paginated list of employees (HTTP 200) with a filter_hash for safe bulk operations.

array[object]

Array of employee objects (same structure as V1 list)

Show Employee Object

string

Unique identifier (UUID)

string | null

Employee’s full name

string | null

Employee’s email address

string

Organization UUID

string | null

active, inactive, or terminated

string

uploaded or loading

array[object] | null

Commuting periods with CO2e calculations

datetime

Record creation timestamp

datetime | null

Last update timestamp

integer

Total number of employees matching the filters

integer

Current page number

integer

Number of items per page

string

Hash of the applied filters. Pass this to bulk delete by filters to ensure the delete operates on exactly the same result set.

boolean

Capability flag: true means this backend exposes the bulk-*-by-filters endpoint for this list, so the client may offer “select all matching”. false on a backend that only supports bulk delete by explicit ids.

Example

curl -X GET "https://api.dcycle.io/v2/employees?co2e_status=not_calculated&situation[]=active&page=1&size=50" \
  -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
}

response = requests.get(
    "https://api.dcycle.io/v2/employees",
    headers=headers,
    params={
        "co2e_status": "not_calculated",
        "situation[]": ["active"],
        "page": 1,
        "size": 50
    }
)

data = response.json()
print(f"Found {data['total']} employees without emissions calculated")
print(f"Filter hash: {data['filter_hash']}")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
};

axios.get('https://api.dcycle.io/v2/employees', {
  headers,
  params: {
    co2e_status: 'not_calculated',
    'situation[]': ['active'],
    page: 1,
    size: 50,
  },
})
.then(({ data }) => {
  console.log(`Found ${data.total} employees without emissions calculated`);
  console.log(`Filter hash: ${data.filter_hash}`);
})
.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": [],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "size": 50,
  "filter_hash": "a1b2c3d4e5f6"
}

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

List Employees (V1)

Basic employee listing

Bulk Delete by Filters

Delete employees matching filters (requires filter_hash from this endpoint)

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​Related Endpoints

List Employees (V1)

Bulk Delete by Filters

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

Related Endpoints