Get import job status

GET https://api.veriko.mx/v1/beneficiaries/imports/{id}

Audience: public
Auth: API key
Permission: beneficiaries:create

Returns the job status and per-bucket counters: valid, correctable, fatal, duplicate_account (summed in duplicate_count) and committed/skipped post-commit. Poll this endpoint every 2 s until status is preview_ready, completed, failed or cancelled.

Parameters
Parameter	In	Type	Required	Description
`id` *	path	`integer`	required	Numeric ID of the import job.

Request

cURLPython•JavaScript•PHP•

curl -X GET 'https://api.veriko.mx/v1/beneficiaries/imports/{id}' \
  -H 'Authorization: Bearer mxcep_••••'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200** `BeneficiaryImportJobResponse` — Current job status with per-bucket counters.
Field	Type	Description
`type`	`string`	JSON:API resource type (always `beneficiary_import`).
`id`	`string`	Numeric job ID expressed as a string (JSON:API format).
`attributes`	`object`	Import job fields.
`status`	`string`	Job status: `pending` — uploaded, awaiting parsing; `parsing` — extracting rows; `preview_ready` — ready for user review; `committing` — persisting confirmed rows; `completed` — commit finished; `failed` — non-recoverable failure (see `error_code`); `cancelled` — cancelled by the user.
`file_format`	`string`	Format of the uploaded file. Accepted: CSV, Excel (xls/xlsx), plain text, and PDF.
`parse_mode`	`string`	Parse mode: `template` — fixed column format (downloadable from `/v1/beneficiaries/imports/template`); `free` — free-form, the system infers the structure.
`total_rows`	`integer`	Total rows extracted from the file. Available once status is `preview_ready` or later.
`valid_count`	`integer`	Error-free rows, ready for direct commit.
`correctable_count`	`integer`	Rows with auto-corrections applied (e.g. auto-assigned alias). Persisted unless the user rejects them.
`fatal_count`	`integer`	Rows with errors that cannot be auto-corrected. Not persisted and skipped during commit.
`duplicate_count`	`integer`	Sum of `duplicate_account` and `duplicate_alias` rows. `duplicate_account` rows are skipped unless the account is archived (in which case it is reactivated); `duplicate_alias` rows are persisted with an alias suffix.
`committed_count`	`integer`	Rows effectively persisted in the beneficiary list. Available once status is `completed`.
`skipped_count`	`integer`	Rows not persisted (fatal or `duplicate_account` without possible reactivation).
`llm_invoked`	`boolean`	`true` if the AI engine was used during parsing to resolve ambiguous rows in free-form mode.
`error_code`	`string \| null` nullable	Stable error code when `status=failed` (e.g. `file_corrupt`, `plan_cap_exceeded`). `null` in non-failed states.
`error_summary`	`string \| null` nullable	Human-readable diagnostic message when `status=failed`. Card numbers (PANs) are masked in this field.
`created_at`	`string (date-time)`	ISO 8601 timestamp in UTC with explicit `Z` suffix. Example: `"2026-05-01T05:14:38Z"`. Every datetime field uses this shape. The descriptor at `meta.datetime` makes the contract runtime-assertable.
`parsed_at`	`string \| null` nullable	ISO 8601 UTC timestamp when parsing completed. `null` until parsing finishes.
`committed_at`	`string \| null` nullable	ISO 8601 UTC timestamp when commit started. `null` until commit begins.
`completed_at`	`string \| null` nullable	ISO 8601 UTC timestamp when the job completed. `null` while the job has not finished.

**Response status codes** `GET /v1/beneficiaries/imports/{id}`
Status	Class	Description	Body
200	`2xx`	Current job status with per-bucket counters.	`BeneficiaryImportJobResponse`
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
404	`4xx`	The resource does not exist or is not visible to the caller	`Error`

**Errors from `GET /v1/beneficiaries/imports/{id}`**
Status	Code	Detail
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c0`