Employee Tools

Query employees and their commuting periods — this is Scope 3 employee commuting data. Each employee can have multiple commuting periods with different transport modes, distances, and CO₂e calculations.

`list_employees`

List employees with their commuting periods, including origin/destination data and CO₂e emissions. Parameters:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID
`situation`	string	No	—	Employment situation: `active`, `inactive`
`status`	string	No	—	Data processing status: `uploaded`, `loading`
`transport_type`	string	No	—	Filter by commuting transport mode (see below)
`response_medium`	string	No	—	How data was collected: `manual`, `qr`, `form`, `file_upload`
`file_id`	string	No	—	Filter by source file UUID (for bulk-uploaded employees)
`search`	string	No	—	Search by name or email
`created_at_from`	string	No	—	Filter employees created at/after this date (ISO datetime)
`created_at_to`	string	No	—	Filter employees created at/before this date (ISO datetime)
`co2e_status`	string	No	—	Calculation state: `calculated`, `not_calculated`
`page`	integer	No	1	Page number
`size`	integer	No	50	Results per page

Transport type values

Value	Description
`car`	Private car
`bus`	Bus
`train`	Train
`metro`	Metro/subway
`tram`	Tram
`motorbike`	Motorbike
`bicycle`	Bicycle
`walking`	Walking
`telecommuting`	Remote work
`electric_kick_scooter`	Electric scooter
`trolleybus`	Trolleybus

Employee responses include nested periods arrays with detailed commuting data. Each period has total_km, transport_type, fuel_type, co2e, and schedule fields. Large organizations can have thousands of employees — use size ≤ 20 and paginate to avoid oversized responses.

Example response:

{
  "items": [
    {
      "id": "d43aaf5b-...",
      "name": "María García",
      "email": "maria@company.com",
      "situation": "active",
      "status": "uploaded",
      "periods": [
        {
          "id": "a1b2c3d4-...",
          "transport_type": "car",
          "fuel_type": "diesel",
          "vehicle_size": "medium",
          "total_km": 25.0,
          "weekly_travels": [0, 1, 2, 3, 4],
          "daily_trips": 2,
          "carpool": false,
          "commuting_type": "in_itinere",
          "origin": "Calle Mayor 1, Madrid",
          "destination": "Paseo de la Castellana 50, Madrid",
          "co2e": 1820.5,
          "start_date": "2025-01-01",
          "end_date": null,
          "response_medium": "form"
        }
      ],
      "created_at": "2024-11-24T10:30:00Z",
      "updated_at": "2025-03-15T14:20:00Z"
    }
  ],
  "total": 99,
  "page": 1,
  "size": 50,
  "pages": 2
}

Key response fields:

Field	Description
`situation`	Employment situation (`active`, `inactive`)
`status`	Data processing status (`uploaded` = ready, `loading` = being processed)
`periods[].transport_type`	Mode of transport for this commuting period
`periods[].total_km`	One-way commute distance in km
`periods[].co2e`	Calculated CO₂e emissions in kg for this period
`periods[].commuting_type`	`in_itinere` (home→office) or `in_labore` (work-related travel)
`periods[].weekly_travels`	Days of the week (0=Mon, 4=Fri) the employee commutes

Example prompts:

"How many active employees do we have?"
"Search for employees named García"
"List employees who commute by car"
"Show employees whose emissions haven't been calculated yet"
"Which employees were uploaded via the last CSV file?"

`create_employee`

Create a new employee for commuting emissions tracking (Scope 3). At least one of name or email must be provided. Parameters:

Parameter	Type	Required	Description
`situation`	string	Yes	Employee situation: `active`, `inactive`, or `terminated`
`name`	string	No	Employee name (required if no email)
`email`	string	No	Employee email (required if no name)
`organization_id`	string	No	Organization UUID (uses default if not set)

After creating an employee, add commuting periods to calculate Scope 3 emissions.

Example prompts:

"Create a new active employee named María García"
"Add employee maria@company.com to the organization"

`update_employee`

Update an existing employee. Only provided fields are changed (partial update). Parameters:

Parameter	Type	Required	Description
`employee_id`	string	Yes	UUID of the employee to update
`name`	string	No	New employee name
`email`	string	No	New employee email
`situation`	string	No	New situation: `active`, `inactive`, or `terminated`
`organization_id`	string	No	Organization UUID (uses default if not set)

Example prompts:

"Set employee d43aaf5b-... to inactive"
"Update María García's email to maria.garcia@company.com"

Workflow

List employees — list_employees to find employees by name, situation, or transport type
Create employees — create_employee to add new employees for commuting tracking
Update employees — update_employee to change situation, name, or email
Analyze commuting patterns — Use transport_type filter to see how employees commute
Check data completeness — Use co2e_status=not_calculated to find employees missing emission calculations
View emissions — get_greenhouse_gas_emissions with category=employees_in_itinere for aggregated commuting totals

API: List Employees

REST API equivalent with additional filters

Emissions

Aggregated Scope 3 commuting emissions

CLI

Manage employees from the command line

Getting Started

Tools Reference

Reference Data

Employee Tools

Employee Tools

`list_employees`

`create_employee`

`update_employee`

Workflow

API: List Employees

Emissions

CLI

​Employee Tools

​list_employees

​create_employee

​update_employee

​Workflow

​Related

API: List Employees

Emissions

CLI

Employee Tools

`list_employees`

`create_employee`

`update_employee`

Workflow

Related