> ## Documentation Index > Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a transfer batch > Creates a batch of outbound transfers from your accounts, in the `live` or `test` mode of the API key used. The batch starts in `pending_authorization` and Fintoc sends its transfers only after you approve the batch from the Dashboard. An approved batch moves to `in_progress`. Requirements differ by country. In Chile, the currency is `CLP` and each counterparty needs a `holder_id`, which is the Chilean tax ID (RUT), a `holder_name`, an `account_type`, and an `institution_id`. In Mexico, the currency is `MXN` and each counterparty's `account_number` can be a standardized Mexican bank account number (CLABE), debit card, or phone number. When `account_number` is a debit card or phone number, the counterparty also needs an `institution_id`. To read the transfers of the batch, call `GET /v2/transfers` with the `transfer_batch_id` query parameter. Requires a JSON Web Signature (JWS) in the `Fintoc-JWS-Signature` header. ## OpenAPI ````yaml reference/core-api.json POST /v2/transfer_batches openapi: 3.1.0 info: title: Fintoc API version: v2026-02-01 servers: - url: https://api.fintoc.com security: [] paths: /v2/transfer_batches: post: tags: - Transfer batches summary: Create a transfer batch description: >- Creates a batch of outbound transfers from your accounts, in the `live` or `test` mode of the API key used. The batch starts in `pending_authorization` and Fintoc sends its transfers only after you approve the batch from the Dashboard. An approved batch moves to `in_progress`. Requirements differ by country. In Chile, the currency is `CLP` and each counterparty needs a `holder_id`, which is the Chilean tax ID (RUT), a `holder_name`, an `account_type`, and an `institution_id`. In Mexico, the currency is `MXN` and each counterparty's `account_number` can be a standardized Mexican bank account number (CLABE), debit card, or phone number. When `account_number` is a debit card or phone number, the counterparty also needs an `institution_id`. To read the transfers of the batch, call `GET /v2/transfers` with the `transfer_batch_id` query parameter. Requires a JSON Web Signature (JWS) in the `Fintoc-JWS-Signature` header. operationId: transfer-batches-create parameters: - name: Fintoc-JWS-Signature in: header required: true schema: type: string description: >- JSON Web Signature (JWS) of the request body. See [Generate JWS keys](https://docs.fintoc.com/docs/setting-up-jws-keys) to set up request signing. requestBody: content: application/json: schema: type: object properties: description: type: string description: >- Human-readable label shown in the Dashboard when you approve the batch. Up to 40 characters. example: Supplier payouts March currency: type: string enum: - CLP - MXN description: >- Currency of every transfer in the batch. One of `CLP`, `MXN`. example: MXN transfers: type: array description: Transfers to send in the batch. From 1 to 5000 transfers. items: type: object properties: account_id: type: string description: Identifier of the account the transfer is sent from. example: acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN amount: type: integer description: >- Amount to transfer, in the smallest currency unit. For MXN this is centavos; CLP has no minor unit. The minimum is `1`. example: 50000 counterparty: type: object description: Recipient of the transfer. properties: account_number: type: string description: >- Counterparty account number. In Mexico, use a standardized Mexican bank account number (CLABE), debit card, or phone number; in Chile, use the bank account number. example: '000000000000000000' holder_id: type: string description: >- Tax ID of the counterparty. Required in Chile, where it is the RUT. example: '111111111' holder_name: type: string description: >- Name of the counterparty. Required in Chile, up to 50 characters. example: Test Customer 1 institution_id: type: string description: >- Identifier of the counterparty bank. Required in Chile. In Mexico, required when the `account_number` is a debit card or phone number, since only a CLABE encodes the bank. example: cl_banco_de_chile account_type: type: string description: >- Type of the counterparty account. Required in Chile. One of `checking_account`, `sight_account`, `savings_account`. example: checking_account email: type: string description: Email of the counterparty. Up to 200 characters. example: jared@piedpiper.com required: - account_number comment: type: string description: >- Comment shown to the counterparty. Up to 40 characters. example: Payout March reference_id: type: string description: >- Numeric reference shown in the counterparty statement in Mexico. Up to 7 digits, with no leading zeros. example: '1234567' metadata: type: object description: >- Set of key-value pairs you can attach to the transfer for storing additional structured information. Up to 50 pairs, with keys of up to 40 characters and string values of up to 500 characters. Values cannot be arrays or nested objects. example: invoice_id: '12345' required: - account_id - amount - counterparty required: - description - currency - transfers required: true responses: '201': description: The created transfer batch, in `pending_authorization`. content: application/json: schema: $ref: '#/components/schemas/transfer_batch' '400': description: >- Invalid request: the batch or one of its transfers is missing or has an invalid field. For `invalid_transfers`, `details` lists each error with the `index` of the transfer in `transfers` and the `field` that failed. content: application/json: examples: invalid_transfers: value: error: code: invalid_transfers message: >- Some of the information provided in the transfers field is missing or invalid details: - index: 3 field: counterparty.holder_id text: is missing invalid_transfers_size: value: error: code: invalid_transfers_size message: Transfers must contain between 1 and 5000 transfers invalid_description_size: value: error: code: invalid_description_size message: Description length must be less than 40 characters param: description doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' '401': description: Invalid or missing API key. content: application/json: examples: invalid_api_key: value: error: type: authentication_error code: invalid_api_key message: 'Invalid API Key: invalid-*oken' schema: $ref: '#/components/schemas/error_object' '409': description: >- One or more accounts cannot send the transfers. `details` lists every failing account with its `account_id` and its `error_code`, so you can fix them all at once. The possible values of `error_code` are `missing_account`, `insufficient_balance`, `invalid_status`, and `api_outbounds_blocked`. `api_outbounds_blocked` also applies to every account when your organization has API outbound transfers blocked. content: application/json: examples: invalid_sender_accounts: value: error: code: invalid_sender_accounts message: Some accounts are invalid details: - account_id: acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN error_code: insufficient_balance - account_id: acc_2daFu7wPmXcRnYqBvLsT4kJhGdE error_code: missing_account schema: $ref: '#/components/schemas/error_object' '501': description: Transfer batches are not available for your organization. content: application/json: examples: operation_not_implemented: value: error: code: operation_not_implemented message: Operation not implemented for this region schema: $ref: '#/components/schemas/error_object' security: - api_key: [] components: schemas: transfer_batch: type: object description: >- A group of outbound transfers that you create in one request and approve once from the Dashboard. Fintoc sends the transfers in the batch after you approve the batch. List them with `GET /v2/transfers` and the `transfer_batch_id` query parameter. properties: id: type: string description: Unique identifier of the transfer batch. example: trbatch_2daFu0zqqDtZGJaSi2TGI2Mm1nN object: const: transfer_batch description: Type of the object. Always `transfer_batch`. amount: type: integer description: >- Sum of the amounts of the transfers in the batch, in the smallest currency unit. For MXN this is centavos; CLP has no minor unit. example: 150000 authorized_at: type: - string - 'null' format: date-time description: >- Time the batch was approved from the Dashboard, as an ISO 8601 datetime in UTC, or `null`. example: '2026-03-01T12:05:00Z' created_at: type: string format: date-time description: Time the batch was created, as an ISO 8601 datetime in UTC. example: '2026-03-01T12:00:00Z' currency: type: string enum: - CLP - MXN description: Currency of the transfers in the batch. One of `CLP`, `MXN`. example: MXN description: type: string description: Human-readable label for the batch. Up to 40 characters. example: Supplier payouts March expired_at: type: - string - 'null' format: date-time description: >- Time the batch expired without approval, as an ISO 8601 datetime in UTC, or `null`. example: null mode: type: string enum: - live - test description: Whether the batch is `live` or `test` data. example: test partially_succeeded_at: type: - string - 'null' format: date-time description: >- Time the batch finished after only some transfers succeeded, as an ISO 8601 datetime in UTC, or `null`. example: null rejected_at: type: - string - 'null' format: date-time description: >- Time the batch was rejected from the Dashboard, as an ISO 8601 datetime in UTC, or `null`. example: null settled_amount: type: integer description: >- Sum of the `settled_amount` of the transfers in the batch, in the smallest currency unit. For MXN this is centavos; CLP has no minor unit. example: 0 status: type: string enum: - pending_authorization - rejected - expired - in_progress - succeeded - partially_succeeded - failed description: >- Lifecycle status of the batch. One of `pending_authorization` (waiting for approval in the Dashboard), `rejected` (rejected in the Dashboard), `expired` (not approved in time), `in_progress` (approved, with transfers being sent), `succeeded` (every transfer succeeded), `partially_succeeded` (some transfers succeeded), or `failed` (no transfer succeeded). example: in_progress succeeded_at: type: - string - 'null' format: date-time description: >- Time every transfer of the batch succeeded, as an ISO 8601 datetime in UTC, or `null`. example: null succeeded_count: type: integer description: Number of transfers in the batch that succeeded. example: 0 transfer_count: type: integer description: Number of transfers in the batch. example: 3 required: - id - object - amount - authorized_at - created_at - currency - description - expired_at - mode - partially_succeeded_at - rejected_at - settled_amount - status - succeeded_at - succeeded_count - transfer_count error_object: type: object properties: error: type: object description: Details of the error that caused the request to fail. properties: code: type: string description: >- Machine-readable code identifying the specific error, for example `invalid_request`. example: invalid_request doc_url: type: string description: >- URL of a documentation page with more details about the error. Not returned by every error. example: https://docs.fintoc.com/reference/errors message: type: string description: Human-readable message describing the error. example: 'Missing required param: account_id' param: type: - string - 'null' description: >- Name of the request parameter that caused the error. Not returned by every error. example: account_id type: type: string description: >- Category of the error, for example `invalid_request_error` or `authentication_error`. Not returned by every error. example: invalid_request_error required: - code - message required: - error securitySchemes: api_key: type: apiKey name: Authorization in: header ````