finov.ioDocumentationHome

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"
}