curl -X POST "https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d/import-sessions" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "Content-Type: application/json" \
-d '{ "template_id": "wastes", "sheet_name": "Enero" }'
import os
import requests
response = requests.post(
"https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d/import-sessions",
headers={"x-api-key": os.environ["DCYCLE_API_KEY"], "x-organization-id": os.environ["DCYCLE_ORG_ID"]},
json={"template_id": "wastes", "sheet_name": "Enero"},
)
print(response.status_code, response.json()["import_id"])
{
"import_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"file_name": "residuos-enero.xlsx",
"total_rows": 412,
"numeric_locale": null,
"date_locale": null,
"language_locale": null,
"sheets": ["Enero", "Instrucciones"],
"selected_sheet": "Enero",
"detected_header_row": 0,
"header_row_candidates": [],
"source_columns": ["Fecha", "Código LER", "Cantidad"],
"sample_rows": [["2026-01-02", "150101", 120.5]],
"sheet_suggestion": null,
"sheet_profiles": null
}
{
"type": "https://code.dcycle.io/api-reference/errors#SHEET_REQUIRED",
"title": "Unprocessable Entity",
"status": 422,
"code": "SHEET_REQUIRED",
"detail": "Sheet required.",
"error_params": {
"sheets": [
{ "name": "Enero", "rows": 412, "date_min": "2026-01-02", "date_max": "2026-01-31" },
{ "name": "Instrucciones", "rows": 8, "date_min": null, "date_max": null }
]
},
"request_id": "b2248a31-0f1b-4a7d-83ce-b29bd5977b4c"
}
Open an Import Session
Open the import session of a spreadsheet you uploaded
POST
/
v2
/
files
/
{file_id}
/
import-sessions
curl -X POST "https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d/import-sessions" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "Content-Type: application/json" \
-d '{ "template_id": "wastes", "sheet_name": "Enero" }'
import os
import requests
response = requests.post(
"https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d/import-sessions",
headers={"x-api-key": os.environ["DCYCLE_API_KEY"], "x-organization-id": os.environ["DCYCLE_ORG_ID"]},
json={"template_id": "wastes", "sheet_name": "Enero"},
)
print(response.status_code, response.json()["import_id"])
{
"import_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"file_name": "residuos-enero.xlsx",
"total_rows": 412,
"numeric_locale": null,
"date_locale": null,
"language_locale": null,
"sheets": ["Enero", "Instrucciones"],
"selected_sheet": "Enero",
"detected_header_row": 0,
"header_row_candidates": [],
"source_columns": ["Fecha", "Código LER", "Cantidad"],
"sample_rows": [["2026-01-02", "150101", 120.5]],
"sheet_suggestion": null,
"sheet_profiles": null
}
{
"type": "https://code.dcycle.io/api-reference/errors#SHEET_REQUIRED",
"title": "Unprocessable Entity",
"status": 422,
"code": "SHEET_REQUIRED",
"detail": "Sheet required.",
"error_params": {
"sheets": [
{ "name": "Enero", "rows": 412, "date_min": "2026-01-02", "date_max": "2026-01-31" },
{ "name": "Instrucciones", "rows": 8, "date_min": null, "date_max": null }
]
},
"request_id": "b2248a31-0f1b-4a7d-83ce-b29bd5977b4c"
}
← Files
Open the session that imports a file, for a template, without sending the file again.
Templates that ask for other context take the fields of
201 Created when it creates the
session, 200 OK when it reuses one that was open for this file and template. Sending another sheet_name or
header_row than the open session’s replaces it, with what had been done in it, and answers 201.
It always answers a session or an error, never a list of tabs in place of a session: a workbook with several tabs and
no sheet_name is 422 SHEET_REQUIRED, with the tabs in error_params.sheets.
Beta. Part of the Import API, in beta. The contract may still change before general availability.
curl -X POST "https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d/import-sessions" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "Content-Type: application/json" \
-d '{ "template_id": "wastes", "sheet_name": "Enero" }'
import os
import requests
response = requests.post(
"https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d/import-sessions",
headers={"x-api-key": os.environ["DCYCLE_API_KEY"], "x-organization-id": os.environ["DCYCLE_ORG_ID"]},
json={"template_id": "wastes", "sheet_name": "Enero"},
)
print(response.status_code, response.json()["import_id"])
{
"import_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"file_name": "residuos-enero.xlsx",
"total_rows": 412,
"numeric_locale": null,
"date_locale": null,
"language_locale": null,
"sheets": ["Enero", "Instrucciones"],
"selected_sheet": "Enero",
"detected_header_row": 0,
"header_row_candidates": [],
"source_columns": ["Fecha", "Código LER", "Cantidad"],
"sample_rows": [["2026-01-02", "150101", 120.5]],
"sheet_suggestion": null,
"sheet_profiles": null
}
{
"type": "https://code.dcycle.io/api-reference/errors#SHEET_REQUIRED",
"title": "Unprocessable Entity",
"status": 422,
"code": "SHEET_REQUIRED",
"detail": "Sheet required.",
"error_params": {
"sheets": [
{ "name": "Enero", "rows": 412, "date_min": "2026-01-02", "date_max": "2026-01-31" },
{ "name": "Instrucciones", "rows": 8, "date_min": null, "date_max": null }
]
},
"request_id": "b2248a31-0f1b-4a7d-83ce-b29bd5977b4c"
}
Request
Path Parameters
string
required
The file’s id: an uploaded spreadsheet (
csv, xlsx, xls) of the organization in x-organization-id.Headers
string
required
Your API key.
string
required
The organization that owns the file.
Body
Unknown fields are rejected.string
required
The import template.
string
The tab to import. Required for a workbook with several tabs. See Get a File’s Sheets.
integer
The 0-based row with the column names. Without it, the one detected.
string
The facility, for templates that ask for one. Without it, the one the file was uploaded with.
string
upstream or downstream, for templates that ask for one. Without it, the one the file was uploaded with.POST /v2/imports/sessions: block_id, lca_distribution_name,
weight_type, product_weight, target_organization_id, measurement_campaign_id, lca_id, target_block_id and
negative_purchases.
Response
The session, asPOST /v2/imports/sessions answers it. import_id is what the importer’s next routes take
(mapping, validate, submit). A context field the template requires and nobody sent does not stop the session: it
is asked for at submit.
Errors
Errors are problem details.404 NOT_FOUND, 422 SHEET_REQUIRED, 422 FILE_NOT_IMPORTABLE
(an unknown template, a file that is not an uploaded spreadsheet or has no rows), 403 IMPORT_TEMPLATE_NOT_IN_PLAN,
400 IMPORT_FILE_TOO_LARGE, 503 IMPORT_HEAVY_OPERATION_BUSY, 422 REQUEST_VALIDATION_FAILED, the importer’s own
errors about the context it was sent, and 429 beyond the rate limits.
Related Endpoints
Get a File's Sheets
The tabs of a workbook
Upload a File (v2)
Upload one file in one call
Was this page helpful?