Commercial Accounts Reporting

Sleek and accurate search for accounts and transactions

Commercial Accounts Reporting Endpoints

Summary	Endpoint
Retrieve account details	get /commercial/accounts/v1/{accountId}
Search for accounts	get /commercial/accounts/v1/list
Search prior day account transactions	get /commercial/accounts/v1/{accountId}/transactions/previous
Search current day account transactions	get /commercial/accounts/v1/{accountId}/transactions/current

Key notes

Before you begin

To test or use any KeyBank API, you must be fully onboarded. This means having the right certificates, user credentials, and specific permissions for the API you're accessing.

Need help getting started? Check out our Get started section for everything you need to know.

Requirements

Request headers

HTTP request headers tell the server how to process the request and what format to use for the response. With the Commercial Accounts Reporting API, the following headers are required:

Accept

Specifies the expected response format. KeyBank APIs return JSON. Set this header to: Accept: application/json

The server responds with Content-Type: application/json.

Accept-Charset

Specifies the character encoding used for the request and response. Set this header to: Accept-Charset: UTF-8

AccountIdPath

Include the account ID in the request path to identify the account for which you want to retrieve data.

FapiInteractionHeader

A unique identifier (UUID) assigned to each request for tracking and support purposes. The ID must be 36 characters long.

UserAgent

Identifies the client application making the request, like the browser or integration tool. This is commonly used for troubleshooting and compatibility analysis.

Balance as of date

The balance as of date is a query option to return historical balance information from a certain date. Balance information includes opening and closed ledger balances, opening and closing available balances, and commercial balances.

Use the balanceAsOf field to define the length of the report data by date range.
The date range should be within 180 days from the current date.
Do not use the current date.
If a date is not provided, historical balance information is not returned.
The date provided should be in the format: YYYY-MM-DD.

Potential responses

Successful date ranges return a HTTP 200 or HTTP 206 message.

HTTP 200 returns full balance data. It is possible to have a successful response with no data if the date is valid but there are no records for that date.
HTTP 206 returns with closest prior record if the date is valid, but there are no records for that day (like it is a weekend date or a holiday).

Unsuccessful date ranges return a HTTP 400 or HTTP 404 message.

HTTP 400 with error code 703 returns if you provide today's date or a date too far in the past (beyond the 180 days).
HTTP 404 with error code 1107 returns if the request parameters do not have any records associated with the ID or for the date specified.

Retrieve account details

get /commercial/accounts/v1/{accountId}

Get full details about the account identified with the accountId parameter.

To include account balance information like opening and closing ledger amounts, be sure to specify the balanceAsOf date in the request.

Request

NAME	TYPE	DESCRIPTION
Acceptrequired	string	Accept
Accept-Charsetrequired	string	AcceptCharset
User-Agentrequired	string	UserAgent
FapiInteractionIdHeaderrequired	string	FapiInteractionIdHeader
AccountIdPathrequired	string	AccountIdPath
BalanceAsOfDateoptional	string	BalanceAsOfDate

Request example

curl --location: "https://partner-api-qv.key.com/commercial/accounts/v1/17e13f78-20c7-4ce6-ad4e-5afff48c8834?balanceAsOf=2025-08-21"
--header "Accept: application/json"
--header "Accept-Charset: UTF-8'
--header "User-Agent: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Mobile Safari/537.36 Edg/136.0.0.0'
--header "x-fapi-interaction-id: c770aef3-6784-41f7-8e0e-ff5f97bddb3a" 
--header "Bearer: testZcKJDWnwDWmmf9qah6PJvPy8"

Responses

Commercial Account

NAME	TYPE	DESCRIPTION
AccountWithDetails	object	AccountWithDetails

Response example (200)

