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

# List Employees (V2)

> Enhanced employee listing with advanced filters and filter_hash for safe bulk operations

# List Employees (V2)

Retrieve a paginated list of employees with advanced filtering. This V2 endpoint extends the [V1 list](/api-reference/employees/list) with additional filters (`co2e_status`, `file_id`, `created_at` range) and returns a `filter_hash` required by the [bulk delete by filters](/api-reference/employees/bulk-delete-by-filters) endpoint.

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

### Query Parameters

<ParamField query="search" type="string">
  Search employees by name or email (partial match)

  **Example:** `"john"`
</ParamField>

<ParamField query="transport_type[]" type="array[string]">
  Filter by transport type used in commuting periods

  **Available values:** `car`, `bus`, `train`, `metro`, `tram`, `motorbike`, `bicycle`, `walking`, `telecommuting`, `electric_kick_scooter`, `trolleybus`

  **Example:** `transport_type[]=car&transport_type[]=bus`
</ParamField>

<ParamField query="situation[]" type="array[string]">
  Filter by employment situation

  **Available values:** `active`, `inactive`, `terminated`

  **Example:** `situation[]=active`
</ParamField>

<ParamField query="status[]" type="array[string]">
  Filter by data status

  **Available values:** `uploaded`, `loading`

  **Example:** `status[]=uploaded`
</ParamField>

<ParamField query="response_medium[]" type="array[string]">
  Filter by how commuting data was collected

  **Available values:** `manual`, `qr`, `form`, `file_upload`

  **Example:** `response_medium[]=form`
</ParamField>

<ParamField query="file_id[]" type="array[string]">
  Filter by source file UUID(s)

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

<ParamField query="co2e_status" type="string">
  Filter by emission calculation status

  **Available values:** `calculated`, `not_calculated`

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

<ParamField query="created_at_from" type="datetime">
  Filter employees created on or after this date (ISO 8601)

  **Example:** `2024-01-01T00:00:00Z`
</ParamField>

<ParamField query="created_at_to" type="datetime">
  Filter employees created on or before this date (ISO 8601)

  **Example:** `2024-12-31T23:59:59Z`
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination

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

<ParamField query="size" type="integer" default="10">
  Number of items per page (max 100)

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

## Response

Returns a paginated list of employees (HTTP 200) with a `filter_hash` for safe bulk operations.

<ResponseField name="items" type="array[object]">
  Array of employee objects (same structure as [V1 list](/api-reference/employees/list))

  <Expandable title="Employee Object">
    <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">`active`, `inactive`, or `terminated`</ResponseField>
    <ResponseField name="status" type="string">`uploaded` or `loading`</ResponseField>
    <ResponseField name="periods" type="array[object] | null">Commuting periods with CO2e calculations</ResponseField>
    <ResponseField name="created_at" type="datetime">Record creation timestamp</ResponseField>
    <ResponseField name="updated_at" type="datetime | null">Last update timestamp</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of employees matching the filters
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="size" type="integer">
  Number of items per page
</ResponseField>

<ResponseField name="filter_hash" type="string">
  Hash of the applied filters. Pass this to [bulk delete by filters](/api-reference/employees/bulk-delete-by-filters) to ensure the delete operates on exactly the same result set.
</ResponseField>

## Example

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

  ```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")

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

  response = requests.get(
      "https://api.dcycle.io/v2/employees",
      headers=headers,
      params={
          "co2e_status": "not_calculated",
          "situation[]": ["active"],
          "page": 1,
          "size": 50
      }
  )

  data = response.json()
  print(f"Found {data['total']} employees without emissions calculated")
  print(f"Filter hash: {data['filter_hash']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const headers = {
    'x-api-key': process.env.DCYCLE_API_KEY,
    'x-organization-id': process.env.DCYCLE_ORG_ID,
  };

  axios.get('https://api.dcycle.io/v2/employees', {
    headers,
    params: {
      co2e_status: 'not_calculated',
      'situation[]': ['active'],
      page: 1,
      size: 50,
    },
  })
  .then(({ data }) => {
    console.log(`Found ${data.total} employees without emissions calculated`);
    console.log(`Filter hash: ${data.filter_hash}`);
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
```

### 403 Forbidden

**Cause:** The authenticated user is not a member of the organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Employees (V1)" icon="users" href="/api-reference/employees/list">
    Basic employee listing
  </Card>

  <Card title="Bulk Delete by Filters" icon="trash" href="/api-reference/employees/bulk-delete-by-filters">
    Delete employees matching filters (requires filter\_hash from this endpoint)
  </Card>
</CardGroup>