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));

import requests

url = "https://api.dcycle.io/v1/employees"

payload = {
    "name": "<string>",
    "email": "<string>",
    "situation": "<string>",
    "status": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/employees \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "<string>",
  "email": "<string>",
  "situation": "<string>",
  "status": "<string>"
}
'

{
  "id": "<string>",
  "name": {},
  "email": {},
  "organization_id": "<string>",
  "situation": {},
  "status": "<string>",
  "periods": {},
  "created_at": {},
  "updated_at": {}
}

POST

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));

import requests

url = "https://api.dcycle.io/v1/employees"

payload = {
    "name": "<string>",
    "email": "<string>",
    "situation": "<string>",
    "status": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/employees \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "<string>",
  "email": "<string>",
  "situation": "<string>",
  "status": "<string>"
}
'

{
  "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

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body Parameters

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: "john.smith@company.com"

string

required

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

string

required

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

Response

string

Unique identifier (UUID) for the employee

string | null

Employee’s full name

string | null

Employee’s email address

string

Organization UUID

string | null

Employment status: active, inactive, or terminated

string

Data status: uploaded or loading

array | null

List of commuting periods (empty for new employees)

datetime

Timestamp when the employee was created

datetime | null

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"
  }'

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,
    "Content-Type": "application/json"
}

payload = {
    "name": "John Smith",
    "email": "john.smith@company.com",
    "situation": "active",
    "status": "uploaded"
}

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

employee = response.json()
print(f"Employee created: {employee['id']}")
print(f"Name: {employee['name']}")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId,
  'Content-Type': 'application/json'
};

const payload = {
  name: "John Smith",
  email: "john.smith@company.com",
  situation: "active",
  status: "uploaded"
};

axios.post(
  'https://api.dcycle.io/v1/employees',
  payload,
  { headers }
)
.then(response => {
  const employee = response.data;
  console.log(`Employee created: ${employee.id}`);
  console.log(`Name: ${employee.name}`);
})
.catch(error => console.error(error));

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:

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

​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