{
  "accountId": "17e13f78-20c7-4ce6-ad4e-5afff48c8834",
  "accountNumberDisplay": "X5678", 

  "accountNumber": "012345678",
  "accountCategory": "COMMERCIAL_ACCOUNT",
  "currentAvailableBalance": 1000.1,
  "currentLedgerBalance": 3000.2,
  "openingLedgerBalance": 123.45,
  "closingLedgerBalance": 25000.99,
  "openingAvailableBalance": 15000.5,
  "closingAvailableBalance": 25000.36,
  "balanceAsOf": "2025-08-21T00:00:00.000Z",
  "commercialBalances": [
    {
      "commercialCode": {
        "type": "BAI",
        "code": "010",
        "memo": "Opening Ledger Balance"
      },
      "amount": 123.45
    },
    {
      "commercialCode": {
        "type": "BAI",
        "code": "015",
        "memo": "Closing Ledger Balance"
      },
      "amount": 25000.99
    },
    {
      "commercialCode": {
        "type": "BAI",
        "code": "040",
        "memo": "Opening Available Balance"
      },
      "amount": 15000.5
    },
    {
      "commercialCode": {
        "type": "BAI",
        "code": "045",
        "memo": "Closing Available Balance"
      },
      "amount": 25000.36
    }
  ]
}

Partial Success of Commercial Account

It is possible to have a success message with a HTTP 206 code that indicates a partial success. For example, only a portion of the records are returned from the full set or the record is returning partial data. This can occur if the balanceAsOf date requested is a weekend date or a non-business day. Or, this can occur in an unlikely event that a dependent system or provider is down or has reduced performance.

NAME	TYPE	DESCRIPTION
AccountWithDetails	object	AccountWithDetails

Response example (206)

{
  "accountCategory": "COMMERCIAL_ACCOUNT",
  "accountNumberDisplay": "X5678",
  "balanceAsOf": "2019-08-24",
  "openingLedgerBalance": 0,
  "closingLedgerBalance": 0,
  "currentLedgerBalance": 0,
  "openingAvailableBalance": 0,
  "currentAvailableBalance": 0,
  "closingAvailableBalance": 0,
  "commercialBalances": [
    {
      "commercialCode": {
        "type": "BAI",
        "code": "string"     
        },
      "amount": 0,
      "memo": "string"
      }  
    ]
  ]
}

Input sent by client does not satisfy API specification

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (400)

{
  "code": "401",
  "message": "Invalid input",
  "debugMessage": "Required header 'x-fapi-interaction-id' is not valid."			
}

Request lacks valid authentication credentials for the target resource

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (401)

{
  "code": "603",
  "message": "Unauthorized request",
  "debugMessage": "Please update the request and try again."			
}

Forbidden, server understands the request but refuses to authorize it

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (403)

{
  "code": "403",
  "message": "Forbidden",
  "debugMessage": "Please update the request and try again."			
}

Content Type not Supported

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (406)

{
  "code": "1203",
  "message": "Content Type not supported",
  "debugMessage": "Acceptable representations: [application/json, application/*+json]."
}

Search for accounts

get /commercial/accounts/v1/list

Retrieve a list of commercial payment accounts.

A successful response returns an array of accounts for authorized commercial clients. In the account details, an accountId is returned. This identifier is required to retrieve account details or to search for current or past day transactions.

Request

HEADER	TYPE	DESCRIPTION
Acceptrequired	string	Accept
Accept-Charsetrequired	string	AcceptCharset
User-Agentrequired	string	UserAgent
LimitQueryoptional	integer	LimitQuery
PageKeyQueryoptional	string	PageKeyQuery
FapiInteractionIdHeaderrequired	string	FapiInteractionIdHeader

Request example

curl --location: "https://partner-api-qv.key.com/commercial/accounts/v1/list?limit=50"
--header "Accept: application/json"
--header "Accept-Charset: UTF-8'
--header "User-Agent: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Mobile Safari/537.36 Edg/136.0.0.0'
--header "x-fapi-interaction-id: c770aef3-6784-41f7-8e0e-ff5f97bddb3a" 
--header "Bearer: testZcKJDWnwDWmmf9qah6PJvPy8"

Responses

Array of account (Account)

NAME	TYPE	DESCRIPTION
Accounts	object	Accounts

Response example (200)

{
  "page": {
    "nextPageKey": "2",
    "previousPageKey": "1",
    "totalElements": 3
  },
  "links": {
    "next": {
      "href": "https://partner-api.key.com/accounts/12345"
    },
    "prev": {
      "href": "https://domain.com/accounts/12345"
    }
  },
  "accounts": [
    {
     "accountCategory": "COMMERCIAL_ACCOUNT",
     "accountId": "17e13f78-20c7-4ce6-ad4e-5afff48c8834",
     "accountNumberDisplay": "X5678",
     "accountNumber": "012345678"
    }
  ]
}

