Skip to main content
GET
/
v2
/
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));
{
  "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>"
}

​
List Employees (V2)

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

​
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"
​
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
​
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
​
response_medium[]
array[string]
Filter by how commuting data was collectedAvailable values: manual, qr, form, file_uploadExample: response_medium[]=form
​
file_id[]
array[string]
Filter by source file UUID(s)Example: file_id[]=550e8400-e29b-41d4-a716-446655440000
​
co2e_status
string
Filter by emission calculation statusAvailable values: calculated, not_calculatedExample: not_calculated
​
created_at_from
datetime
Filter employees created on or after this date (ISO 8601)Example: 2024-01-01T00:00:00Z
​
created_at_to
datetime
Filter employees created on or before this date (ISO 8601)Example: 2024-12-31T23:59:59Z
​
page
integer
default:"1"
Page number for paginationExample: 1
​
size
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.
​
items
array[object]
Array of employee objects (same structure as V1 list)
​
total
integer
Total number of employees matching the filters
​
page
integer
Current page number
​
size
integer
Number of items per page
​
filter_hash
string
Hash of the applied filters. Pass this to bulk delete by filters to ensure the delete operates on exactly the same result set.

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

​
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)