--- title: "Request a batch of validations" method: POST path: "/validation/batches" tags: ["Account Validation"] --- # Request a batch of validations `POST /validation/batches` ## Request - Base URL: `https://api.validator.shinkansen.finance/v1` - URL: `https://api.validator.shinkansen.finance/v1/validation/batches` - Auth: API key in header `Shinkansen-Validator-Api-Key` Requests up to 1000 validations in a single call. Shinkansen stores the batch and answers immediately; the validations are performed asynchronously, and once none is pending the results of the whole batch are sent in a single call to the batch webhook configured for the Validator service. Validations that belong to a batch are not sent to the single validation webhook. The batch is accepted or rejected as a whole: if any request is invalid, its id is taken or repeated, or it asks for an access check that is not available, nothing is stored. A batch times out after 15 minutes by default. Requests still pending at that time are closed as `error`, with `return_code` `unable_to_validate` and `return_message` `batch_timed_out`. ## Request body - PublicBatchRequest: Validation batch request (public endpoint) - `id` string, required: The id of the validation batch. Set by customer. Must be unique for your organization. It is used for idempotency: retrying a batch with the same id never creates a second batch, and answers `409` with the stored batch. - `source_name` string: A free-form label for the origin of the batch (e.g. the name of your process). Returned when you read the batch. - `validation_requests` PublicBatchRequestItem[], required: Between 1 and 1000 validation requests. Each one needs its own `id`, unique for your organization, and must not repeat inside the batch. If any request is invalid, conflicts with another one, or is not allowed, the whole batch is rejected and nothing is stored. - `id` string, required: The id of the validation request. Set by customer. Must be unique for your organization, across batches and single validation requests. - `perform_account_access_check` boolean: Same as in a single validation request: when `true`, Shinkansen transfers a random amount (between $1 and $99 CLP) instead of the fixed $1, and returns it as `access_check_amount` once the transfer is confirmed. Only available for CLP and only with the `validator_variable_amount_cl` product enabled. If one request of the batch asks for it without meeting both conditions, the whole batch is rejected with `403`. Must be a JSON boolean: any other value (e.g. `"true"` or `1`) is a `400`. The amount is always chosen by Shinkansen: a request that carries `access_check_amount` is rejected with `400`. - `account_details` AccountDetails, required: Validation Account Details - `name` string: Name of the account holder. - `identification` object: The identifier for a legal or natural person - `id_schema` string, required: Identification schema. See https://docs.shinkansen.tech/docs/tipos-de-identificacion - `id` string, required: The actual identification "number" (but not always just numbers). For `"MXRFC"` schema (Mexican RFCs), it can contain numbers and letters (13 for natural persons, 12 for legal entities). For `"MXCURP"` schema (Mexican CURPs) identifying natural persons, it can contain numbers and letters (18 characters). For `"COCC"`, `"COTI"`, `"CONUIP"`, and `"COCE"` schemas (all identifying natural personal in Colombia), use only numbers. For `"CONIT"` schema (Colombian NITs, for legal entities), also use only numbers. For `"PASS"` schema (Passports, used in Colombia for some accounts in name of foreign natural persons), it can contain numbers and letters (and generally whatever is literally printed as a passport number). For `"CLID"` schema (Chilean RUTs, for legal entities and natural persons) you must use the XXXXXXXX-X format: `^\d{8}[-][0-9kK]$`. See https://docs.shinkansen.tech/docs/tipos-de-identificacion for more details. - `financial_institution` object: The identifier for a financial institution - `fin_id_schema` string, required: Identification schema for financial institution, namely, any participant in Shinkansen Network. Use `"SHINKANSEN"` for Shinkansen's native network ids and full support on any participant and service of the Shinkansen network. Other schemas might be used when interfacing with other networks but they are *not* recommended unless you *really* know what you are doing or have been explicitly instructed to do so by Shinkansen. - `fin_id` string, required: Identification according to schema. When the `"SHINKANSEN"` schema is used (as recommended), this is the ID assigned by Shinkansen to the participant in the network. In the context of the `header`, it refers to the Shinkansen network participant that sends (Sender) or receives (Receiver) the message. In the context of the `transactions`, it refers to the financial institution from which the resources leave or where the resources arrive. The ID assigned by Shinkansen to the financial institution can be found in https://docs.shinkansen.tech/docs/instituciones-financieras. When sending a transaction to Shinkansen, this value must always be SHINKANSEN. When sending a payout order to Shinkansen Treasury, this value must be SHINKANSEN_TREASURY - `account` string, required: The account number - `account_type` string, required: Account type. See https://docs.shinkansen.tech/docs/tipos-de-cuentas for possible values. - `currency` string, required: Currency ISO 4217 code (e.g: `"CLP"`) - `email` string, email: E-mail of the legal or natural person owning the account. Used for email notifications. REQUIRED for validations in 🇨🇱 ## Response `200` Validation batch correctly received. Returns the batch with status `"pending"` and each request's id and status. The results will be sent to the batch webhook configured for the Validator service. - PublicBatchAccepted: Validation batch just accepted. Each request is listed with its id and status only; read the batch to get the full requests and their results. - `id` string, required: The id of the validation batch, as you sent it. - `source_type` 'api', required: Always `api` for batches created through this endpoint. - `source_name` string, required: The `source_name` you sent, or `api` if you did not send one. - `status` 'pending', required: Always `pending` for a just-accepted batch. - `timeout_at` string, date-time, required: When the batch times out. Requests still pending at that time are closed as `error`, with `return_code` `unable_to_validate` and `return_message` `batch_timed_out`. - `closed_at` string, date-time, nullable: When the batch was closed. Always `null` here. - `validation_requests` object[], required - `id` string, required - `status` 'pending', required - `inserted_at` string, date-time, required - `updated_at` string, date-time, required ## Other responses - `400`: Validation batch invalid or malformed: an invalid field, a missing or empty `id`, an empty batch or one over 1000 requests, a non-boolean `perform_account_access_check`, or an `access_check_amount` sent by the client. Nothing is stored. - `403`: Wrong API Key (empty body), or an account access check requested where it is not available: outside CLP, or without the `validator_variable_amount_cl` product. The whole batch is rejected. - `409`: The batch id, or some of its request ids, were already received. Nothing new is stored. Two answers: * **Batch id already received**: the stored batch, in its current state, with `idempotent_replay: true`. Safe to use when you retry a batch after a network failure. * **Request ids taken or repeated**: only the conflicting requests. A stored one comes with its current state, like the single validation endpoint answers a taken id; one only repeated inside the batch comes back as you sent it. - `500`: Unexpected error. Nothing is stored. --- [API](https://skmtc.dev/shinkansen/apis/validator-shinkansen-endpoints.md) - [All operations](https://skmtc.dev/shinkansen/apis/validator-shinkansen-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/shinkansen/apis/validator-shinkansen-endpoints/revisions/4502fbbb6325?raw)