> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CSV Import

> Bulk create employees from a CSV file and send survey emails

# CSV Import

Create multiple employees from a CSV file and automatically send commuting survey emails to each one. The CSV must contain at least an `email` column.

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `multipart/form-data`
</ParamField>

### Form Parameters

<ParamField body="file" type="file" required>
  CSV file with at least an `email` column header
</ParamField>

<ParamField body="lang" type="string" required>
  Survey language code. Values: `ar`, `ca`, `de`, `en`, `es`, `fr`, `it`, `pt`, `zh`
</ParamField>

<ParamField body="start_date" type="string" required>
  Survey period start date (`YYYY-MM-DD`)
</ParamField>

<ParamField body="end_date" type="string" required>
  Survey period end date (`YYYY-MM-DD`)
</ParamField>

<ParamField body="subject" type="string" required>
  Email subject line (1–255 characters)
</ParamField>

<ParamField body="deadline" type="string">
  Survey response deadline (`YYYY-MM-DD`). After this date, the survey link expires.
</ParamField>

## Response

Returns an array of created employees (HTTP 201).

<ResponseField name="id" type="string">
  Unique identifier (UUID) for the employee
</ResponseField>

<ResponseField name="name" type="string | null">
  Employee's full name
</ResponseField>

<ResponseField name="email" type="string | null">
  Employee's email address
</ResponseField>

<ResponseField name="organization_id" type="string">
  Organization UUID
</ResponseField>

<ResponseField name="situation" type="string | null">
  Employment status: `active`, `inactive`, or `terminated`
</ResponseField>

<ResponseField name="status" type="string">
  Data status: `uploaded` or `loading`
</ResponseField>

<ResponseField name="periods" type="array | null">
  List of commuting periods (empty for newly imported employees)
</ResponseField>

<ResponseField name="created_at" type="datetime">
  Timestamp when the employee was created
</ResponseField>

<ResponseField name="updated_at" type="datetime | null">
  Timestamp when the employee was last updated
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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`);
  });
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
```

### 403 Forbidden

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}
```

### 422 Unprocessable Entity

**Cause:** Invalid CSV format or missing required columns

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["body", "file"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Employee" icon="user-plus" href="/api-reference/employees/create">
    Create a single employee
  </Card>

  <Card title="Resend Survey" icon="paper-plane" href="/api-reference/employees/resend-survey">
    Resend survey to existing employees
  </Card>
</CardGroup>