BeneficiaryImportJob
Bulk beneficiary import job. Lifecycle: `pending` → `parsing` → `preview_ready` → `committing` → `completed` (or `failed` / `cancelled`). Wrapped under `{ type, id, attributes }` following JSON:API format.
ExtendsJsonApiResourceBase
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. |
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. |
file_format | string | Format of the uploaded file. Accepted: `csv`, `xls`, `xlsx`, `txt`, `json` or `pdf`. |
parse_mode | string | File reading mode — `template`: Follows the canonical headers; `free`: Free-form, the system infers the structure. |
total_rows | integer | Number of rows extracted from the file. Only available once the status is `preview_ready` or later. |
valid_count | integer | Number of rows without errors, ready to be committed. |
correctable_count | integer | Number of rows with errors that can be corrected. They are persisted unless the user rejects them. |
fatal_count | integer | Number of rows that cannot be processed with their current data. They are not persisted and are skipped on commit. |
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. |
committed_count | integer | Rows effectively persisted in the beneficiary list. Available once status is `completed`. |
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. |
llm_invoked | boolean | `true` when the AI engine was used during parsing to resolve ambiguous rows in free-form mode. |
error_code | string | null | Stable code of the job failure. `null` when it did not end in `failed`. For example, `file_corrupt` or `empty_file`. |
error_summary | string | null | Readable summary of the job failure. `null` when it did not end in `failed`. Card numbers appear masked. |
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. |
parsed_at | string | null | Date and time when the file reading finished, in ISO 8601 UTC. `null` while it has not finished. |
committed_at | string | null | Date and time when the commit started, in ISO 8601 UTC. `null` while it has not been committed. |
completed_at | string | null | Date and time of completion, in ISO 8601 UTC. `null` while it has not finished. |
Used in operations
GET /v1/beneficiaries/imports/{id}GET /v1/beneficiaries/imports/{id}/preview