Skip to main content
GET
Get Import Status
← Imports Retrieve the current lifecycle status and validation summary of an import session. Use this to check whether a session is ready to submit, or to monitor progress after submission.

Request

Headers

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

Path Parameters

string
required
UUID of the import sessionExample: "11111111-1111-1111-1111-111111111111"

Response

string
UUID of the import session
string
Current lifecycle statusValues: created, parsed, mapped, validating, validated, submitting, submitted, failed, expired
string
Backend template identifier used for this import
string
Original filename of the uploaded file
string | null
Numeric locale applied during parsing
string | null
Date locale applied (dmy or mdy)
integer
Total number of data rows
integer
Number of rows that passed validation
integer
Number of rows with validation errors
object
Error counts per column key. Example: {"weight_kg": 3, "date": 1}
object | null
Confirmed column mapping ({target_column: source_column}) or null if not yet mapped
string | null
UUID of the file created after submission
string | null
UUID of the file the session reads: the spreadsheet that was uploaded, as opposed to file_id, the file the submission generates. Null once that file is deleted.
string | null
UUID of the downstream processing job started after submission
array[string]
Column headers detected in the source file
array[string]
Every sheet name of the uploaded workbook, in workbook order. Empty for CSV and legacy XLS files and for sessions created before 2026-10-08. Use it to let the user pick another sheet of a session being resumed.
string | null
The sheet that was parsed (null for CSV and legacy XLS)
object
The session’s values for the template’s required and submit context fields, as create, validate or submit stored them. Example: {"facility_id": "3f1e…"} for wastes. Other context the session keeps internally is not returned.
object
The value mappings the last validation applied, including suggestions it applied on its own, in the shape Validate takes: {target_column: {raw_value: canonical_value}}. Confirming a mapping clears them.
object | null
Custom columns declared in this session and not created yet (they are created on submit): template, the import template with them added as columns, and columns, each declared column with its source_header and the key it got. Null when none is declared.
boolean
True when the session is validated and nothing changed its data since: on templates that track data revisions, a row correction, an added or deleted row, or a declared custom column makes it false until the next validation, and Submit answers 409 IMPORT_VALIDATION_STALE while it is false. On other templates it is true for any validated session.
datetime
ISO 8601 timestamp when the session was created
string | null
ISO 8601 timestamp of the last update

Example

Successful Response

Session Status Lifecycle

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

403 Forbidden

Cause: The authenticated user is not a member of the organization

404 Not Found

Cause: The import session does not exist or belongs to another organization. Both cases return the same response, so a session id from another organization is indistinguishable from one that does not exist.
Cause: The session’s project is no longer one your organization can import into (for example, the organization was unlinked from it). Every step of the session answers this, not only the submit. Create a new session on a project you work in.

Create Session

Upload a file and start a new import

Submit Import

Submit the validated session