OcrValidationRequest
Body for `POST /v1/validate-ocr` with the receipt in `image` or `image_url`; requires at least one of the two fields. `cuenta_beneficiaria` and `cuentas_candidatas` cannot be sent together.
Properties
| Field | Type | Description |
|---|---|---|
image | string (byte) | Receipt encoded in base64, as an image or a PDF. If `image_url` is also provided, only `image_url` is considered. Accepted formats: JPEG, PNG, WebP, or a PDF of 1 to 3 pages. Maximum size: `12 MB`. Maximum dimensions of an image: `12000px` per side. Accepts the `data:image/...;base64,` or `data:application/pdf;base64,` prefix. |
image_url | string (uri) | Public HTTPS URL of the receipt. The file is fetched when the request arrives and follows the same format and size limits as `image`: JPEG, PNG, WebP, or a PDF of 1 to 3 pages, up to `12 MB`. An `http` URL returns HTTP status `422` (with `invalid_url_scheme` in the body), and a redirect to `http` is not followed. |
cuenta_beneficiaria | string | Receiving account for the transfer (useful when it is missing or incomplete in the image). Required for DiMo phone; optional if the image shows the full account or its last digits, which are completed with the saved beneficiaries (they do not replace this field). Accepts CLABE (18 digits), card (16 digits) or DiMo phone (10 digits). It cannot be sent together with `cuentas_candidatas`: sending both responds with an HTTP status `422` (with `cuenta_y_candidatas_excluyentes` in the body). |
cuentas_candidatas | array | Accounts among which the receiving one is, for when the image does not show it and it is not known which. It replaces `cuenta_beneficiaria`: sending both responds with an HTTP status `422` (with `cuenta_y_candidatas_excluyentes` in the body). It takes priority over the account read from the image. It accepts from 2 up to the platform's current maximum, 3 by default and never more than 10; the `422` for an excess reports the maximum in `meta.max`. Each account is a CLABE (18 digits), a card (16) or a DiMo phone (10), with a valid check digit and no repeats. A list that does not comply responds with a `422` with `cuentas_candidatas_invalidas`, and points out in `field_errors` the position that failed. Both errors happen before any quota is consumed. It consumes a single quota unit, however many accounts it carries, also with `?async=1`. The query goes through the candidates in the order sent and adopts the first one that matches the transfer. The winner is published in full in `normalized_data.cuenta_beneficiaria`, and `candidate_match` reports its position. If none matches, the response is an HTTP status `422` with the reason in `code` (`cuenta_unresolvable_after_probes` when there is no more precise diagnosis). |
banco_emisor | string | **SPEI code** of the sending bank (4 or 5 digits, e.g. `40012`), to correct the one read from the receipt. It replaces the one read before querying Banxico. A value that is not 4 or 5 digits (a name, for example) is ignored and the one read is kept. |
banco_receptor | string | **SPEI code** of the receiving bank (4 or 5 digits, e.g. `40002`), to correct the one read from the receipt. It replaces the one read before querying Banxico. A value that is not 4 or 5 digits (a name, for example) is ignored and the one read is kept. |
retry_policy | object | Automatic retry policy for this validation. If omitted, the policy configured at `PUT /v1/users/me/retry-policy` is used. Retries do not consume validation quota. |
enabled | boolean | `true` when the retry cycle is active. With `false`, the other fields are ignored. |
max_retries | integer | Maximum number of automatic retries. Once reached, the cycle enters the `exhausted` terminal state. The allowed limit depends on the plan. |
interval_seconds | integer | Seconds to wait between each retry (300–86400, i.e., 5 minutes to 24 hours). |
outcomes | array | Outcomes that trigger a retry. By default, they are `not_found`, `cep_unavailable`, and `error`; the combination `["not_found", "cep_unavailable"]` excludes `error`. |
client_ref | string | Reference of your own that is returned as sent in the validation, in the validation webhooks, and as an exact filter of `GET /v1/validations`. Text of 1 to 64 characters, without line breaks or emoji; it is trimmed before being stored. A value that does not comply is rejected with an HTTP status `422` (with `invalid_client_ref` in the body). It must not contain personal data. |
retain_image | boolean | `true` when the platform keeps the receipt file after validating it, which is the usual case. With `false`, the file is deleted as soon as the validation reaches a terminal status in which it is no longer needed; the verdict and the extracted data are kept. With `false`, the validation publishes `image_retained=false` and `GET /v1/validations/{id}/image` responds with an HTTP status `410` (with `image_not_retained` in the body). It applies the same with `?async=1`. The file exists while the validation is being processed. If it came in as a CEP in PDF and has automatic retries active, the deletion waits for that cycle to close, because each retry compares the PDF's seal again. A value that is not a boolean responds with an HTTP status `422` (with `invalid_retain_image` in the body), before any quota is consumed. |
Variants
Must include at least one of these fields:
imageimage_url
Used in operations
POST /v1/validate-ocr