List or submit bank batches
API Documentation / Resources / Bank data
List bank batches
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/bank-accounts/{bank_account_id}/batches
Required OAuth scope: accounting:read
Returns undeleted batches for one bank account using page-number pagination.
Filters and ordering
| Parameter | Meaning | Default |
|---|---|---|
source |
Exact source code such as API |
All sources |
from_date |
Created on or after this date | Unbounded |
to_date |
Created on or before this date | Unbounded |
updated_since |
Updated at or after this RFC 3339 timestamp | Unbounded |
search |
Case-insensitive description search | No search |
sort |
created_at, description, or updated_at |
created_at |
order |
asc or desc |
desc |
Results with equal sort values are ordered by their internal sequence to keep pagination deterministic.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the subsidiary whose books contain the bank account. |
bank_account_id |
path | Yes | string (uuid) | UUID of the bank account. |
source |
query | No | string: API, UPLOAD, MANUAL, FEED | |
from_date |
query | No | string (date) | |
to_date |
query | No | string (date) | |
updated_since |
query | No | string (date-time) | |
search |
query | No | string | |
page |
query | No | integer | |
per_page |
query | No | integer | |
sort |
query | No | string: created_at, description, updated_at | |
order |
query | No | string: asc, desc |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/bank-accounts/{bank_account_id}/batches HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
A page of bank batches. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
422 |
One or more supplied values failed validation. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": "ad2f5fe3-d5e6-4234-b921-a70d4bf04f44",
"source": "API",
"description": "July 2026 bank activity",
"records": 2,
"created_at": "2026-08-10T09:43:00Z",
"updated_at": "2026-08-10T09:43:00Z"
}
],
"meta": {
"current_page": 1,
"per_page": 30,
"last_page": 1,
"total": 1
}
}
Submit an API bank batch
POST /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/bank-accounts/{bank_account_id}/batches
Required OAuth scope: bankbatches:write
Atomically creates one batch and up to 1,000 bank transactions.
Preconditions
| Rule | Result when violated |
|---|---|
Bank account has source_type=API |
409 bank_account_source_type_invalid |
Every external_id is unique in the bank account |
409 bank_transaction_duplicate |
| The idempotency key is new or has the same body | 409 idempotency_key_reused |
| Every transaction passes validation | 422 validation_error |
No batch or transaction is retained when any transaction fails. A retry
using the same Idempotency-Key and semantically identical JSON returns
the original batch with 200 OK; the first successful request returns
201 Created.
Monetary amounts are strings to preserve decimal precision. Positive values are inflows and negative values are outflows.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the subsidiary whose books contain the bank account. |
bank_account_id |
path | Yes | string (uuid) | UUID of the bank account. |
Idempotency-Key |
header | Yes | string | A caller-generated key unique within the bank account. Repeating the key with an identical request body returns the original batch. Repeating it with a different body returns 409 Conflict. |
Request
POST /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/bank-accounts/{bank_account_id}/batches HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Content-Type: application/json
{
"description": "July 2026 bank activity",
"transactions": [
{
"external_id": "bank-90814",
"date": "2026-07-03",
"amount": "1250.0000",
"type": "DIRECT_CREDIT",
"details": "Customer payment",
"particulars": "ASTER RIDGE",
"code": "INV-1048",
"reference": "BANK-90814"
},
{
"external_id": "bank-90815",
"date": "2026-07-04",
"amount": "-84.5000",
"type": "CARD_PURCHASE",
"details": "Software subscription",
"particulars": "CLOUD HOSTING",
"reference": "CARD-4412"
}
]
}
Required body fields: description, transactions.
Responses
| Status | Description |
|---|---|
201 |
Batch created atomically. |
400 |
Missing or malformed Idempotency-Key header. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
409 |
Source type, external ID, or idempotency conflict. |
422 |
One or more supplied values failed validation. |
201 example
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": "ad2f5fe3-d5e6-4234-b921-a70d4bf04f44",
"source": "API",
"description": "July 2026 bank activity",
"records": 2,
"created_at": "2026-08-10T09:43:00Z",
"updated_at": "2026-08-10T09:43:00Z"
}
}
409 example
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{
"type": "https://api.finov.io/problems/bank_transaction_duplicate",
"title": "Bank transaction already exists",
"status": 409,
"code": "bank_transaction_duplicate",
"detail": "One or more external transaction identifiers already exist for this bank account.",
"request_id": "req_01J50Y7N6C4X8W2NV9P0Y6H3KQ"
}