> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Employees API

> Manage employee commuting data and calculate Scope 3 Category 7 emissions

# Employees API

The Employees API allows you to create, retrieve, update, and delete employee records for tracking commuting patterns and calculating Scope 3 Category 7 (Employee Commuting) emissions. Each employee can have multiple commuting periods with detailed transport information for accurate CO2e calculations.

<Note>
  **GHG Protocol Scope 3 Category 7**

  Employee commuting covers emissions from transportation of employees between their homes and worksites. This API helps you collect and manage the data needed for accurate Category 7 reporting.
</Note>

## Key Features

* **Employee Management**: Create and manage employee records with contact information
* **Commuting Periods**: Track multiple commuting patterns per employee over time
* **Transport Modes**: Support for cars, public transit, cycling, walking, and remote work
* **CO2e Calculation**: Automatic emissions calculation based on distance, transport mode, and frequency
* **Survey Integration**: Send surveys to employees to collect commuting data
* **Bulk Upload**: Import employee data via CSV for large organizations
* **Pagination Support**: Efficiently retrieve large employee lists

## Authentication

All endpoints require authentication using an API key included in the `x-api-key` header.

## Headers

All requests must include:

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

## Available Endpoints

### Employees

<CardGroup cols={2}>
  <Card title="List Employees" icon="list" href="/api-reference/employees/list">
    Retrieve all employees with filtering and pagination
  </Card>

  <Card title="Get Employee" icon="user" href="/api-reference/employees/get">
    Get a specific employee by ID
  </Card>

  <Card title="Create Employee" icon="plus" href="/api-reference/employees/create">
    Add a new employee to your organization
  </Card>

  <Card title="Update Employee" icon="pencil" href="/api-reference/employees/update">
    Modify employee details
  </Card>

  <Card title="Delete Employee" icon="trash" href="/api-reference/employees/delete">
    Remove an employee from your organization
  </Card>
</CardGroup>

### Survey Templates

<CardGroup cols={2}>
  <Card title="List Templates" icon="list" href="/api-reference/employees/survey-templates/list">
    Get all survey templates for your organization
  </Card>

  <Card title="Create Template" icon="plus" href="/api-reference/employees/survey-templates/create">
    Create a customizable survey template
  </Card>

  <Card title="Clone Template" icon="copy" href="/api-reference/employees/survey-templates/clone">
    Duplicate an existing template
  </Card>

  <Card title="Set Default" icon="star" href="/api-reference/employees/survey-templates/set-default">
    Set a template as the organization default
  </Card>
</CardGroup>

### Commuting Periods

<CardGroup cols={2}>
  <Card title="List Commuting Periods" icon="calendar" href="/api-reference/employees/commuting-periods/list">
    Get commuting periods for an employee
  </Card>

  <Card title="Create Commuting Period" icon="route" href="/api-reference/employees/commuting-periods/create">
    Add a new commuting period
  </Card>

  <Card title="Update Commuting Period" icon="pencil" href="/api-reference/employees/commuting-periods/update">
    Modify commuting period details
  </Card>

  <Card title="Delete Commuting Period" icon="trash" href="/api-reference/employees/commuting-periods/delete">
    Remove a commuting period
  </Card>
</CardGroup>

## Data Model

### Employee Object

