CSV Upload

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({file_name: '<string>'})
};

fetch('https://api.dcycle.io/v1/employee-historic/bulk/csv', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/employee-historic/bulk/csv"

payload = { "file_name": "<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/employee-historic/bulk/csv \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "file_name": "<string>"
}
'

{
  "upload_url": "<string>",
  "file_name": "<string>",
  "file_id": "<string>",
  "destination_file_key": "<string>",
  "message": "<string>",
  "organization_id": "<string>"
}

POST

employee-historic

bulk

csv

CSV Upload

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({file_name: '<string>'})
};

fetch('https://api.dcycle.io/v1/employee-historic/bulk/csv', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/employee-historic/bulk/csv"

payload = { "file_name": "<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/employee-historic/bulk/csv \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "file_name": "<string>"
}
'

{
  "upload_url": "<string>",
  "file_name": "<string>",
  "file_id": "<string>",
  "destination_file_key": "<string>",
  "message": "<string>",
  "organization_id": "<string>"
}

CSV Upload

Generate a presigned S3 URL for bulk importing employee commuting periods via CSV. After uploading the file, the system processes each row to create commuting period records and trigger emission calculations.

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

required

Name of the CSV file to uploadExample: commuting-data-2025.csv

CSV Format

The CSV file should contain the following columns:

Column	Required	Description
`employee_email`	Yes	Employee email for lookup
`employee_name`	No	Employee name (fallback if email not found)
`start_date`	Yes	Period start date (YYYY-MM-DD)
`end_date`	Yes	Period end date (YYYY-MM-DD)
`commuting_type`	Yes	`in_itinere` or `in_labore`
`transport_type`	Yes	car, bus, metro, train, bicycle, walking, telecommuting, etc.
`vehicle_size`	Conditional	small/medium/large (required for car)
`fuel_type`	Conditional	petrol, diesel, electric, hybrid, etc.
`renewable_energy`	Conditional	yes/no/do_not_know (for electric vehicles)
`carpool`	Conditional	true/false (required for car)
`total_km`	Yes	Distance per trip (km)
`daily_trips`	Yes	Number of daily trips
`weekly_travels`	No	Days of week, semicolon-separated (e.g., `0;1;2;3;4` for Mon-Fri)
`origin`	No	Origin address
`destination`	No	Destination address

Response

string

Presigned S3 URL — upload your CSV via PUT to this URL

string

File name as stored

string

UUID of the created file record

string

S3 object key where the file will be stored

string

Confirmation message

string

UUID of the organization the file belongs to

Example

# Step 1: Get presigned URL
RESPONSE=$(curl -s -X POST "https://api.dcycle.io/v1/employee-historic/bulk/csv" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{"file_name": "commuting-data-2025.csv"}')

# Step 2: Upload CSV to presigned URL
UPLOAD_URL=$(echo $RESPONSE | jq -r '.upload_url')
curl -X PUT "$UPLOAD_URL" -H "Content-Type: text/csv" --data-binary @commuting-data-2025.csv

echo "File ID: $(echo $RESPONSE | jq -r '.file_id')"

import requests
import os

# Step 1: Get presigned URL
response = requests.post(
    "https://api.dcycle.io/v1/employee-historic/bulk/csv",
    headers={
        "x-api-key": os.getenv("DCYCLE_API_KEY"),
        "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
        "Content-Type": "application/json",
    },
    json={"file_name": "commuting-data-2025.csv"},
)

result = response.json()

# Step 2: Upload CSV
with open("commuting-data-2025.csv", "rb") as f:
    requests.put(result["upload_url"], data=f, headers={"Content-Type": "text/csv"})

print(f"File ID: {result['file_id']}")

const axios = require('axios');
const fs = require('fs');

// Step 1: Get presigned URL
const { data } = await axios.post('https://api.dcycle.io/v1/employee-historic/bulk/csv', {
  file_name: 'commuting-data-2025.csv',
}, {
  headers: {
    'x-api-key': process.env.DCYCLE_API_KEY,
    'x-organization-id': process.env.DCYCLE_ORG_ID,
    'Content-Type': 'application/json',
  },
});

// Step 2: Upload CSV
const csv = fs.readFileSync('commuting-data-2025.csv');
await axios.put(data.upload_url, csv, { headers: { 'Content-Type': 'text/csv' } });

console.log(`File ID: ${data.file_id}`);

Successful Response

{
  "upload_url": "https://s3.eu-west-1.amazonaws.com/dcycle-uploads/...",
  "file_name": "commuting-data-2025.csv",
  "file_id": "file-uuid",
  "destination_file_key": "organizations/org-uuid/employee-commuting/file-uuid.csv",
  "message": "Upload URL generated successfully",
  "organization_id": "org-uuid"
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

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

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

422 Unprocessable Entity

Cause: Missing required field (file_name)

{
  "detail": [
    {
      "loc": ["body", "file_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

List Commuting Periods

Browse imported commuting periods

Create Commuting Period

Create a single commuting period manually

​CSV Upload

​Request

​Headers

​Body Parameters

​CSV Format

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​Related Endpoints

List Commuting Periods

Create Commuting Period

CSV Upload

Request

Headers

Body Parameters

CSV Format

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

Related Endpoints