Skip to main content
GET
/
v1
/
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));
{
  "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,
      "situation": "<string>",
      "origin": {},
      "destination": {},
      "response_medium": {},
      "co2e": 123,
      "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

​
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

​
Path Parameters

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

​
Response

​
id
string
Unique identifier (UUID)
​
name
string | null
Employee’s full name
​
email
string | null
Employee’s email address
​
organization_id
string
Organization UUID
​
situation
string | null
Employment status: active, inactive, or terminated
​
status
string
Data status: uploaded or loading
​
periods
array
List of commuting periods with full details
​
created_at
datetime
Timestamp when the employee was created
​
updated_at
datetime
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}"

​
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