Create Employee

Create a new employee record in your organization. After creating an employee, you can add commuting periods to track their transportation emissions.

Name or Email Required: At least one of name or email must be provided when creating an employee.

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

Body Parameters

name

string

Employee’s full name (1-255 characters)Required if email is not providedExample: "John Smith"

string

Employee’s email addressRequired if name is not providedExample: "[email protected]"

situation

string

required

Employment situationAvailable values: active, inactive, terminatedExample: "active"

status

string

required

Data collection statusAvailable values: uploaded, loadingExample: "uploaded"

Response

string

Unique identifier (UUID) for the employee

name

string | null

Employee’s full name

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

List of commuting periods (empty for new employees)

created_at

datetime

Timestamp when the employee was created

updated_at

datetime

Timestamp when the employee was last updated

Example

curl -X POST "https://api.dcycle.io/v1/employees" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "email": "[email protected]",
    "situation": "active",
    "status": "uploaded"
  }'

Successful Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John Smith",
  "email": "[email protected]",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "situation": "active",
  "status": "uploaded",
  "periods": null,
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T10:30: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. Get a new one from Settings -> API.

404 Not Found

Cause: Organization not found

{
  "code": "ORGANIZATION_NOT_FOUND",
  "detail": "Organization with id=UUID('...') not found"
}

Solution: Verify that the x-organization-id header contains a valid organization UUID.

422 Validation Error

Cause: Missing required parameters or invalid values

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "Either name or email must be provided",
      "type": "value_error"
    }
  ]
}

Solution: Ensure at least name or email is provided, and situation and status have valid enum values.

Use Cases

Create Employee with Full Details

Add an employee with all available information:

def create_employee(name, email, situation="active"):
    """Create a new employee with full details"""
    payload = {
        "name": name,
        "email": email,
        "situation": situation,
        "status": "uploaded"
    }

    response = requests.post(
        "https://api.dcycle.io/v1/employees",
        headers=headers,
        json=payload
    )

    return response.json()

# Create employee
employee = create_employee(
    name="John Smith",
    email="[email protected]"
)
print(f"Created: {employee['id']}")

Create Employee for Survey

Create an employee with just email for survey distribution:

def create_employee_for_survey(email):
    """Create employee for survey - email only"""
    payload = {
        "email": email,
        "situation": "active",
        "status": "loading"  # Will be updated after survey
    }

    response = requests.post(
        "https://api.dcycle.io/v1/employees",
        headers=headers,
        json=payload
    )

    return response.json()

# Create employees for survey
emails = ["[email protected]", "[email protected]", "[email protected]"]
for email in emails:
    employee = create_employee_for_survey(email)
    print(f"Created {email}: {employee['id']}")

Create Employee and Add Commuting Period

Complete workflow to track an employee’s commuting:

def create_employee_with_commuting(name, email, commuting_data):
    """Create employee and add their commuting period"""

    # Step 1: Create employee
    employee = requests.post(
        "https://api.dcycle.io/v1/employees",
        headers=headers,
        json={
            "name": name,
            "email": email,
            "situation": "active",
            "status": "uploaded"
        }
    ).json()

    # Step 2: Add commuting period
    period_data = {
        "employee_id": employee["id"],
        "commuting_type": "in_itinere",
        "situation": "active",
        "response_medium": "manual",
        **commuting_data
    }

    period = requests.post(
        "https://api.dcycle.io/v1/employee-historic",
        headers=headers,
        json=period_data
    ).json()

    return employee, period

# Create employee with car commute
employee, period = create_employee_with_commuting(
    name="John Smith",
    email="[email protected]",
    commuting_data={
        "start_date": "2024-01-01",
        "end_date": "2024-12-31",
        "transport_type": "car",
        "vehicle_size": "medium",
        "fuel_type": "petrol",
        "total_km": 15,
        "weekly_travels": [0, 1, 2, 3, 4],
        "daily_trips": 1,
        "carpool": False,
        "renewable_energy": None
    }
)

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

Bulk Create Employees

Add multiple employees from a list:

def bulk_create_employees(employees_data):
    """Create multiple employees at once"""
    created = []
    failed = []

    for emp_data in employees_data:
        try:
            response = requests.post(
                "https://api.dcycle.io/v1/employees",
                headers=headers,
                json={
                    "name": emp_data.get("name"),
                    "email": emp_data.get("email"),
                    "situation": "active",
                    "status": "uploaded"
                }
            )

            if response.status_code == 201:
                created.append(response.json())
            else:
                failed.append({"data": emp_data, "error": response.text})

        except Exception as e:
            failed.append({"data": emp_data, "error": str(e)})

    return created, failed

# Bulk create
employees_to_create = [
    {"name": "Alice Johnson", "email": "[email protected]"},
    {"name": "Bob Williams", "email": "[email protected]"},
    {"name": "Carol Davis", "email": "[email protected]"},
]

created, failed = bulk_create_employees(employees_to_create)
print(f"Created: {len(created)}, Failed: {len(failed)}")

Next Steps

After creating an employee, you’ll typically want to:

Add Commuting Period: Create a commuting period to track their transportation
Send Survey: Use the survey feature to collect commuting data from the employee
View Emissions: Retrieve the employee to see calculated CO2e

Create Commuting Period

Add commuting data for the employee

List Employees

View all employees and their emissions

Employee Commuting Guide

Learn about tracking commuting emissions

Update Employee

Modify employee details

Introduction

Logistics

Vehicles

Unknown Vehicles

Vehicle Fuels

Business Travels

Employees

Commuting Periods

Create Employee

Create Employee

Request

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

Use Cases

Create Employee with Full Details

Create Employee for Survey

Create Employee and Add Commuting Period

Bulk Create Employees

Next Steps

Create Commuting Period

List Employees

Employee Commuting Guide

Update Employee

Introduction

Logistics

Vehicles

Unknown Vehicles

Vehicle Fuels

Business Travels

Employees

Commuting Periods

​Create Employee

​Request

​Headers

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​422 Validation Error

​Use Cases

​Create Employee with Full Details

​Create Employee for Survey

​Create Employee and Add Commuting Period

​Bulk Create Employees

​Next Steps

Create Commuting Period

List Employees

Employee Commuting Guide

Update Employee

Create Employee

Request

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

Use Cases

Create Employee with Full Details

Create Employee for Survey

Create Employee and Add Commuting Period

Bulk Create Employees

Next Steps