Input sent by client does not satisfy API specification

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (400)

{
  "code": "401",
  "message": "Invalid input",
  "debugMessage": "Required header 'x-fapi-interaction-id' is not valid."			
}

Request lacks valid authentication credentials for the target resource

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (401)

{
  "code": "603",
  "message": "Authentication failed",
  "debugMessage": "Please update the request and try again."			
}

Forbidden, server understands the request but refuses to authorize it

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (403)

{
  "code": "403",
  "message": "Forbidden",
  "debugMessage": "Please update the request and try again."			
}

Data not found for request parameters

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (404)

{
  "code": "1107",
  "message": "Data not found for request parameters",
  "debugMessage": "Please adjust your search criteria and try again."
}

Content Type not Supported

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (406)

{
  "code": "1203",
  "message": "Content Type not supported",
  "debugMessage": "Acceptable representations: [application/json, application/*+json]."		
}

Search prior day account transactions

get /commercial/accounts/v1/{accountId}/transactions/previous

Search for past transactions by accountId and date range, startDate and endDate. Do not specify a date range to search yesterday's transactions. If you enter a date range, remember the following:

If you enter a start date, you must also provide an end date.
You can look up to 180 days in the past (about 6 months).
The end date cannot be the current date.
To search for a specific date, the start date and the end date must be the same date. For example, .../commercial/v1/accounts/accountId12345/transactions/previous?startDate=2025-02-15&endDate=2025-02-15.

Request

NAME	TYPE	DESCRIPTION
Acceptrequired	string	Accept
Accept-Charsetrequired	string	AcceptCharset
User-Agentrequired	string	UserAgent
FapiInteractionIdHeaderrequired	string	FapiInteractionIdHeader
AccountIdPathrequired	string	AccountIdPath
StartDateQueryoptional	string	StartDateQuery
EndDateQueryoptional	string	EndDateQuery
LimitQueryoptional	integer	LimitQuery
PageKeyQueryoptional	string	PageKeyQuery

Request example

curl --location: 'https://partner-api-qv.key.com/commercial/accounts/v1/FintechCo-25-7120aez/transactions/previous?startDate=2025-02-15&endDate=2025-02-28&limit=15&pageKey=2'
--header 'Accept: application/json'
--header 'Accept-Charset: UTF-8'
--header 'User-Agent: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Mobile Safari/537.36 Edg/136.0.0.0'
--header 'x-fapi-interaction-id: c770aef3-6784-41f7-8e0e-ff5f97bddb3a' 
--header 'Bearer: testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

Paginated collection of commercial transactions

NAME	TYPE	DESCRIPTION
transactions	array	Transactions

Response example (200)

{
  "page": {
    "nextPageKey": "2",
    "previousPageKey": "1",
    "totalElements": 3
  },
  "links": {
    "next": {
      "href": "https://partner-api.key.com/accounts/12345"
    },
    "prev": {
      "href": "https://partner-api.key.com/accounts/12345"
    }
  },
  "transactions": [
    {
      "accountCategory": "COMMERCIAL_ACCOUNT",
      "accountId": "17e13f78-20c7-4ce6-ad4e-5afff48c8834",
      "transactionId": "c83e25fa-f522-4b81-97fd-7b060fc76f38",
      "postedTimestamp": "2021-07-15T14:46:41.375",
      "transactionTimestamp": "2021-07-15T14:46:41.375",
      "description": "string",
      "debitCreditMemo": "CREDIT",
      "status": "AUTHORIZATION",
      "amount": 0,
      "lineItem": [
        {
          "description": "ACH",
          "amount": 0
        }
      ],
      "fiAttributes": [
        {
          "name": "transactionType",
          "value": "ACH"
        }
      ],
      "commercialCode": {
        "type": "BAI",
        "code": "string"
      }
    }
  ]
}

Partial Success of Prior Day

It is possible to have a success message with a HTTP 206 code that indicates a partial success. For example, only a portion of the records are returned from the full set or the record is returning partial data. This can occur if the daily batch hasn’t processed one or more of the dates being searched. Or, in an unlikely event that a dependent system or provider is down or has reduced performance. In either case, review the Content-Range response header for an explanation to the range of data provided.

NAME	TYPE	DESCRIPTION
AccountWithDetails	object	AccountWithDetails

Response example (206)

