Get Employee

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

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

import requests

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

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

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

print(response.text)

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

GET

employees

{employee_id}

Get Employee

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

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

import requests

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

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

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

print(response.text)

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

Get Employee

Retrieve a specific employee by their unique identifier. The response includes all commuting periods associated with the employee, allowing you to see their complete commuting history and CO2e calculations.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Path Parameters

string

required

The unique identifier (UUID) of the employeeExample: 550e8400-e29b-41d4-a716-446655440000

Response

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

List of commuting periods with full details

Show Commuting Period Object

string

Period unique identifier (UUID)

string

Employee UUID

date

Period start date

date

Period end date

string

Type of commute: in_itinere (home-work) or in_labore (during work)

string | null

Mode of transport

string | null

Vehicle size for cars: small, medium, large

string | null

Fuel type for motorized transport

string | null

For electric vehicles: yes, no, do_not_know

number | null

One-way distance in kilometers

array | null

Days of the week employee commutes (0=Mon, 6=Sun)

integer

Number of round trips per day

boolean

Whether employee carpools

array | null

Days of the week employee telecommutes (0=Mon, 6=Sun)

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 status: active, inactive, terminated

string | null

Origin address/location

string | null

Destination address/location

string | null

How data was collected: manual, qr, form

number | null

Calculated CO2 equivalent emissions in kg. null if not yet calculated.

string | null

UUID of the linked file (if uploaded via bulk import)

string | null

Name of the linked import file

datetime

Timestamp when the period was created

datetime | null

Timestamp when the period was last updated

datetime

Timestamp when the employee was created

datetime | null

Timestamp when the employee was last updated

Example

curl -X GET "https://api.dcycle.io/v1/employees/550e8400-e29b-41d4-a716-446655440000" \
  -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")
employee_id = "550e8400-e29b-41d4-a716-446655440000"

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

response = requests.get(
    f"https://api.dcycle.io/v1/employees/{employee_id}",
    headers=headers
)

employee = response.json()
print(f"Employee: {employee['name']}")
print(f"Email: {employee['email']}")
print(f"Status: {employee['situation']}")

# Calculate total emissions
total_co2e = sum(p['co2e'] for p in employee.get('periods', []))
print(f"Total CO2e: {total_co2e} kg")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;
const employeeId = '550e8400-e29b-41d4-a716-446655440000';

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

axios.get(
  `https://api.dcycle.io/v1/employees/${employeeId}`,
  { headers }
)
.then(response => {
  const employee = response.data;
  console.log(`Employee: ${employee.name}`);
  console.log(`Email: ${employee.email}`);
  console.log(`Status: ${employee.situation}`);

  // Calculate total emissions
  const totalCo2e = (employee.periods || [])
    .reduce((sum, p) => sum + p.co2e, 0);
  console.log(`Total CO2e: ${totalCo2e} kg`);
})
.catch(error => console.error(error));

Successful Response

{
  "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-06-30",
      "commuting_type": "in_itinere",
      "transport_type": "car",
      "vehicle_size": "medium",
      "fuel_type": "petrol",
      "renewable_energy": null,
      "total_km": 15,
      "weekly_travels": [0, 1, 2, 3, 4],
      "daily_trips": 1,
      "carpool": false,
      "situation": "active",
      "origin": "Home Address",
      "destination": "Office Address",
      "response_medium": "form",
      "co2e": 622.75,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "employee_id": "550e8400-e29b-41d4-a716-446655440000",
      "start_date": "2024-07-01",
      "end_date": "2024-12-31",
      "commuting_type": "in_itinere",
      "transport_type": "train",
      "vehicle_size": null,
      "fuel_type": "electric",
      "renewable_energy": "yes",
      "total_km": 15,
      "weekly_travels": [0, 1, 2, 3, 4],
      "daily_trips": 1,
      "carpool": false,
      "situation": "active",
      "origin": "Home Address",
      "destination": "Office Address",
      "response_medium": "form",
      "co2e": 156.20,
      "created_at": "2024-07-01T09:00:00Z",
      "updated_at": "2024-07-01T09:00:00Z"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-07-01T09:00:00Z"
}

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.

404 Not Found

Cause: Employee not found or doesn’t belong to your organization

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

Solution: Verify the employee ID is correct and belongs to your organization.

Use Cases

View Employee Commuting History

See how an employee’s commuting has changed over time:

def get_employee_history(employee_id):
    """Get employee with full commuting history"""
    response = requests.get(
        f"https://api.dcycle.io/v1/employees/{employee_id}",
        headers=headers
    )
    employee = response.json()

    print(f"Employee: {employee['name']}")
    print(f"Commuting History:")

    for period in employee.get('periods', []):
        print(f"  {period['start_date']} - {period['end_date']}")
        print(f"    Transport: {period['transport_type']}")
        print(f"    Distance: {period['total_km']} km")
        print(f"    CO2e: {period['co2e']} kg")
        print()

    return employee

employee = get_employee_history("550e8400-e29b-41d4-a716-446655440000")

Calculate Annual Emissions

Get total emissions for a specific year:

from datetime import date

def get_annual_emissions(employee_id, year):
    """Calculate employee's emissions for a specific year"""
    response = requests.get(
        f"https://api.dcycle.io/v1/employees/{employee_id}",
        headers=headers
    )
    employee = response.json()

    total_co2e = 0
    for period in employee.get('periods', []):
        # Check if period overlaps with the year
        start = date.fromisoformat(period['start_date'])
        end = date.fromisoformat(period['end_date'])

        year_start = date(year, 1, 1)
        year_end = date(year, 12, 31)

        if start <= year_end and end >= year_start:
            # Period overlaps with the year
            total_co2e += period['co2e']

    return total_co2e

emissions_2024 = get_annual_emissions(
    "550e8400-e29b-41d4-a716-446655440000",
    2024
)
print(f"2024 Emissions: {emissions_2024} kg CO2e")

Analyze Transport Mode Usage

Understand which transport modes an employee uses:

def analyze_transport_modes(employee_id):
    """Analyze transport modes used by employee"""
    response = requests.get(
        f"https://api.dcycle.io/v1/employees/{employee_id}",
        headers=headers
    )
    employee = response.json()

    transport_summary = {}
    for period in employee.get('periods', []):
        transport = period['transport_type']
        if transport not in transport_summary:
            transport_summary[transport] = {
                'periods': 0,
                'total_co2e': 0
            }
        transport_summary[transport]['periods'] += 1
        transport_summary[transport]['total_co2e'] += period['co2e']

    print(f"Transport analysis for {employee['name']}:")
    for transport, data in transport_summary.items():
        print(f"  {transport}: {data['periods']} periods, {data['total_co2e']:.1f} kg CO2e")

    return transport_summary

analyze_transport_modes("550e8400-e29b-41d4-a716-446655440000")

List Employees

View all employees in your organization

Update Employee

Modify employee details

Delete Employee

Remove an employee

Commuting Periods

Manage commuting periods separately

​Get Employee

​Request

​Headers

​Path Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​Use Cases

​View Employee Commuting History

​Calculate Annual Emissions

​Analyze Transport Mode Usage

​Related Endpoints

List Employees

Update Employee

Delete Employee

Commuting Periods

Get Employee

Request

Headers

Path Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

Use Cases

View Employee Commuting History

Calculate Annual Emissions

Analyze Transport Mode Usage

Related Endpoints