Create Import Session

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    template_id: '<string>',
    numeric_locale: '<string>',
    date_locale: '<string>',
    language_locale: '<string>',
    sheet_name: '<string>',
    project_id: '<string>',
    folder_id: '<string>',
    facility_id: '<string>',
    transport_direction: '<string>',
    context_task_id: '<string>'
  })
};

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

import requests

url = "https://api.dcycle.io/v2/imports/sessions"

payload = {
    "template_id": "<string>",
    "numeric_locale": "<string>",
    "date_locale": "<string>",
    "language_locale": "<string>",
    "sheet_name": "<string>",
    "project_id": "<string>",
    "folder_id": "<string>",
    "facility_id": "<string>",
    "transport_direction": "<string>",
    "context_task_id": "<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/v2/imports/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "template_id": "<string>",
  "numeric_locale": "<string>",
  "date_locale": "<string>",
  "language_locale": "<string>",
  "sheet_name": "<string>",
  "project_id": "<string>",
  "folder_id": "<string>",
  "facility_id": "<string>",
  "transport_direction": "<string>",
  "context_task_id": "<string>"
}
'

{
  "import_id": "<string>",
  "file_name": "<string>",
  "total_rows": 123,
  "numeric_locale": {},
  "date_locale": {},
  "sheets": {},
  "selected_sheet": {},
  "detected_header_row": 123,
  "source_columns": {},
  "sample_rows": {}
}

POST

imports

sessions

Create Import Session

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    template_id: '<string>',
    numeric_locale: '<string>',
    date_locale: '<string>',
    language_locale: '<string>',
    sheet_name: '<string>',
    project_id: '<string>',
    folder_id: '<string>',
    facility_id: '<string>',
    transport_direction: '<string>',
    context_task_id: '<string>'
  })
};

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

import requests

url = "https://api.dcycle.io/v2/imports/sessions"

payload = {
    "template_id": "<string>",
    "numeric_locale": "<string>",
    "date_locale": "<string>",
    "language_locale": "<string>",
    "sheet_name": "<string>",
    "project_id": "<string>",
    "folder_id": "<string>",
    "facility_id": "<string>",
    "transport_direction": "<string>",
    "context_task_id": "<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/v2/imports/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "template_id": "<string>",
  "numeric_locale": "<string>",
  "date_locale": "<string>",
  "language_locale": "<string>",
  "sheet_name": "<string>",
  "project_id": "<string>",
  "folder_id": "<string>",
  "facility_id": "<string>",
  "transport_direction": "<string>",
  "context_task_id": "<string>"
}
'

{
  "import_id": "<string>",
  "file_name": "<string>",
  "total_rows": 123,
  "numeric_locale": {},
  "date_locale": {},
  "sheets": {},
  "selected_sheet": {},
  "detected_header_row": 123,
  "source_columns": {},
  "sample_rows": {}
}

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.

This is the entry point for every import. After creating a session, proceed to Suggest Mapping to auto-map source columns, then validate and submit.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Body (multipart/form-data)

string

required

Backend template identifier. Determines which columns are expected and how values are validated.Examples: logistics_requests, purchases, wastes, invoices_electricityFor the own workforce templates — own_workforce, own_workforce_trainings and own_workforce_accidents_absenteeisms — see Own Workforce Import Templates.

file

required

The source CSV or XLSX file to import

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)

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.

string

Language hint for header detection and value matchingExample: es, en, fr

string

Sheet to read for multi-sheet XLSX uploads. When omitted on a multi-sheet file, the first sheet is used.

string

UUID of the project to scope this import toRetrieve available options from GET /v1/projects/extended

string

UUID of the folder within the project

string

UUID of the facility. Required for templates that declare facility_id as a context field (e.g. wastes, invoices_electricity).Retrieve available options from GET /v1/facilities

string

Transport direction. Required for transport_routes template.Values: upstream, downstream

string

UUID of the task this import was started from. Optional. When set, the source file is linked to that task and comes back in its files on GET /v1/tasks/{task_id}.

Response

string

UUID of the created import session. Use this in all subsequent workflow calls.

string

Original filename of the uploaded file

integer

Number of data rows parsed (excluding header)

string | null

The numeric locale applied during parsing

string | null

The date locale applied (dmy or mdy), or null if auto-detected

array[string]

List of sheet names in the workbook (empty for CSV)

string | null

The sheet that was parsed

integer

Zero-based index of the detected header row

array[string]

Column headers detected in the source file

array[array]

First few rows of parsed data for preview

Example

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"

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

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(', ')}`);
});

Successful Response

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

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

400 Bad Request

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

{
  "detail": "Could not parse the uploaded file."
}

422 Unprocessable Entity

Cause: Missing required context field for the template

{
  "detail": "facility_id is required for template 'wastes'"
}

Import Overview

Full import workflow guide

Get Import Status

Check session status and validation summary

Submit Import

Submit the validated session for processing

Delete Session

Abandon and clean up a session

​Request

​Headers

​Body (multipart/form-data)

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​400 Bad Request

​422 Unprocessable Entity

​Related Endpoints

Import Overview

Get Import Status

Submit Import

Delete Session

Request

Headers

Body (multipart/form-data)

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

400 Bad Request

422 Unprocessable Entity

Related Endpoints