{
  "page": {
    "nextPageKey": "2",
    "previousPageKey": "1"
  },
  "links": {
    "next": {
      "href": "https://partner-api.key.com/accounts/12345"
    },
    "prev": {
      "href": "https://partner-api.key.com/accounts/12345"
    }
  },
  "transactions": [
    {
      "accountCategory": "COMMERCIAL_ACCOUNT",
      "accountId": "17e13f78-20c7-4ce6-ad4e-5afff48c8834",
      "transactionId": "c83e25fa-f522-4b81-97fd-7b060fc76f38",
      "postedTimestamp": "2021-07-15T14:46:41.375",
      "lineItem": [],
      "fiAttributes": [
        {
          "name": "transactionType",
          "value": "ACH"
        }
      ]
    }
  ]
}

Input sent by client does not satisfy API specification

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (400)

{
  "code": "401",
  "message": "Invalid input",
  "debugMessage": "Required header 'x-fapi-interaction-id' is not valid."			
}

Request lacks valid authentication credentials for the target resource

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (401)

{
  "code": "603",
  "message": "Authentication failed",
  "debugMessage": "Please update the request and try again."			
}

Forbidden, server understands the request but refuses to authorize it

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (403)

{
  "code": "403",
  "message": "Forbidden",
  "debugMessage": "Please update the request and try again."			
}

Data not found for request parameters

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (404)

{
  "code": "1107",
  "message": "Data not found for request parameters",
  "debugMessage": "Please adjust your search criteria and try again."
}

Content Type not Supported

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (406)

{
  "code": "1203",
  "message": "Content Type not supported",
  "debugMessage": "Acceptable representations: [application/json, application/*+json]."			
}

Search current day account transactions

get /commercial/accounts/v1/{accountId}/transactions/current

Search for current day transaction by accountId. Use pagination controls to limit or filter the data returned.

Request

NAME	TYPE	DESCRIPTION
Acceptrequired	string	Accept
Accept-Charsetrequired	string	AcceptCharset
User-Agentrequired	string	UserAgent
FapiInteractionIdHeader	string	FapiInteractionIdHeader
AccountIdPathrequired	string	AccountIdPath
LimitQueryoptional	integer	LimitQuery
PageKeyQueryoptional	string	PageKeyQuery

Request example

curl --location: 'https://partner-api-qv.key.com/commercial/v1/accounts/FintechCo-25-7120aez/transactions/current?limit=15&pageKey=3'
--header 'Accept: application/json'
--header 'Accept-Charset: UTF-8'
--header 'User-Agent: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Mobile Safari/537.36 Edg/136.0.0.0'
--header 'x-fapi-interaction-id: c770aef3-6784-41f7-8e0e-ff5f97bddb3a' 
--header 'Bearer: testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

Paginated collection of commercial transactions

NAME	TYPE	DESCRIPTION
transactions	array	Transactions

Response example (200)

{
  "page": {
    "nextPageKey": "2",
    "previousPageKey": "1",
    "totalElements": 3
  },
  "links": {
    "next": {
      "href": "https://partner-api.key.com/accounts/12345"
    },
    "prev": {
      "href": "https://partner-api.key.com/accounts/12345"
    }
  },
  "transactions": [
    {
      "accountCategory": "COMMERCIAL_ACCOUNT",
      "accountId": "17e13f78-20c7-4ce6-ad4e-5afff48c8834",
      "transactionId": "c83e25fa-f522-4b81-97fd-7b060fc76f38",
      "postedTimestamp": "2021-07-15T14:46:41.375",
      "transactionTimestamp": "2021-07-15T14:46:41.375",
      "description": "string",
      "debitCreditMemo": "CREDIT",
      "status": "AUTHORIZATION",
      "amount": 0,
      "lineItem": [
        {
          "description": "ACH",
          "amount": 0
        }
      ],
      "fiAttributes": [
        {
          "name": "transactionType",
          "value": "ACH"
        }
      ],
      "commercialCode": {
        "type": "BAI",
        "code": "string"
      }
    }
  ]
}

Input sent by client does not satisfy API specification

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (400)

{
  "code": "401",
  "message": "Invalid input",
  "debugMessage": "Required header 'x-fapi-interaction-id' is not valid."			
}

Request lacks valid authentication credentials for the target source

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (401)

