# Get transaction banking account balance history
Get the balance history for a transaction banking account.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"title": "Banking - Transaction banking",
"version": "0.9.0",
"description": "Transaction banking API",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
}
},
"servers": [
{
"url": "https://sandbox.pismolabs.io",
"description": "Sandbox API server for testing"
}
],
"security": [
{
"BearerAuth": []
}
],
"tags": [
{
"name": "Bank statements",
"description": "Bank statements endpoints"
}
],
"components": {
"parameters": {
"CursorQuery": {
"name": "cursor",
"in": "query",
"description": "Cursor to the next page of results. If no value is specified, it fetches the first page.",
"schema": {
"type": "string"
},
"example": "1234"
},
"EndDateQuery": {
"name": "endDate",
"in": "query",
"description": "Ending date of the desired date range for the account balance history. If not provided, it defaults to the current date. The total date range cannot exceed three years.",
"schema": {
"type": "string",
"format": "date"
},
"example": "2023-05-03"
},
"ExternalAccountIdPath": {
"name": "externalAccountId",
"in": "path",
"description": "External account ID",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"example": "12345678901",
"required": true
},
"LimitQuery2": {
"name": "limit",
"in": "query",
"description": "Maximum number of items per page. Defaults to `100`. Maximum is `500`",
"schema": {
"type": "integer",
"format": "int32",
"default": 100,
"maximum": 500
},
"example": 500
},
"StartDateQuery": {
"name": "startDate",
"in": "query",
"description": "Starting date of the desired date range for the account balance history. If not provided, it defaults to one month prior to the end date. The total date range cannot exceed three years.",
"schema": {
"type": "string",
"format": "date"
},
"example": "2023-04-03"
}
},
"schemas": {
"AccountBalanceHistoryResponse": {
"type": "object",
"properties": {
"account_id": {
"$ref": "#/components/schemas/AccountID"
},
"external_account_id": {
"$ref": "#/components/schemas/ExternalAccountID"
},
"currency_numeric_code": {
"$ref": "#/components/schemas/AccountNumericCurrencyCode"
},
"currency_alphabetic_code": {
"$ref": "#/components/schemas/AccountAlphabeticCurrencyCode"
},
"balance_history": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/AccountBalanceMainAttributes"
},
{
"type": "object",
"properties": {
"date": {
"$ref": "#/components/schemas/CurrentBalanceDate"
},
"business_date": {
"$ref": "#/components/schemas/BusinessDate"
},
"credit_movement": {
"$ref": "#/components/schemas/CreditMovement"
},
"debit_movement": {
"$ref": "#/components/schemas/DebitMovement"
},
"net_movement": {
"$ref": "#/components/schemas/NetMovement"
}
}
}
]
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
}
},
"AccountBalanceMainAttributes": {
"type": "object",
"required": [
"future_dated_credits_balance",
"future_dated_debits_balance"
],
"properties": {
"future_dated_credits_balance": {
"$ref": "#/components/schemas/FutureDatedCreditsBalance"
},
"future_dated_debits_balance": {
"$ref": "#/components/schemas/FutureDatedDebitsBalance"
},
"ledger_balance": {
"$ref": "#/components/schemas/LedgerBalance"
},
"book_balance": {
"$ref": "#/components/schemas/BookBalance"
},
"available_balance": {
"$ref": "#/components/schemas/AvailableBalance"
},
"credit_balance": {
"$ref": "#/components/schemas/CreditBalance"
},
"debit_balance": {
"$ref": "#/components/schemas/DebitBalance"
},
"uncleared_funds": {
"$ref": "#/components/schemas/UnclearedFunds"
},
"uncleared_checks_balance": {
"$ref": "#/components/schemas/UnclearedChecksBalance"
},
"restricted_funds": {
"$ref": "#/components/schemas/RestrictedFundsBalance"
},
"earmarked_balance": {
"$ref": "#/components/schemas/EarmarkBalance"
},
"overdraft_limit": {
"$ref": "#/components/schemas/OverdraftLimit"
},
"value_dated_balance": {
"$ref": "#/components/schemas/ValueDatedBalance"
},
"held_funds": {
"$ref": "#/components/schemas/HeldFunds"
},
"held_checks_balance": {
"$ref": "#/components/schemas/HeldChecksBalance"
},
"remunerative_interest_accrued": {
"$ref": "#/components/schemas/RemunerativeInterestAccrued"
}
}
},
"AccountID": {
"type": "integer",
"format": "int64",
"description": "Account ID",
"example": 1234
},
"AvailableBalance": {
"type": "number",
"format": "float",
"minimum": -9223372036854776000,
"maximum": 9223372036854776000,
"description": "Available balance.
\nAvailable balance is calculated as `credit_balance` - `debit_balance` + `overdraft_limit`.\n`minimum: -9223372036854775807`\n`maximum: 9223372036854775807`\n",
"example": 123.45
},
"BookBalance": {
"type": "number",
"format": "float",
"minimum": -9223372036854776000,
"maximum": 9223372036854776000,
"description": "Book balance.
\nBook balance is calculated as `credit_balance` - `debit_balance` + `earmarked_balance`.\n`minimum: -9223372036854775807`\n`maximum: 9223372036854775807`\n",
"example": 146.9
},
"BusinessDate": {
"type": "string",
"format": "date",
"description": "Specifying a `business_date` value impacts the account balance history.
\nNotes:\n - The business date is in ISO 8601 format.\n - The business date allows users to designate the balance history cycle in which a payment is posted.\n - You can specify a `business_date` within the current working day or up to one working day before or after.\n",
"example": "2023-03-09"
},
"CreditBalance": {
"type": "number",
"description": "Credit balance",
"format": "float",
"example": 123.45
},
"AccountNumericCurrencyCode": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "Account numeric currency code in ISO 4217 format. If not specified, it's inherited from the program.\n",
"example": "840"
},
"AccountAlphabeticCurrencyCode": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "Account alphabetic currency code in ISO 4217 format. If not specified, it's inherited from the program.\n",
"example": "USD"
},
"CurrentBalanceDate": {
"type": "string",
"description": "Date of current balance. Format = yyyy-mm-dd.",
"example": "2023-06-22"
},
"Cursor": {
"type": "string",
"description": "Cursor pointing to the next page of results",
"example": "eyJJRCI6IjBjOGVhMTA4LWNhZTYtNDA2Mi1iMmQzLTFhMTZkNmJiNGIyOCIsIk9yZ0lEIjoiMDllYThhMDQtNWY5My0xMWVkLTliNmEtMDI0MmFjMTIwMDAyIn0="
},
"DebitBalance": {
"type": "number",
"description": "Debit balance",
"format": "float",
"example": 123.45
},
"EarmarkBalance": {
"type": "number",
"description": "Earmark balance. Initially equal to the earmarked amount and decreases as the reserved funds are used up or decreased in a decrease operation. It can also increase if an increase operation is performed.
\n`minimum: 0`\n`maximum: 18446744073709551617`\n",
"minimum": 0,
"maximum": 18446744073709552000,
"example": 123.45
},
"ErrorCode": {
"description": "Error code\n`minLength: 1`\n`maxLength: 12`\n",
"type": "string",
"minLength": 1,
"maxLength": 12,
"example": "WPMT0017"
},
"ErrorMessage": {
"description": "Error message\n`minLength: 1`\n`maxLength: 1000`\n",
"type": "string",
"minLength": 1,
"maxLength": 1000,
"example": "Invalid JSON payload received: Error unmarshalling request"
},
"ErrorResponse": {
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/ErrorCode"
},
"message": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
},
"ExternalAccountID": {
"maxLength": 60,
"type": "string",
"pattern": "^[a-zA-Z0-9-]+$",
"description": "Custom account ID. Used as the key for all operations (manage accounts, transactions, etc.) on the corporate layer.\n\nThis field is:\n- Unique within the Organization\n- Immutable: The field cannot be updated.\n- Not recyclable: You can't reuse an external account ID, even if the account that was using it has been canceled.\n",
"example": "b993ba96-b3e8-4ef7-9cf7-7eee5ddafdab"
},
"FutureDatedCreditsBalance": {
"description": "Represents the account balance scheduled to be settled on a future date, after the original posting date. The account's `book_balance` is credited when the settlement occurs.
\nThe `future_dated_credits_balance` increases when future-dated credits are posted using the [Post payment](https://developers.pismo.io/pismo-docs/reference/corporate-v2-post-payments) endpoint, and decreases when those payments are settled or canceled. This balance is always a positive value.
\n`minimum`: `-9223372036854775807`\n`maximum`: `9223372036854775807`\n",
"type": "number",
"minimum": -9223372036854776000,
"maximum": 9223372036854776000,
"example": 70
},
"FutureDatedDebitsBalance": {
"description": "Represents the account balance scheduled to be settled on a future date, after the initial posting date. The account’s `book_balance` is debited when the settlement occurs.
\nThe `future_dated_debits_balance` increases when future-dated debits are posted using the [Post payment](https://developers.pismo.io/pismo-docs/reference/corporate-v2-post-payments) endpoint, and decreases when these payments are settled or canceled. This balance is always a positive value.
\n`minimum`: `-9223372036854775807`\n`maximum`: `9223372036854775807`\n",
"type": "number",
"minimum": -9223372036854776000,
"maximum": 9223372036854776000,
"example": 70
},
"CreditMovement": {
"description": "Represents the total of all credits processed during the business day. Always expressed as a positive value.
\n`minimum`: `0`\n`maximum`: `9223372036854775807`\n",
"type": "number",
"minimum": 0,
"maximum": 9223372036854776000,
"example": 70
},
"DebitMovement": {
"description": "Represents the total of all debits processed during the business day. Always expressed as a positive value.
\n`minimum`: `0`\n`maximum`: `9223372036854775807`\n",
"type": "number",
"minimum": 0,
"maximum": 9223372036854776000,
"example": 70
},
"NetMovement": {
"description": "The change in an account’s balance between two consecutive business dates.\nCalculated as: `net_movement` = `credit_movement` - `debit_movement`.
\n`minimum`: `-9223372036854775807`\n`maximum`: `9223372036854775807`\n",
"type": "number",
"minimum": -9223372036854776000,
"maximum": 9223372036854776000,
"example": 70
},
"LedgerBalance": {
"type": "number",
"format": "float",
"minimum": -9223372036854776000,
"maximum": 9223372036854776000,
"description": "Ledger balance.
\nLedger balance is calculated as `book_balance` + `uncleared_funds`.\n`minimum: -9223372036854775807`\n`maximum: 9223372036854775807`\n",
"example": 270.35
},
"MaxItemsPerPage": {
"type": "integer",
"format": "int32",
"description": "Maximum number of items per page",
"example": 10
},
"OverdraftLimit": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 18446744073709552000,
"description": "Account overdraft limit
\n`minimum: 0`\n`maximum: 18446744073709551617`\n",
"example": 123.45
},
"Pagination": {
"type": "object",
"description": "Data related to list pagination using a cursor.",
"properties": {
"limit": {
"$ref": "#/components/schemas/MaxItemsPerPage"
},
"cursor": {
"$ref": "#/components/schemas/Cursor"
}
}
},
"RestrictedFundsBalance": {
"type": "number",
"format": "float",
"description": "The portion of an account balance held under regulatory or operational restrictions and not available for transactions.\n`minimum`: 0\n`maximum`: 9223372036854775807\n",
"minimum": 0,
"maximum": 9223372036854776000
},
"HeldFunds": {
"type": "number",
"format": "float",
"description": "Funds that are temporarily restricted due to regulatory or operational requirements, unavailable for transactions, and representing the total amount of earmarked or otherwise restricted balances.\n`minimum`: 0\n`maximum`: 9223372036854775807\n",
"minimum": 0,
"maximum": 9223372036854776000
},
"HeldChecksBalance": {
"type": "number",
"format": "float",
"description": "The balance from checks that the bank considers available but holds to earn interest. It increases when check holds are applied and decreases when those holds are released or canceled.\n`minimum`: 0\n`maximum`: 9223372036854775807\n",
"minimum": 0,
"maximum": 9223372036854776000
},
"RemunerativeInterestAccrued": {
"type": "number",
"format": "float",
"description": "This balance reflects the total interest pending capitalization. It increases as interest accrues and decreases when the accrued interest is added to the principal balance.\n`minimum`: 0\n`maximum`: 9223372036854775807\n",
"minimum": 0,
"maximum": 9223372036854776000
},
"UnclearedChecksBalance": {
"type": "number",
"format": "float",
"minimum": -9223372036854776000,
"maximum": 9223372036854776000,
"description": "The total value of checks that have been posted to the account but have not yet cleared.\n`minimum: -9223372036854775807`\n`maximum: 9223372036854775807`\n"
},
"UnclearedFunds": {
"type": "number",
"format": "float",
"minimum": -9223372036854776000,
"maximum": 9223372036854776000,
"description": "Uncleared funds amount
\n`minimum: -9223372036854775807`\n`maximum: 9223372036854775807`\n",
"example": 123.45
},
"ValueDatedBalance": {
"type": "number",
"description": "The value dated balance results from recalculating credit or debit balance based on the back value date. Defaults to the book balance.
\nThe value dated balance is included in the following events:\n- [Account balance changed](https://developers.pismo.io/events/docs/account-balances-balance-change-1)\n- [Account balance history generated](https://developers.pismo.io/events/docs/account-balances-balance-history-1)\n",
"format": "float",
"example": 123.45
}
},
"responses": {
"500InternalServer2": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Generic internal error": {
"value": {
"code": "CMN9999",
"message": "Internal error"
}
},
"Account balance unknown": {
"value": {
"code": "EABL0001",
"message": "Account balance unknown"
}
}
}
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/bank-statements/v1/account-balances/{externalAccountId}/history": {
"get": {
"summary": "Get transaction banking account balance history",
"description": "Get the balance history for a transaction banking account.",
"operationId": "get-account-balance-history",
"tags": [
"Bank statements"
],
"parameters": [
{
"$ref": "#/components/parameters/ExternalAccountIdPath"
},
{
"$ref": "#/components/parameters/StartDateQuery"
},
{
"$ref": "#/components/parameters/EndDateQuery"
},
{
"$ref": "#/components/parameters/CursorQuery"
},
{
"$ref": "#/components/parameters/LimitQuery2"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountBalanceHistoryResponse"
},
"examples": {
"Example account balance": {
"value": {
"account_id": 1234,
"external_account_id": "b993ba96-b3e8-4ef7-9cf7-7eee5ddafdab",
"currency_numeric_code": "840",
"currency_alphabetic_code": "USD",
"balance_history": [
{
"future_dated_credits_balance": 0,
"future_dated_debits_balance": 0,
"credit_movement": 50,
"debit_movement": 0,
"net_movement": 50,
"available_balance": 50,
"debit_balance": 0,
"credit_balance": 50,
"earmarked_balance": 20,
"ledger_balance": 110,
"book_balance": 70,
"uncleared_funds": 40,
"uncleared_checks_balance": 0,
"overdraft_limit": 0,
"value_dated_balance": 70,
"cycle_closing_datetime": "2023-01-21T23:00:00Z",
"date": "2023-06-22",
"business_date": "2023-06-22",
"restricted_funds": 0,
"remunerative_interest_accrued": 1.23
}
],
"pagination": {
"limit": 100,
"cursor": "MjAyMy0wNC0wMQ=="
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"external_account_id validation error": {
"value": {
"code": "CMN0002",
"message": "external_account_id must be a maximum of 60 characters in length"
}
},
"Invalid header account": {
"value": {
"code": "WHIS0002",
"message": "Invalid header account"
}
},
"Invalid date format": {
"value": {
"code": "WHIS0003",
"message": "Invalid date format"
}
},
"Invalid date interval": {
"value": {
"code": "WHIS0004",
"message": "Invalid date interval"
}
},
"Max page limit exceeded": {
"value": {
"code": "WHIS0006",
"message": "Max page limit exceeded"
}
},
"Max date range exceeded": {
"value": {
"code": "WHIS0007",
"message": "Max query range exceeded"
}
},
"Cursor is invalid": {
"value": {
"code": "WHIS0008",
"message": "Cursor is invalid"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Account not authorized": {
"value": {
"code": "WHIS0001",
"message": "Account not authorized"
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Forbidden request": {
"value": {
"message": "access denied"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Transaction not found": {
"value": {
"code": "WHIS0005",
"message": "No account balance history found"
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/500InternalServer2"
}
}
}
}
}
}
```