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

# Open an Import Session

> Open the import session of a spreadsheet you uploaded

[← Files](https://code.dcycle.io/api-reference/files/overview.md)

Open the session that imports a file, for a template, without sending the file again. `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`.

It replaces `POST /v2/imports/sessions/ensure-from-raw`, deprecated since 6 November 2026, which keeps answering as it
did until its removal.

> [!WARNING]
>
> **Beta.** Part of the Import API, in beta. The contract may still change before general availability.

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

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

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

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

**file\_id** `string` *required*

The file's id: an uploaded spreadsheet (`csv`, `xlsx`, `xls`) of the organization in `x-organization-id`.

### Headers

**x-api-key** `string` *required*

Your API key.

**x-organization-id** `string` *required*

The organization that owns the file.

### Body

Unknown fields are rejected.

**template\_id** `string` *required*

The import template.

**sheet\_name** `string`

The tab to import. Required for a workbook with several tabs. See [Get a File's Sheets](https://code.dcycle.io/api-reference/files/sheets-v2.md).

**header\_row** `integer`

The 0-based row with the column names. Without it, the one detected.

**facility\_id** `string`

The facility, for templates that ask for one. Without it, the one the file was uploaded with.

**transport\_direction** `string`

`upstream` or `downstream`, for templates that ask for one. Without it, the one the file was uploaded with.

Templates that ask for other context take the fields of `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, as `POST /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](https://code.dcycle.io/api-reference/errors.md). `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](https://code.dcycle.io/api-reference/rate-limits.md).

## Related Endpoints

> [card] [Get a File's Sheets](https://code.dcycle.io/api-reference/files/sheets-v2.md)
>
> The tabs of a workbook

> [card] [Upload a File (v2)](https://code.dcycle.io/api-reference/files/upload-v2.md)
>
> Upload one file in one call


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.