{
  "code": "603",
  "message": "Authentication failed",
  "debugMessage": "Please update the request and try again."			
}

Forbidden, sever understands the request but refuses to authorize it

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (403)

{
  "code": "403",
  "message": "Forbidden",
  "debugMessage": "Please update the request and try again."			
}

Data not found for requested parameters

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (404)

{
  "code": "1107",
  "message": "Data not found for request parameters",
  "debugMessage": "Please adjust your search criteria and try again."
}

Content Type not Supported

NAME	TYPE	DESCRIPTION
Error	object	Error

Response example (406)

{
  "code": "1203",
  "message": "Content Type not supported",
  "debugMessage": "Acceptable representations: [application/json, application/*+json]."			
}

Schemas

x-fapi-interaction-id

NAME	TYPE	DESCRIPTION
x-fapi-interaction-id	string	FapiInteractionId

Accept

NAME	TYPE	DESCRIPTION
Accept	string	ContentTypes

AcceptCharset

NAME	TYPE	DESCRIPTION
AcceptCharset	string	Charsets

AccountIdPath

NAME	TYPE	DESCRIPTION
AccountIdPath	string	Account Identifier

BalanceAsOfDate

NAME	TYPE	DESCRIPTION
BalanceAsOfDate	string	DateString

FapiInteractionIdHeader

NAME	TYPE	DESCRIPTION
FapiInteractionIdHeader	object	FapiInteractionId

LimitQuery

NAME	TYPE	DESCRIPTION
LimitQuery	integer	Restrict the amount of data you receive. For accounts, the limit can be between 1 and 100. If omitted, the default is 50. For transactions, the limit can be between 1 and 500. If omitted, the default is 100.

PageKeyQuery

NAME	TYPE	DESCRIPTION
PageKeyQuery	string	A secure and flexible pagination capability to retrieve the following set of records.

StartDateQuery

NAME	TYPE	DESCRIPTION
StartDateQuery	string	Use start date to search a past date range. Leave the field blank to search prior day transactions. If you enter a date, you must also specify an end date. The start date cannot be older than 180 days from today. If no date range is provided, the request returns the prior weekday's information. Format: YYYY-MM-DD DateString

NAME

TYPE

DESCRIPTION

StartDateQuery

string

Use start date to search a past date range. Leave the field blank to search prior day transactions. If you enter a date, you must also specify an end date. The start date cannot be older than 180 days from today. If no date range is provided, the request returns the prior weekday's information. Format: YYYY-MM-DD

DateString

EndDateQuery

NAME	TYPE	DESCRIPTION
EndDateQuery	string	Use end date for a date range. Leave the field blank to search prior day transactions. If you enter a date, you must also specify a start date. The end date cannot be today's date. To search for a single day's transactions, make the end date the same as the start date. If no date range is provided, the request returns the prior weekday's information. Format: YYYY-MM-DD DateString

NAME

TYPE

DESCRIPTION

EndDateQuery

string

Use end date for a date range. Leave the field blank to search prior day transactions. If you enter a date, you must also specify a start date. The end date cannot be today's date. To search for a single day's transactions, make the end date the same as the start date. If no date range is provided, the request returns the prior weekday's information. Format: YYYY-MM-DD

DateString

UserAgent

NAME	TYPE	DESCRIPTION
UserAgent	string	Identifies the web browser and/or cURL command line used in the HTTP request. We collect this data to see which products use our API data services, helpful for troubleshooting and compatibility.

Account

NAME	TYPE	DESCRIPTION
Account	object	AccountDescriptor

Accounts

NAME	TYPE	DESCRIPTION
PaginatedArray	object	PaginatedArray
Accounts	array	Account

AccountWithDetails

NAME	TYPE	DESCRIPTION
AccountWithDetails	oneOf	CommercialAccount

AccountCategory

NAME	TYPE	DESCRIPTION
AccountCategory	string	The account type for the transaction. Valid values: COMMERCIAL_ACCOUNT

AccountDescriptor

NAME	TYPE	DESCRIPTION
accountCategoryrequired	Object	AccountCategory
accountId	Object	Identifier
accountNumberDisplay	string	The account display number suitable for the interface provider.
accountNumber	string	The bank account number.

Charsets

NAME	TYPE	DESCRIPTION
Charsets	string	The supported character set for the content. UTF-8 contains the accepted Unicode character list for standard English and Latin characters.

