Goal

Upload a spreadsheet or CSV of beneficiary accounts (CLABEs, cards, or DiMo phone numbers), review how each row was classified, fix any correctable errors, and commit the import — creating all valid accounts in a single operation.

Prerequisites

• An active API key (mxcep_…) with the beneficiaries:create permission.
• A file in one of the supported formats: CSV, XLS, XLSX, TXT, or PDF. Maximum size: 20 MB.
• Only one import job may be active (non-terminal) at a time per user. Cancel or wait for the previous job to complete before uploading a new file.

Steps

1. (Optional) Download the template

For best results, use the canonical template — the parser handles it without AI fallback:

curl 'https://api.example.com/v1/beneficiaries/imports/template' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output beneficiaries-template.csv

The template CSV has columns: Alias, Cuenta. Fill in your data and save. Bank codes are derived automatically from the CLABE prefix or card BIN.

2. Upload the file

POST the file as multipart/form-data. Choose parse_mode:

• template — the file follows the canonical column headers (recommended).
• free — any layout; the system extracts accounts automatically with AI fallback for unstructured formats.

curl -X POST 'https://api.example.com/v1/beneficiaries/imports' \
  -H 'Authorization: Bearer mxcep_••••' \
  -F 'file=@beneficiaries.csv;type=text/csv' \
  -F 'parse_mode=template'

Response 202 — job created:

{
  "data": {
    "type": "beneficiary_import",
    "id": "42",
    "attributes": { "status": "pending" }
  }
}

3. Poll until preview_ready

The job goes through pending → parsing → preview_ready. Poll GET /v1/beneficiaries/imports/{id} every 2 seconds:

curl 'https://api.example.com/v1/beneficiaries/imports/42' \
  -H 'Authorization: Bearer mxcep_••••'

When status is preview_ready, the response includes per-bucket counters:

{
  "data": {
    "id": "42",
    "attributes": {
      "status": "preview_ready",
      "total_rows": 150,
      "valid_count": 120,
      "correctable_count": 20,
      "fatal_count": 5,
      "duplicate_count": 5
    }
  }
}

Bucket meanings:

4. Review and fix rows in the preview

Fetch the preview to see individual rows, optionally filtering by bucket:

# Show only correctable rows
curl 'https://api.example.com/v1/beneficiaries/imports/42/preview?buckets[]=correctable' \
  -H 'Authorization: Bearer mxcep_••••'

To fix a correctable row (for example, assign a bank code to a DiMo phone number):

curl -X PATCH \
  'https://api.example.com/v1/beneficiaries/imports/42/rows/102' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "parsed_account_type": "phone",
    "parsed_bank_code": "40012",
    "parsed_bank_name": "BBVA MEXICO"
  }'

The server re-processes the row immediately and returns its updated status. If the override resolves the error, status changes from correctable to valid.

Five fields are editable per row: parsed_account, parsed_label, parsed_account_type, parsed_bank_code, parsed_bank_name.

5. Commit the import

When satisfied with the preview, trigger the commit:

curl -X POST 'https://api.example.com/v1/beneficiaries/imports/42/commit' \
  -H 'Authorization: Bearer mxcep_••••'

Response 202 — commit enqueued:

{
  "data": {
    "id": "42",
    "attributes": { "status": "committing" }
  }
}

Poll GET /v1/beneficiaries/imports/42 until status is completed or failed. On success the response shows committed_count and skipped_count:

{
  "data": {
    "attributes": {
      "status": "completed",
      "committed_count": 140,
      "skipped_count": 10
    }
  }
}

Commit rules: valid and correctable rows are persisted. fatal and duplicate_account rows are skipped. Previously archived accounts with the same number are reactivated instead of duplicated.

6. (Optional) Cancel before committing

If you need to start over, cancel the job while it is still in pending, parsing, or preview_ready:

curl -X DELETE 'https://api.example.com/v1/beneficiaries/imports/42' \
  -H 'Authorization: Bearer mxcep_••••'

Returns 204 on success.

What's next

• View the created beneficiaries: GET /v1/beneficiaries.
• Add or update individual beneficiaries: POST /v1/beneficiaries, PUT /v1/beneficiaries/{id}.
• Export the full list for reconciliation: GET /v1/beneficiaries/export.