Start a bulk beneficiary import

POSThttps://api.veriko.mx/v1/beneficiaries/imports

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

Uploads a file — CSV, XLS, XLSX, TXT, or PDF, up to 20 MB — and opens an import job with it. An account may only have one open job at a time: a second upload while the previous one is still alive responds 422 import_already_in_flight.

The reading mode decides how much work the file does and how much the server does:

template: the file follows the canonical headers, obtained from /v1/beneficiaries/imports/template. The bank is derived from the CLABE prefix or the card BIN.
free: any format. Accounts are extracted from the content, with a language model stepping in when the file has no recognisable structure.

The import persists nothing on its own. The job runs pending → parsing → preview_ready and stops there, waiting for an explicit confirmation. The full sequence is four steps:

This call returns the job identifier.
GET /v1/beneficiaries/imports/{id} reports progress until preview_ready or failed.
GET /v1/beneficiaries/imports/{id}/preview shows the extracted rows, and PATCH …/rows/{row_id} corrects the ones that need it.
POST /v1/beneficiaries/imports/{id}/commit persists the result.

The polling in step 2 and its cadence are covered in asynchronous operations.

Request

cURLPython•JavaScript•PHP•

curl -X POST 'https://api.veriko.mx/v1/beneficiaries/imports' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 202**`CreateBeneficiaryImportResponse` — Import job created and enqueued for processing.
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`	Initial job attributes returned upon creation.
`status`*	`string`	Initial job status. The only possible value is `pending`. e.g. `pending`
`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. `a1b2c3d4e5f6`
`datetime`	`object`	Companion descriptor present in every response's meta block (and in outgoing webhook payloads). 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**`POST /v1/beneficiaries/imports`
Status	Class	Description	Body
202	`2xx`	Import job created and enqueued for processing.	`CreateBeneficiaryImportResponse`
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Insufficient permissions.	`ErrorResponse`
422	`4xx`	Validation or pre-condition failed. Possible codes: `file_required`, `file_too_large`, `unsupported_format`, and `import_already_in_flight`.	`ErrorResponse`

**Errors from `POST /v1/beneficiaries/imports`**
Status	Code	Example
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`
422	`file_required`	A `file` part is required in the multipart body. Envelope meta.request_id `f2a3b4c5d6e7`