CommercialAccount

NAME	TYPE	DESCRIPTION
Commercial Account entity	allOf	Account
balanceAsOf	object	Timestamp
openingLedgerBalance	number	The ledger balance at the start of the business day (balance as-of date) for which the activity is being reported.
closingLedgerBalance	number	The ledger balance at the end of the business day (balance as-of date) for which the activity is being reported. Calculated as: Opening Ledger + Total Credits - Total Debits = Closing Ledger Balance
currentLedgerBalance	number	The ledger balance at the time during the day the information is being reported. It includes debits and credits that have been processed up to that time. Calculated as: Opening Ledger Balance + the Current Net of Debits and Credits = Current Ledger Balance.
openingAvailableBalance	number	The available balance at the start of the business day following the day for which activity is reported. Calculated as: Closing Available Balance Reported + The Net of One-day Float = Opening Available Balance.
currentAvailableBalance	number	The available balance at a given time during the business day the information is being reported. It includes zero-float debits and credits processed up to that time. Calculated as: Opening Available Balance + the Current Net of Zero Day Float Debits and Credits = Current Available Balance.
closingAvailableBalance	number	The available balance at the end of the business day for which activity is being reported. Calculated as: Closing Ledger Balance - Float = Closing Available Balance.
commercialBalances	array	CommercialBalance

CommercialBalance

NAME	TYPE	DESCRIPTION
commercialCode	object	CommercialCode
amount	number	The treasury management balance amount
memo	string	Memo field for the treasury management balance amount

CommercialCode

NAME	TYPE	DESCRIPTION
type	object	TreasuryManagementType
code	string	The code of the Treasury Management defined field

CommercialTransaction

NAME	TYPE	DESCRIPTION
CommercialTransaction	object	Transaction
commercialCode	object	CommercialCode

ContentTypes

NAME	TYPE	DESCRIPTION
ContentTypes	string	Types of supported document formats.

DateString

NAME	TYPE	DESCRIPTION
DateString	string	Date format based on ISO 8601 standards. Format: YYYY-MM-DD

Error

NAME	TYPE	DESCRIPTION
code	string	Code indicates the type of error that occurred.
message	string	Information associated with the code that helps you diagnose the error.
debugMessage	string	Message used to debug the root cause of the error and determine what needs correction in the request. Content can change depending on the request data provided.

FapiInteractionId

NAME	TYPE	DESCRIPTION
FapiInteractionId	string	Universally unique identifier for this interaction, used across all API requests and responses. A valid ID must be 36 characters in length.

FiAttribute

NAME	TYPE	DESCRIPTION
name	string	Name of attribute
value	string	Value of attribute

HateoasLink

NAME	TYPE	DESCRIPTION
href	string	URL address to invoke the action on the resource.

HateoasLinks

NAME	TYPE	DESCRIPTION
HateoasLinks	array	HateoasLink

Identifier

NAME	TYPE	DESCRIPTION
Identifieroptional	string	Value for a unique identifier

LineItem

NAME	TYPE	DESCRIPTION
description	string	Brief details about the transaction.
amount	number	The amount of money for this line item.

PageMetadata

NAME	TYPE	DESCRIPTION
nextPageKey	string	Displays the next page number. This is an opaque identifier and does not need to be numeric or have any specific pattern.
previousPageKey	string	Display the previous page number. This is an opaque identifier and does not need to be numeric or have any specific pattern.
totalElements	integer	Total number of elements

PageMetadataLinks

NAME	TYPE	DESCRIPTION
next	object	HateoasLink
prev	object	HateoasLink

PaginatedArray

NAME	TYPE	DESCRIPTION
page	Object	PageMetadata
links	Object	PageMetadataLinks

Timestamp

NAME	TYPE	DESCRIPTION
Timestamp	string	Date and time format based on ISO 8601 standard. Format: YYYY-MM-DDThh:mm:ss.nnn

Transaction

