> ## 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.

# Create Import Session

> Upload a source file and create a new import session

# Create Import Session

Upload a CSV or XLSX file and create an import session. The backend parses the file, detects column headers, and returns metadata needed to begin the mapping and validation workflow.

<Note>
  This is the entry point for every import. After creating a session, proceed to [Suggest Mapping](/api-reference/imports/suggest-mapping) to auto-map source columns, then [validate](/api-reference/imports/overview#end-to-end-flow) and submit.
</Note>

## 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>

### Body (multipart/form-data)

<ParamField body="template_id" type="string" required>
  Backend template identifier. Determines which columns are expected and how values are validated.

  **Examples:** `logistics_requests`, `purchases`, `wastes`, `invoices_electricity`
</ParamField>

<ParamField body="upload_file" type="file" required>
  The source CSV or XLSX file to import
</ParamField>

<ParamField body="numeric_locale" type="string">
  Locale for decimal number parsing. Use this when your file uses commas as decimal separators.

  **Example:** `es_ES` (parses `1.234,56` as `1234.56`)
</ParamField>

<ParamField body="date_locale" type="string">
  Preferred date format for ambiguous slash-separated dates.

  **Values:** `dmy` (European: 05/04/2026 = April 5th), `mdy` (US: 05/04/2026 = May 4th)

  When omitted, the parser auto-detects from unambiguous values in the column.
</ParamField>

<ParamField body="language_locale" type="string">
  Language hint for header detection and value matching

  **Example:** `es`, `en`, `fr`
</ParamField>

<ParamField body="sheet_name" type="string">
  Sheet to read for multi-sheet XLSX uploads. When omitted on a multi-sheet file, the first sheet is used.
</ParamField>

<ParamField body="project_id" type="string">
  UUID of the project to scope this import to
</ParamField>

<ParamField body="folder_id" type="string">
  UUID of the folder within the project
</ParamField>

<ParamField body="facility_id" type="string">
  UUID of the facility. Required for templates that declare `facility_id` as a context field (e.g. `wastes`, `invoices_electricity`).
</ParamField>

<ParamField body="transport_direction" type="string">
  Transport direction. Required for `transport_routes` template.

  **Values:** `upstream`, `downstream`
</ParamField>

## Response

<ResponseField name="import_id" type="string">
  UUID of the created import session. Use this in all subsequent workflow calls.
</ResponseField>

<ResponseField name="file_name" type="string">
  Original filename of the uploaded file
</ResponseField>

<ResponseField name="total_rows" type="integer">
  Number of data rows parsed (excluding header)
</ResponseField>

<ResponseField name="numeric_locale" type="string | null">
  The numeric locale applied during parsing
</ResponseField>

<ResponseField name="date_locale" type="string | null">
  The date locale applied (`dmy` or `mdy`), or null if auto-detected
</ResponseField>

<ResponseField name="sheets" type="array[string]">
  List of sheet names in the workbook (empty for CSV)
</ResponseField>

<ResponseField name="selected_sheet" type="string | null">
  The sheet that was parsed
</ResponseField>

<ResponseField name="detected_header_row" type="integer">
  Zero-based index of the detected header row
</ResponseField>

<ResponseField name="source_columns" type="array[string]">
  Column headers detected in the source file
</ResponseField>

<ResponseField name="sample_rows" type="array[array]">
  First few rows of parsed data for preview
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.dcycle.io/v2/imports/sessions" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -F "template_id=logistics_requests" \
    -F "numeric_locale=es_ES" \
    -F "upload_file=@./logistics-data.csv;type=text/csv"
  ```

  ```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("logistics-data.csv", "rb") as f:
      response = requests.post(
          "https://api.dcycle.io/v2/imports/sessions",
          headers=headers,
          data={"template_id": "logistics_requests", "numeric_locale": "es_ES"},
          files={"upload_file": ("logistics-data.csv", f, "text/csv")},
      )

  session = response.json()
  print(f"Session created: {session['import_id']}")
  print(f"Rows: {session['total_rows']}, Columns: {session['source_columns']}")
  ```

  ```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('template_id', 'logistics_requests');
  form.append('numeric_locale', 'es_ES');
  form.append('upload_file', fs.createReadStream('./logistics-data.csv'));

  axios.post('https://api.dcycle.io/v2/imports/sessions', form, {
    headers: {
      ...form.getHeaders(),
      'x-api-key': process.env.DCYCLE_API_KEY,
      'x-organization-id': process.env.DCYCLE_ORG_ID,
    },
  }).then(response => {
    const { import_id, total_rows, source_columns } = response.data;
    console.log(`Session: ${import_id}, ${total_rows} rows`);
    console.log(`Columns: ${source_columns.join(', ')}`);
  });
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "import_id": "11111111-1111-1111-1111-111111111111",
  "file_name": "logistics-data.csv",
  "total_rows": 240,
  "numeric_locale": "es_ES",
  "date_locale": null,
  "language_locale": null,
  "sheets": [],
  "selected_sheet": null,
  "detected_header_row": 0,
  "source_columns": ["origin", "destination", "weight_kg", "date", "vehicle_type"],
  "sample_rows": [
    ["Madrid", "Barcelona", "1500", "15/03/2024", "truck"],
    ["Valencia", "Sevilla", "800", "16/03/2024", "van"]
  ]
}
```

## 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"}
```

### 400 Bad Request

**Cause:** File could not be parsed (unsupported format, empty, or corrupt)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Could not parse the uploaded file."
}
```

### 422 Unprocessable Entity

**Cause:** Missing required context field for the template

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "facility_id is required for template 'wastes'"
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Import Overview" icon="upload" href="/api-reference/imports/overview">
    Full import workflow guide
  </Card>

  <Card title="Get Import Status" icon="circle-info" href="/api-reference/imports/get-status">
    Check session status and validation summary
  </Card>

  <Card title="Submit Import" icon="paper-plane" href="/api-reference/imports/submit">
    Submit the validated session for processing
  </Card>

  <Card title="Delete Session" icon="trash" href="/api-reference/imports/delete-session">
    Abandon and clean up a session
  </Card>
</CardGroup>