Skip to main content
POST
/
v2
/
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>'
  })
};

fetch('https://api.dcycle.io/v2/imports/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "import_id": "<string>",
  "file_name": "<string>",
  "total_rows": 123,
  "numeric_locale": {},
  "date_locale": {},
  "sheets": {},
  "selected_sheet": {},
  "detected_header_row": 123,
  "source_columns": {},
  "sample_rows": {}
}

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

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Body (multipart/form-data)

​
template_id
string
required
Backend template identifier. Determines which columns are expected and how values are validated.Examples: logistics_requests, purchases, wastes, invoices_electricity
​
upload_file
file
required
The source CSV or XLSX file to import
​
numeric_locale
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)
​
date_locale
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.
​
language_locale
string
Language hint for header detection and value matchingExample: es, en, fr
​
sheet_name
string
Sheet to read for multi-sheet XLSX uploads. When omitted on a multi-sheet file, the first sheet is used.
​
project_id
string
UUID of the project to scope this import to
​
folder_id
string
UUID of the folder within the project
​
facility_id
string
UUID of the facility. Required for templates that declare facility_id as a context field (e.g. wastes, invoices_electricity).
​
transport_direction
string
Transport direction. Required for transport_routes template.Values: upstream, downstream

​
Response

​
import_id
string
UUID of the created import session. Use this in all subsequent workflow calls.
​
file_name
string
Original filename of the uploaded file
​
total_rows
integer
Number of data rows parsed (excluding header)
​
numeric_locale
string | null
The numeric locale applied during parsing
​
date_locale
string | null
The date locale applied (dmy or mdy), or null if auto-detected
​
sheets
array[string]
List of sheet names in the workbook (empty for CSV)
​
selected_sheet
string | null
The sheet that was parsed
​
detected_header_row
integer
Zero-based index of the detected header row
​
source_columns
array[string]
Column headers detected in the source file
​
sample_rows
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"

​
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