BeneficiaryImportJob
Bulk beneficiary import job. Lifecycle: `pending` → `parsing` → `preview_ready` → `committing` → `completed` (or `failed` / `cancelled`). Wrapped under `{ type, id, attributes }` following JSON:API format.
Properties
| 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 | Stable error code when `status=failed` (e.g. `file_corrupt`, `plan_cap_exceeded`). `null` in non-failed states. |
error_summary | string | null | 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 | ISO 8601 UTC timestamp when parsing completed. `null` until parsing finishes. |
committed_at | string | null | ISO 8601 UTC timestamp when commit started. `null` until commit begins. |
completed_at | string | null | ISO 8601 UTC timestamp when the job completed. `null` while the job has not finished. |
Used in operations
GET /v1/beneficiaries/imports/{id}GET /v1/beneficiaries/imports/{id}/preview