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

Get import job status

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

Returns the status of an import job and its per-bucket counters: valid, correctable, fatal, duplicate_account (summed in duplicate_count) and committed/skipped after the commit.

The endpoint accepts polling every ~2s 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. e.g. `42`

Request

cURLPython•JavaScript•PHP•

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

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
`data`	`object`	Main response payload. Shape varies by endpoint (object, array, or JSON:API envelope with `type`, `id`, `attributes`).
`type`	`string`	JSON:API resource type. Always `beneficiary_import`. e.g. `beneficiary_import`
`id`	`string`	Numeric job ID expressed as a string (JSON:API format). e.g. `42`
`attributes`	`object`	Import job fields.
`plan_cap`	`object`	Active-beneficiary allowance of the plan and current occupancy of the authenticated account.
`max`	`integer`	Active-beneficiary cap. `-1` means uncapped.
`current`	`integer`	Number of saved active beneficiaries, regardless of the archived filter.
`required`	`integer`	Number of slots needed to create or reactivate accounts in the import job.
`exceeded`	`boolean`	`true` when the import job needs new slots and exceeds the available allowance.
`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. e.g. `preview_ready`
`file_format`	`string`	Format of the uploaded file. Accepted: `csv`, `xls`, `xlsx`, `txt`, `json` or `pdf`. e.g. `csv`
`parse_mode`	`string`	File reading mode — `template`: Follows the canonical headers; `free`: Free-form, the system infers the structure. e.g. `template`
`total_rows`	`integer`	Number of rows extracted from the file. Only available once the status is `preview_ready` or later. e.g. `150`
`valid_count`	`integer`	Number of rows without errors, ready to be committed. e.g. `120`
`correctable_count`	`integer`	Number of rows with errors that can be corrected. They are persisted unless the user rejects them. e.g. `20`
`fatal_count`	`integer`	Number of rows that cannot be processed with their current data. They are not persisted and are skipped on commit. e.g. `5`
`duplicate_count`	`integer`	Number of rows detected as duplicates within the job. Those with `duplicate_account` are skipped on commit, unless the account is archived, in which case it is reactivated; those with `duplicate_alias` are persisted with a suffix on the alias. e.g. `5`
`committed_count`	`integer`	Rows effectively persisted in the beneficiary list. Available once status is `completed`. e.g. `140`
`skipped_count`	`integer`	Number of rows skipped while the job was running. They are the fatal ones and the `duplicate_account` ones with no possible reactivation. e.g. `10`
`llm_invoked`	`boolean`	`true` when the AI engine was used during parsing to resolve ambiguous rows in free-form mode. e.g. `false`
`error_code`	`string \| null`nullable	Stable code of the job failure. `null` when it did not end in `failed`. For example, `file_corrupt` or `empty_file`. e.g. `null`
`error_summary`	`string \| null`nullable	Readable summary of the job failure. `null` when it did not end in `failed`. Card numbers appear masked. e.g. `null`
`created_at`	`string (date-time)`	ISO 8601 timestamp in UTC with an explicit `Z` suffix; for example, `"2026-05-01T05:14:38Z"`. The `_at`, `_end`, `_start`, and `_date` fields follow this format. `meta.datetime` describes the same contract in the response. e.g. `2026-05-01T05:14:38Z`
`parsed_at`	`string \| null`nullable	Date and time when the file reading finished, in ISO 8601 UTC. `null` while it has not finished. e.g. `null`
`committed_at`	`string \| null`nullable	Date and time when the commit started, in ISO 8601 UTC. `null` while it has not been committed. e.g. `null`
`completed_at`	`string \| null`nullable	Date and time of completion, in ISO 8601 UTC. `null` while it has not finished. e.g. `null`
`meta`	`object`	Response metadata including API version, route prefix, unique request identifier, and the server timestamp in UTC.
`version`	`string`	API version that processed the request. e.g. `1.47.0`
`api_version`	`string`	API route prefix version (e.g. `v1`). e.g. `v1`
`request_id`	`string`	Unique request identifier (hex). e.g. `a1b2c3d4e5f66f5e4d3c2b1a`
`datetime`	`object`	Companion descriptor present in the `meta` block of every response (and in the `meta` of outgoing webhook bodies). Lets clients assert the timezone contract without re-reading the spec. e.g. `{"timezone":"UTC","format":"ISO 8601"}`
`timezone`*	`string`	Always `UTC`: The canonical timezone for every datetime field in the body. e.g. `UTC`
`format`*	`string`	Always `ISO 8601`: Explicit `Z` suffix on every datetime. e.g. `ISO 8601`
`links`	`object`	Pagination or related links, present only when the endpoint returns a paginated collection.

**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`	Insufficient permissions.	`ErrorResponse`
404	`4xx`	The resource does not exist or is not visible to the client	`Error`

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