Skip to main content
POST
/
v1
/
employees
Create Employee
const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: '<string>', email: '<string>', situation: '<string>', status: '<string>'})
};

fetch('https://api.dcycle.io/v1/employees', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "<string>",
  "name": {},
  "email": {},
  "organization_id": "<string>",
  "situation": {},
  "status": "<string>",
  "periods": {},
  "created_at": {},
  "updated_at": {}
}

​
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"
​
email
string
Employee’s email addressRequired if name is not providedExample: "john.smith@company.com"
​
situation
string
required
Employment situationAvailable values: active, inactive, terminatedExample: "active"
​
status
string
required
Data collection statusAvailable values: uploaded, loadingExample: "uploaded"

​
Response

​
id
string
Unique identifier (UUID) for the employee
​
name
string | null
Employee’s full name
​
email
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": "john.smith@company.com",
    "situation": "active",
    "status": "uploaded"
  }'

​
Successful Response

{
  "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": 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="john@company.com"
)
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 = ["alice@company.com", "bob@company.com", "carol@company.com"]
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="john@company.com",
    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": "alice@company.com"},
    {"name": "Bob Williams", "email": "bob@company.com"},
    {"name": "Carol Davis", "email": "carol@company.com"},
]

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:
  1. Add Commuting Period: Create a commuting period to track their transportation
  2. Send Survey: Use the survey feature to collect commuting data from the employee
  3. 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