VerikoDocs

Type to search. Enter opens the first result.

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

Start a bulk beneficiary import

Audience
public
Auth
API key
Permission
beneficiaries:create
How-to guide →

Uploads a file — CSV, XLS, XLSX, TXT, JSON, or PDF, up to 20 MB — and opens an import job with it. XLSX/XLS sheets allow up to 10,000 rows and 64 columns. XLSX formulas are read as text without evaluation. PDFs allow up to 50 pages and cap decoded streams at 8 MiB. 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. It waits for an explicit confirmation. The full sequence is four steps:

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

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

Request
curl -X POST 'https://api.veriko.mx/v1/beneficiaries/imports' \
  -H 'Authorization: Bearer veriko_••••' \
  -F 'parse_mode=template' \
  -F '[email protected]'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

Try it in the playground →
Response 202CreateBeneficiaryImportResponse — Import job created and enqueued for processing.
FieldTypeDescription
dataobject

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
metaobject

Response metadata including API version, route prefix, unique request identifier, and the server timestamp in UTC.

versionstring

API version that processed the request.

e.g. 1.47.0
api_versionstring

API route prefix version (e.g. v1).

e.g. v1
request_idstring

Unique request identifier (hex).

e.g. a1b2c3d4e5f66f5e4d3c2b1a
datetimeobject

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
linksobject

Pagination or related links, present only when the endpoint returns a paginated collection.

Response status codesPOST /v1/beneficiaries/imports
StatusClassDescriptionBody
2022xxImport job created and enqueued for processing.CreateBeneficiaryImportResponse
4014xxAuthentication is required or the provided credentials are invalid.ErrorResponse
4034xxInsufficient permissions.ErrorResponse
4224xxValidation or pre-condition failed. Possible codes: file_required, upload_error, file_too_large, invalid_parse_mode, unsupported_format, import_already_in_flight, and persist_failed.ErrorResponse
Errors from POST /v1/beneficiaries/imports
StatusCodeExample
401unauthorized

Invalid or missing authentication credentials.

Envelope
meta.request_id
c4d5e6f7a8b99b8a7f6e5d4c
403permission_denied

You do not have permission to access this resource.

Envelope
meta.request_id
d5e6f7a8b9c00c9b8a7f6e5d
422file_required

A `file` part is required in the multipart body.

Envelope
meta.request_id
f2a3b4c5d6e77e6d5c4b3a2f