curl "https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}"
import os
import requests
response = requests.get(
"https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d",
headers={"x-api-key": os.environ["DCYCLE_API_KEY"], "x-organization-id": os.environ["DCYCLE_ORG_ID"]},
)
print(response.json()["auto_import"])
{
"id": "6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d",
"name": "residuos-enero",
"extension": "xlsx",
"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"size_kb": 84,
"status": "needs_review",
"step": "awaiting_mapping",
"reason": null,
"actions": ["map_columns"],
"review_url": "https://app.dcycle.io/acme/a8315ef3-dd50-43f8-b7ce-d839e68d51fa/data/files/upload?run=tabular:6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d&run_file=6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d",
"organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
"folder_id": null,
"facility_id": "9b2e4c1a-6d3f-4e8b-a7c5-1f0d2e3b4a59",
"transport_direction": null,
"project_id": null,
"classifications": [{ "document_type": "document::wastes", "confidence": 0.9 }],
"template_id": "wastes",
"duplicate": null,
"auto_import": {
"state": "held",
"reason": "validation_errors",
"step": "validate",
"import_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
},
"created_at": "2026-11-05T17:20:04Z",
"updated_at": "2026-11-05T17:20:09Z"
}
Get a File (v2)
A file’s state: its classification, its template and its automatic import
GET
/
v2
/
files
/
{file_id}
curl "https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}"
import os
import requests
response = requests.get(
"https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d",
headers={"x-api-key": os.environ["DCYCLE_API_KEY"], "x-organization-id": os.environ["DCYCLE_ORG_ID"]},
)
print(response.json()["auto_import"])
{
"id": "6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d",
"name": "residuos-enero",
"extension": "xlsx",
"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"size_kb": 84,
"status": "needs_review",
"step": "awaiting_mapping",
"reason": null,
"actions": ["map_columns"],
"review_url": "https://app.dcycle.io/acme/a8315ef3-dd50-43f8-b7ce-d839e68d51fa/data/files/upload?run=tabular:6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d&run_file=6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d",
"organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
"folder_id": null,
"facility_id": "9b2e4c1a-6d3f-4e8b-a7c5-1f0d2e3b4a59",
"transport_direction": null,
"project_id": null,
"classifications": [{ "document_type": "document::wastes", "confidence": 0.9 }],
"template_id": "wastes",
"duplicate": null,
"auto_import": {
"state": "held",
"reason": "validation_errors",
"step": "validate",
"import_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
},
"created_at": "2026-11-05T17:20:04Z",
"updated_at": "2026-11-05T17:20:09Z"
}
← Files
Read how a file goes after uploading it. A file of another organization, or in the
trash, answers the same
404 as one that does not exist.
Beta. Part of the Import API, in beta. The contract may still change before general availability.
curl "https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}"
import os
import requests
response = requests.get(
"https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d",
headers={"x-api-key": os.environ["DCYCLE_API_KEY"], "x-organization-id": os.environ["DCYCLE_ORG_ID"]},
)
print(response.json()["auto_import"])
{
"id": "6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d",
"name": "residuos-enero",
"extension": "xlsx",
"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"size_kb": 84,
"status": "needs_review",
"step": "awaiting_mapping",
"reason": null,
"actions": ["map_columns"],
"review_url": "https://app.dcycle.io/acme/a8315ef3-dd50-43f8-b7ce-d839e68d51fa/data/files/upload?run=tabular:6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d&run_file=6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d",
"organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
"folder_id": null,
"facility_id": "9b2e4c1a-6d3f-4e8b-a7c5-1f0d2e3b4a59",
"transport_direction": null,
"project_id": null,
"classifications": [{ "document_type": "document::wastes", "confidence": 0.9 }],
"template_id": "wastes",
"duplicate": null,
"auto_import": {
"state": "held",
"reason": "validation_errors",
"step": "validate",
"import_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
},
"created_at": "2026-11-05T17:20:04Z",
"updated_at": "2026-11-05T17:20:09Z"
}
Request
Path Parameters
string
required
The file’s id, from
POST /v2/files or the presigned flow.Headers
string
required
Your API key.
string
required
The organization that owns the file.
Response
string
What to branch on. Poll while it is
processing.status | Meaning | step |
|---|---|---|
processing | Dcycle is working on it | uploading, classifying, processing, calculating |
needs_review | Someone has to act: see actions and review_url | awaiting_duplicate_review, awaiting_classification_confirmation, awaiting_mapping, awaiting_dataset_import, awaiting_review, not_calculated |
completed | Nothing is left to do | completed, completed_with_errors, and not_processed when you asked for skip_processing or it went in an evidence folder |
failed | It stopped: see reason | error, upload_limit_reached, and not_processed in any other case: the file is stored, but nothing was read from it |
string
The real step behind
status, for more detail. New values may appear: branch on status.object
Why it failed, or what went wrong in part:
code, message (for people; do not parse it) and retryable. NOT_PROCESSED
and UPLOAD_LIMIT_REACHED are not retryable. Null otherwise.array
What can be done with it now, as stable identifiers such as
map_columns. Empty when there is nothing to do.string
Where a person reviews it in the Dcycle app: the file in the upload flow or, for an organization that does not have
that flow yet, My files. Only when it
needs_review.array
Empty until it is classified; one per service found in the file, each with
document_type and confidence (0 to 1,
and 1 for a person’s confirmation).string
The import template its classification leads straight to. Null when there is none: then
open the session with the template you choose.
object
Set while the file is held back because its bytes match another file of the organization: its
status is
needs_review until someone decides. Has status (suspected) and duplicate_of_file_id.object
Where the automatic import of a spreadsheet stands. Null when it did not run for this file: that is every file while
the feature is not on for your organization. A spreadsheet’s job starts after its classification, so this can be null
for some seconds after
classifications fills.Show fields
Show fields
string
running: queued or running. imported: its submit was accepted, and the rows are being saved. held: it
stopped at the first problem and left the session as it was, for a person to continue. failed: it could not finish.string
Why it was
held: a short machine-readable reason, such as validation_errors, validation_ambiguous,
too_large, unreadable, already_submitted or missing_context:facility_id. Null otherwise.string
The last step it reached, such as
ensure, suggest, mapping, unique_values, validate or submit. Null while
it is running. For information: do not branch on it.string
The import session it worked on, if it opened one. Continue from it with the importer’s routes.
The answer carries no download URL. A file’s bytes are read with
GET /v1/files/{file_id}.Errors
Errors are problem details.404 NOT_FOUND, 422 REQUEST_VALIDATION_FAILED (an id that is not
a UUID), and 429 beyond the rate limits.
Related Endpoints
Upload a File (v2)
Upload one file in one call
Get a File's Sheets
The tabs of a workbook
Open an Import Session
Import a spreadsheet you uploaded
Was this page helpful?