CSV Import - Dcycle Platform Docs

CSV Import

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({
    lang: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    subject: '<string>',
    deadline: '<string>'
  })
};

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

import requests

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

payload = {
    "lang": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "subject": "<string>",
    "deadline": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "<content-type>"
}

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

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/employees/csv \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "lang": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "subject": "<string>",
  "deadline": "<string>"
}
'

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

POST

employees

csv

CSV Import

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({
    lang: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    subject: '<string>',
    deadline: '<string>'
  })
};

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

import requests

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

payload = {
    "lang": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "subject": "<string>",
    "deadline": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "<content-type>"
}

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

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/employees/csv \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "lang": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "subject": "<string>",
  "deadline": "<string>"
}
'

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

← Employees API Create multiple employees from a CSV or Excel (.xlsx/.xls) file and automatically send commuting survey emails to every email in the file. Emails that already belong to an employee of the organization (matched case-insensitively) are not re-created: the existing employee is reused and surveyed again for the new period, and is included in the response. The file should contain an email column identified by an email, correo, e-mail, or mail header. Extra columns are ignored. A single-column CSV with one email per line (no header) is also accepted; in multi-column files without a recognized header, the column containing email addresses is detected automatically.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

string

required

Must be multipart/form-data

Form Parameters

file

required

CSV or Excel (.xlsx/.xls) file containing an email column (header: email, correo, e-mail, or mail); extra columns are ignored

string

required

Survey language code. Values: ar, ca, de, en, es, fr, it, pt, zh

string

required

Survey period start date (YYYY-MM-DD)

string

required

Survey period end date (YYYY-MM-DD)

string

required

Email subject line (1–255 characters)

string

Survey response deadline (YYYY-MM-DD). After this date, the survey link expires.

Response

Returns an array of created employees (HTTP 201).

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 newly imported 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/csv" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -F "file=@employees.csv" \
  -F "lang=en" \
  -F "start_date=2025-01-01" \
  -F "end_date=2025-12-31" \
  -F "subject=Commuting Survey 2025" \
  -F "deadline=2025-02-28"

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
}

with open("employees.csv", "rb") as f:
    response = requests.post(
        "https://api.dcycle.io/v1/employees/csv",
        headers=headers,
        files={"file": ("employees.csv", f, "text/csv")},
        data={
            "lang": "en",
            "start_date": "2025-01-01",
            "end_date": "2025-12-31",
            "subject": "Commuting Survey 2025",
            "deadline": "2025-02-28",
        },
    )

employees = response.json()
print(f"Created {len(employees)} employees, surveys sent")

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('file', fs.createReadStream('employees.csv'));
form.append('lang', 'en');
form.append('start_date', '2025-01-01');
form.append('end_date', '2025-12-31');
form.append('subject', 'Commuting Survey 2025');
form.append('deadline', '2025-02-28');

axios.post('https://api.dcycle.io/v1/employees/csv', form, {
  headers: {
    ...form.getHeaders(),
    'x-api-key': process.env.DCYCLE_API_KEY,
    'x-organization-id': process.env.DCYCLE_ORG_ID,
  },
})
.then(response => {
  console.log(`Created ${response.data.length} employees`);
});

Successful Response

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": null,
    "email": "jane.doe@example.com",
    "organization_id": "org-uuid",
    "situation": "active",
    "status": "loading",
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z",
    "periods": []
  }
]

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: Invalid CSV format or missing required columns

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

Create Employee

Create a single employee

Resend Survey

Resend survey to existing employees

​Request

​Headers

​Form Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​Related Endpoints

Create Employee

Resend Survey

Request

Headers

Form Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

Related Endpoints