> ## 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.

# Get Employee

> Retrieve a specific employee by ID with their commuting periods

# 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

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

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

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

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

### Path Parameters

<ParamField path="employee_id" type="string" required>
  The unique identifier (UUID) of the employee

  **Example:** `550e8400-e29b-41d4-a716-446655440000`
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier (UUID)
</ResponseField>

<ResponseField name="name" type="string | null">
  Employee's full name
</ResponseField>

<ResponseField name="email" type="string | null">
  Employee's email address
</ResponseField>

<ResponseField name="organization_id" type="string">
  Organization UUID
</ResponseField>

<ResponseField name="situation" type="string | null">
  Employment status: `active`, `inactive`, or `terminated`
</ResponseField>

<ResponseField name="status" type="string">
  Data status: `uploaded` or `loading`
</ResponseField>

<ResponseField name="periods" type="array">
  List of commuting periods with full details

  <Expandable title="Commuting Period Object">
    <ResponseField name="id" type="string">
      Period unique identifier (UUID)
    </ResponseField>

    <ResponseField name="employee_id" type="string">
      Employee UUID
    </ResponseField>

    <ResponseField name="start_date" type="date">
      Period start date
    </ResponseField>

    <ResponseField name="end_date" type="date">
      Period end date
    </ResponseField>

    <ResponseField name="commuting_type" type="string">
      Type of commute: `in_itinere` (home-work) or `in_labore` (during work)
    </ResponseField>

    <ResponseField name="transport_type" type="string | null">
      Mode of transport
    </ResponseField>

    <ResponseField name="vehicle_size" type="string | null">
      Vehicle size for cars: `small`, `medium`, `large`
    </ResponseField>

    <ResponseField name="fuel_type" type="string | null">
      Fuel type for motorized transport
    </ResponseField>

    <ResponseField name="renewable_energy" type="string | null">
      For electric vehicles: `yes`, `no`, `do_not_know`
    </ResponseField>

    <ResponseField name="total_km" type="number | null">
      One-way distance in kilometers
    </ResponseField>

    <ResponseField name="weekly_travels" type="array | null">
      Days of the week employee commutes (0=Mon, 6=Sun)
    </ResponseField>

    <ResponseField name="daily_trips" type="integer">
      Number of round trips per day
    </ResponseField>

    <ResponseField name="carpool" type="boolean">
      Whether employee carpools
    </ResponseField>

    <ResponseField name="weekly_telecommuting" type="array | null">
      Days of the week employee telecommutes (0=Mon, 6=Sun)
    </ResponseField>

    <ResponseField name="hours_worked_per_day" type="integer | null">
      Hours worked per day
    </ResponseField>

    <ResponseField name="total_commuting_days" type="integer | null">
      Total commuting days in the period
    </ResponseField>

    <ResponseField name="total_telecommuting_days" type="integer | null">
      Total telecommuting days in the period
    </ResponseField>

    <ResponseField name="situation" type="string | null">
      Period status: `active`, `inactive`, `terminated`
    </ResponseField>

    <ResponseField name="origin" type="string | null">
      Origin address/location
    </ResponseField>

    <ResponseField name="destination" type="string | null">
      Destination address/location
    </ResponseField>

    <ResponseField name="response_medium" type="string | null">
      How data was collected: `manual`, `qr`, `form`
    </ResponseField>

    <ResponseField name="co2e" type="number | null">
      Calculated CO2 equivalent emissions in kg. `null` if not yet calculated.
    </ResponseField>

    <ResponseField name="file_id" type="string | null">
      UUID of the linked file (if uploaded via bulk import)
    </ResponseField>

    <ResponseField name="file_name" type="string | null">
      Name of the linked import file
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Timestamp when the period was created
    </ResponseField>

    <ResponseField name="updated_at" type="datetime | null">
      Timestamp when the period was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="datetime">
  Timestamp when the employee was created
</ResponseField>

<ResponseField name="updated_at" type="datetime | null">
  Timestamp when the employee was last updated
</ResponseField>

## Example

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

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

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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));
  ```
</CodeGroup>

### Successful Response

```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": [
    {
      "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

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

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

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

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

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

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Employees" icon="list" href="/api-reference/employees/list">
    View all employees in 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
  </Card>

  <Card title="Commuting Periods" icon="route" href="/api-reference/employees/commuting-periods/list">
    Manage commuting periods separately
  </Card>
</CardGroup>