NAME	TYPE	DESCRIPTION
accountCategory	string	The account type for the transaction. Valid values: COMMERCIAL_ACCOUNT
accountId	string	The account identifier for the transaction.
transactionId	string	Long term persistent identity of the transaction (unique to account)
postedTimestamp	string	The date and time that the transaction was posted to the account. If the transaction is not yet posted, the transactionTimestamp value is returned. Format: YYYY-MM-DDThh:mm:ss.nnn
transactionTimestamp	string	The date and time that the transaction was added to the server and backend systems. Format: 'YYYY-MM-DDThh:mm:ss.nnn
description	string	The description of the transaction, such as information about a merchant's name or place of business in a manner that is user friendly and accessible to the customer.
debitCreditMemo	string	The posting type of a transaction. Valid values: DEBIT, CREDIT
status	string	The status of the transaction. Valid values: PENDING, POSTED
amount	number	The amount of funds in the currency of the account owner.
lineItem	array	LineItem
fiAttributes	array	FiAttribute
reference	string	A reference number like a check number or lockbox number.

TransactionStatus

NAME	TYPE	DESCRIPTION
TransactionStatus	string	The status of a transaction. Valid values: PENDING, POSTED

Transactions

NAME	TYPE	DESCRIPTION
PaginatedArray	object	PaginatedArray
Transactions	object	CommercialTransaction

TreasuryManagementType

NAME	TYPE	DESCRIPTION
TreasuryManagementType	string	Identifies the source of the treasury management account. Valid values: BAI, BTRS, ISO, SWIFT

Errors

For errors, a standard HTTP response is returned with a code that provides further details for why the request was unsuccessful. These errors follow a basic format with three parameters: code, message, and debugMessage.

Error reporting

HTTP status code	Error code	Error message
400	401	Invalid Input
403	403	Forbidden, inadequate authorization
409	409	Conflict with current state of target resource
500	500	Internal server error
501	501	Subsystem unavailable
503	503	Scheduled Maintenance
404	601	Customer not found
403	602	Customer not authorized
401	603	Authentication failed
404	701	Account not found
400	702	Invalid start for end date
400	703	Invalid date range
422	704	Account type not support
409	705	Account is Closed
404	800	Payee not found
400	801	Payee cannot be modified or deleted
404	802	Payment not found
400	803	Due date too soon
400	804	Payment rejected
400	805	Payment cannot be modified or cancelled
404	806	Recurring payment not found
400	807	Recurring payment rejected
400	808	Recurring payment cannot be modified or cancelled
404	901	Source account not found
404	902	Source account closed
401	903	Source account not authorized for transfer
404	904	Destination account not found
404	905	Destination account closed
401	906	Destination account not authorized for transfer
400	907	Invalid amount
409	908	Duplicate transfer request
503	909	Transfer not available due to end of day processing
400	910	Insufficient funds
400	911	Transaction limit exceeded
404	950	Transfer not found
500	1000	Unable to retrieve key from JWKS endpoint
404	1100	Update ID not found
404	1101	Reward program ID not found
404	1102	Categories not found for the reward program
404	1103	Image ID not found for Transaction
404	1104	Statement ID not found for account
501	1106	FDX version not supported or not implemented
404	1107	Data not found for request parameters
404	1108	Statements not found for given Account
404	1200	Tax form not found
400	1201	Tax form type not supported
400	1202	Tax year not supported
406	1203	Content type not supported
400	1204	Account ID is required
409	1205	Tax forms not yet been made available
405	1206	Method not allowed
429	1207	Too many requests
400	1300	Statement is processing

Changelog

1.0.3

June 2026 | LOW

Improved ledger balance descriptions for the CommericalAccounts schema, including details as to how the balance is calculated.
Simplified account descriptions in AccountDescriptor schema.
Added clarity to balanceAsOf field in the Key notes section and in Errors to assist with troubleshooting.

1.0.2

June 2026 | LOW

Removed 'Z' from timestamp parameters as the zone is automatically set to EDT (Eastern Daylight Time).

April 2026 | LOW

Added the accountNumber field to the AccountDescriptor object to support unmasked account number display for the /list endpoint.

1.0.1

February 2026 | LOW

Modified parameter options for debitCreditMemo, status, and TransactionStatus.

1.0.0

September 2025

Released on the Developer Portal.

Impact levels

LOW: This is a minor change or enhancement that does not alter the operations of the API. Upgrading to the latest specifications is preferable but not required.
MID: The previous API version is valid and operates, but does not contain latest enhancements. You need to update your specifications to get these enhancements.
HIGH: The previous API version is no longer operable. You must upgrade to the latest specifications to access and use this API product.

YAML file