The employee object contains basic employee information:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
}
```

### Employee Attributes

| Field             | Type     | Description                                           |
| ----------------- | -------- | ----------------------------------------------------- |
| `id`              | UUID     | Unique identifier for the employee                    |
| `name`            | string   | Employee's full name                                  |
| `email`           | string   | Employee's email address                              |
| `organization_id` | UUID     | Organization the employee belongs to                  |
| `situation`       | string   | Employment status: `active`, `inactive`, `terminated` |
| `status`          | string   | Data status: `uploaded`, `loading`                    |
| `periods`         | array    | List of commuting periods (when requested)            |
| `created_at`      | datetime | When the employee was created                         |
| `updated_at`      | datetime | When the employee was last updated                    |

### Commuting Period Object

Commuting periods track how an employee commutes during a specific time range:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "employee_id": "550e8400-e29b-41d4-a716-446655440000",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "commuting_type": "in_itinere",
  "transport_type": "car",
  "vehicle_size": "medium",
  "fuel_type": "petrol",
  "total_km": 15,
  "weekly_travels": [0, 1, 2, 3, 4],
  "daily_trips": 1,
  "carpool": false,
  "situation": "active",
  "co2e": 1245.5,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

## Transport Types

| Transport Type          | Description                | Requires Fuel Type | Requires Vehicle Size |
| ----------------------- | -------------------------- | ------------------ | --------------------- |
| `car`                   | Personal vehicle           | Yes                | Yes                   |
| `bus`                   | Public bus                 | Yes                | No                    |
| `train`                 | Commuter rail              | Optional           | No                    |
| `metro`                 | Urban subway               | Optional           | No                    |
| `tram`                  | Light rail                 | No                 | No                    |
| `motorbike`             | Motorcycle                 | Yes                | No                    |
| `bicycle`               | Cycling (including e-bike) | Optional           | No                    |
| `walking`               | Walking                    | No                 | No                    |
| `telecommuting`         | Remote work                | No                 | No                    |
| `electric_kick_scooter` | Electric scooter           | No                 | No                    |
| `trolleybus`            | Electric bus               | Optional           | No                    |

## Fuel Types

| Fuel Type        | Description             | Applicable Transport                  |
| ---------------- | ----------------------- | ------------------------------------- |
| `petrol`         | Gasoline                | car, motorbike, bus                   |
| `diesel`         | Diesel fuel             | car, motorbike, bus                   |
| `electric`       | Electric vehicle        | car, motorbike, metro, train, bicycle |
| `hybrid`         | Hybrid vehicle          | car                                   |
| `lpg`            | Liquefied petroleum gas | car, bus                              |
| `natural_gas`    | Natural gas             | car, bus                              |
| `not_fuel_based` | No fuel (human powered) | bicycle                               |
| `do_not_know`    | Unknown fuel type       | Any motorized                         |

## Vehicle Sizes (Cars Only)

| Size     | Description                                |
| -------- | ------------------------------------------ |
| `small`  | Compact cars (e.g., city cars, superminis) |
| `medium` | Mid-size sedans and hatchbacks             |
| `large`  | SUVs, large sedans, minivans               |

## Weekly Travels

The `weekly_travels` field is an array of integers representing which days the employee commutes:

| Value | Day       |
| ----- | --------- |
| `0`   | Monday    |
| `1`   | Tuesday   |
| `2`   | Wednesday |
| `3`   | Thursday  |
| `4`   | Friday    |
| `5`   | Saturday  |
| `6`   | Sunday    |

**Examples:**

* `[0, 1, 2, 3, 4]` - Monday to Friday (5-day week)
* `[1, 3]` - Tuesday and Thursday only (hybrid)
* `[]` - Fully remote (telecommuting)

## CO2e Calculation

Emissions are calculated using the formula:

```
CO2e = Distance (km) × Working Days × Daily Trips × Emission Factor × 2 (round trip)
```

* **Distance**: One-way distance from home to work (`total_km`)
* **Working Days**: Calculated from `weekly_travels` and date range
* **Daily Trips**: Number of round trips per day
* **Emission Factor**: Based on transport type, fuel, and vehicle size (from Ecoinvent database)
* **Carpool Factor**: If `carpool: true`, emissions are divided by 3

## Workflow

### Tracking Employee Commuting

1. **Create Employee**: Add employee with name or email
2. **Create Commuting Period**: Define the commuting pattern for a date range
3. **Query Emissions**: Retrieve employee with `periods` to see calculated CO2e

### Using Surveys

1. **Upload Employees via CSV**: Bulk create employees with email addresses
2. **Send Survey**: Use the resend-survey endpoint to collect commuting data
3. **Review Results**: Employees fill in the survey, creating commuting periods automatically

## Error Handling

### Common HTTP Status Codes

| Status | Meaning                        | Solution                            |
| ------ | ------------------------------ | ----------------------------------- |
| 200    | Success                        | -                                   |
| 201    | Created                        | -                                   |
| 204    | No Content (delete successful) | -                                   |
| 400    | Bad Request                    | Check request parameters and format |
| 401    | Unauthorized                   | Verify API key                      |
| 404    | Not Found                      | Check resource ID or organization   |
| 422    | Validation Error               | Review error details in response    |
| 500    | Server Error                   | Contact support if persists         |

### Error Response Format

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Error description",
  "code": "ERROR_CODE"
}
```

## Use Cases

### Track Office Commuting

Monitor CO2e emissions for employees commuting to the office:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests

# Create employee
employee = requests.post(
    "https://api.dcycle.io/v1/employees",
    headers=headers,
    json={
        "name": "John Smith",
        "email": "john@company.com",
        "situation": "active",
        "status": "uploaded"
    }
).json()

# Add commuting period
period = requests.post(
    "https://api.dcycle.io/v1/employee-historic",
    headers=headers,
    json={
        "employee_id": employee["id"],
        "start_date": "2024-01-01",
        "end_date": "2024-12-31",
        "commuting_type": "in_itinere",
        "transport_type": "car",
        "vehicle_size": "medium",
        "fuel_type": "petrol",
        "total_km": 15,
        "weekly_travels": [0, 1, 2, 3, 4],
        "daily_trips": 1,
        "carpool": False,
        "situation": "active",
        "response_medium": "manual"
    }
).json()

print(f"Annual CO2e: {period['co2e']} kg")
```

### Calculate Category 7 Totals

Sum up all employee commuting emissions:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Get all employees with periods
response = requests.get(
    "https://api.dcycle.io/v1/employees",
    headers=headers,
    params={"size": 100}
).json()

total_co2e = 0
for employee in response["items"]:
    for period in employee.get("periods", []):
        total_co2e += period.get("co2e", 0)

print(f"Scope 3 Category 7 Total: {total_co2e} kg CO2e")
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="Employee Commuting Guide" icon="route" href="/guides/emissions/scope-3-category-7-employee-commuting">
    Complete tutorial for tracking Scope 3 Category 7 emissions
  </Card>

  <Card title="GHG Protocol Tutorial" icon="book" href="/guides/emissions/ghg-protocol-tutorial">
    Learn about GHG Protocol and emissions tracking
  </Card>

  <Card title="Authentication Guide" icon="key" href="/docs/authentication">
    Learn how to authenticate API requests
  </Card>

  <Card title="Vehicles API" icon="car" href="/api-reference/vehicles/overview">
    Track company fleet emissions (Scope 1)
  </Card>

  <Card title="MCP Tools" icon="robot" href="/mcp/employees">
    Query employee data from AI assistants via MCP
  </Card>
</CardGroup>