# Get transaction banking account information
Get the information for a transaction banking account.
**NOTE**: This endpoint requires an account token - an access token encoded with an external account ID. Tokens can expire quickly, which can result in a `401 Unauthorized` message.
# 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": "Accounts",
"description": "Accounts endpoints"
}
],
"components": {
"parameters": {
"ExternalAccountIdPath": {
"name": "externalAccountId",
"in": "path",
"description": "External account ID",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"example": "12345678901",
"required": true
}
},
"schemas": {
"AccountCreationDatetime": {
"type": "string",
"format": "date-time",
"description": "Datetime the account was created in the Pismo system (in UTC). The datetime format follows the ISO 8601 standard: `yyyy-mm-ddThh:mm:ss.sssZ`.
\nNote that milliseconds are represented as `000`, for example: `2024-02-22T16:51:49.000Z`.
\nThis field accepts datetime values from the present or past. Future dates are not allowed.
\n`minLength: 24`\n`maxLength: 24`\n",
"minLength": 24,
"maxLength": 24,
"example": "2024-01-04T10:25:30.123Z"
},
"AccountID2": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 4294967295,
"description": "Account ID
\n`minimum: 1`\n`maximum: 4294967295`\n",
"example": 102778
},
"AccountStatus": {
"type": "string",
"minLength": 1,
"maxLength": 9,
"description": "Account status
\n`minLength: 1`\n`maxLength: 9`\n",
"example": "DORMANT"
},
"AccountStatusReasonDescription": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Account status reason description
\n`minLength: 1`\n`maxLength: 500`\n",
"example": "CREDIT_ONLY"
},
"AccountStatusReasonID": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 4294967295,
"description": "Account status reason ID
\n`minimum: 1`\n`maximum: 4294967295`\n",
"example": 1438
},
"AccountStatusReasonExternalID": {
"type": "string",
"minLength": 1,
"maximum": 120,
"description": "External reason ID specifying account restrictions
\n`minimum: 1`\n`maximum: 120`\n",
"example": "CREDIT_ONLY"
},
"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
},
"Children": {
"type": "array",
"description": "List of child account IDs",
"items": {
"type": "integer",
"format": "int32",
"example": 102778,
"minimum": 1
}
},
"CurrencyAlphabeticCode": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "Alphabetic code (ISO 4217) for the currency used by the program.
\n`minLength: 3`\n`maxLength: 3`\n",
"example": "USD"
},
"CurrencyNumericCode": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "Numeric code (ISO 4217) for the currency used by the program.
\n`minLength: 3`\n`maxLength: 3`\n",
"example": "840"
},
"DivisionCode": {
"type": "string",
"maxLength": 36,
"description": "Code used to identify your division within the organization. Division code should only contain letters, numbers, and hyphens.",
"example": "US"
},
"DocumentNumber2": {
"type": "string",
"minLength": 1,
"maxLength": 15,
"description": "Entity's government document number.
\n`minLength: 1`\n`maxLength: 15`\n",
"example": "1122334455"
},
"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
},
"GetAccountResponse": {
"description": "Account response body",
"type": "object",
"required": [
"account_id",
"account_creation_datetime",
"division_code",
"program_id",
"future_dated_credits_balance",
"future_dated_debits_balance"
],
"properties": {
"account_id": {
"$ref": "#/components/schemas/AccountID2"
},
"account_creation_datetime": {
"$ref": "#/components/schemas/AccountCreationDatetime"
},
"division_code": {
"$ref": "#/components/schemas/DivisionCode"
},
"program_id": {
"$ref": "#/components/schemas/ProgramID2"
},
"future_dated_credits_balance": {
"$ref": "#/components/schemas/FutureDatedCreditsBalance"
},
"future_dated_debits_balance": {
"$ref": "#/components/schemas/FutureDatedDebitsBalance"
},
"parent_account_id": {
"$ref": "#/components/schemas/ParentAccountID2"
},
"available_balance": {
"$ref": "#/components/schemas/AvailableBalance"
},
"earmarked_balance": {
"$ref": "#/components/schemas/EarmarkBalance"
},
"overdraft_limit": {
"$ref": "#/components/schemas/OverdraftLimit"
},
"ledger_balance": {
"$ref": "#/components/schemas/LedgerBalance"
},
"book_balance": {
"$ref": "#/components/schemas/BookBalance"
},
"value_dated_balance": {
"$ref": "#/components/schemas/ValueDatedBalance"
},
"uncleared_funds": {
"$ref": "#/components/schemas/UnclearedFunds"
},
"uncleared_checks_balance": {
"$ref": "#/components/schemas/UnclearedChecksBalance"
},
"restricted_funds": {
"$ref": "#/components/schemas/RestrictedFundsBalance"
},
"held_funds": {
"$ref": "#/components/schemas/HeldFunds"
},
"held_checks_balance": {
"$ref": "#/components/schemas/HeldChecksBalance"
},
"remunerative_interest_accrued": {
"$ref": "#/components/schemas/RemunerativeInterestAccrued"
},
"children": {
"$ref": "#/components/schemas/Children"
},
"status": {
"$ref": "#/components/schemas/AccountStatus"
},
"external_account_id": {
"$ref": "#/components/schemas/ExternalAccountID"
},
"currency_numeric_code": {
"$ref": "#/components/schemas/CurrencyNumericCode"
},
"currency_alphabetic_code": {
"$ref": "#/components/schemas/CurrencyAlphabeticCode"
},
"document_number": {
"$ref": "#/components/schemas/DocumentNumber2"
},
"status_reason_id": {
"$ref": "#/components/schemas/AccountStatusReasonID"
},
"status_reason_description": {
"$ref": "#/components/schemas/AccountStatusReasonDescription"
},
"reason_external_id": {
"$ref": "#/components/schemas/AccountStatusReasonExternalID"
}
}
},
"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
},
"OverdraftLimit": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 18446744073709552000,
"description": "Account overdraft limit
\n`minimum: 0`\n`maximum: 18446744073709551617`\n",
"example": 123.45
},
"ParentAccountID2": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 4294967295,
"description": "Parent account ID. The account retrieved is the child of the account referenced by `parent_account_id`. The account referenced by `parent_account_id` can be in another program or division.
\n`minimum: 1`\n`maximum: 4294967295`\n",
"example": 123
},
"ProgramID2": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 4294967295,
"description": "Program ID
\n`minimum: 1`\n`maximum: 4294967295`\n",
"example": 492
},
"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": {
"401Unauthorized": {
"description": "Access token is missing or invalid"
},
"403Forbidden": {
"description": "The request has been lost"
},
"500InternalServer": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Generic internal error": {
"value": {
"code": "ECMN9999",
"message": "Internal error"
}
}
}
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/corporate/v1/corporate-accounts/{externalAccountId}": {
"get": {
"summary": "Get transaction banking account information",
"description": "Get the information for a transaction banking account.\n\n**NOTE**: This endpoint requires an account token - an access token encoded with an external account ID. Tokens can expire quickly, which can result in a `401 Unauthorized` message.\n",
"operationId": "get-accounts",
"parameters": [
{
"$ref": "#/components/parameters/ExternalAccountIdPath"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetAccountResponse"
},
"examples": {
"Account info": {
"value": {
"account_id": 184034550,
"division_code": "division-7",
"program_id": 10768,
"children": [
10983
],
"future_dated_credits_balance": 0,
"future_dated_debits_balance": 0,
"status": "DORMANT",
"external_account_id": "a4070788-bbe3-4127-8",
"currency_numeric_code": "840",
"currency_alphabetic_code": "USD",
"document_number": "1879063",
"status_reason_id": 1421,
"reason_external_id": "DEBIT_ONLy",
"status_reason_description": "Debit Only",
"account_creation_datetime": "2024-07-11T14:58:33.000Z",
"available_balance": 0,
"earmarked_balance": 0,
"overdraft_limit": 0,
"ledger_balance": 0,
"book_balance": 0,
"value_dated_balance": 0,
"uncleared_funds": 0,
"uncleared_checks_balance": 0,
"restricted_funds": 0
}
}
}
}
}
},
"400": {
"description": "A Bad Request validation error.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Account not found:": {
"value": {
"code": "WCAC0012",
"message": "Corporate account not found"
}
},
"division_code required": {
"value": {
"code": "WCAC0005",
"message": "division_code is a required field"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Account division not found": {
"value": {
"code": "WDIV0002",
"message": "Account division not found"
}
},
"Account balance not found": {
"value": {
"code": "WCAC0023",
"message": "Account balance not found"
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/500InternalServer"
}
},
"tags": [
"Accounts"
]
}
}
}
}
```