Start a bulk beneficiary import

POST https://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 creates an asynchronous import job. A user may only have one active (non-terminal) job at a time — a concurrent upload returns 422. Parse modes:

template: the file follows canonical headers (download the template from /v1/beneficiaries/imports/template). The bank is derived from the CLABE prefix or BIN.
free: any format; the system extracts accounts automatically, with AI fallback for unstructured formats.

The job goes through pending → parsing → preview_ready and waits for the user to confirm. Poll GET /v1/beneficiaries/imports/{id} until preview_ready or failed; once at preview_ready review and edit rows via GET /v1/beneficiaries/imports/{id}/preview and finally confirm with POST /v1/beneficiaries/imports/{id}/commit.

Request

cURLPython•JavaScript•PHP•

curl -X POST 'https://api.veriko.mx/v1/beneficiaries/imports' \
  -H 'Authorization: Bearer mxcep_••••' \
  -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
`type` *	`string`	JSON:API resource type.
`id` *	`string`	Numeric job ID expressed as a string (JSON:API format).
`attributes` *	`object`	Initial job attributes returned upon creation.
`status` *	`string`	Initial job status.

**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`	Permisos insuficientes	`ErrorResponse`
422	`4xx`	Validation or pre-condition failed. Possible codes: `file_required`, `file_too_large`, `unsupported_format`, `active_job_exists`, `parse_mode_invalid`.	`ErrorResponse`

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