openapi: 3.1.0 info: #--------------------------------------------------- # Information to contact the API provider #--------------------------------------------------- title: Commercial Accounts Reporting description: A set of commercial accounting APIs used to get account-level information for client authorized accounts. contact: name: KeyBank Developer Support email: embedded_banking_support@keybank.com version: 1.0.3 servers: #--------------------------------------------------- # List of Environments for the API #--------------------------------------------------- # Non-Production environment URL (QV) - url: https://partner-api-qv.key.com # Production and Simulator environment URL - url: https://partner-api.key.com paths: #--------------------------------------------------- # List of API flows #--------------------------------------------------- /commercial/accounts/v1/{accountId}: get: operationId: getAccount tags: - Account Information summary: Retrieve account details description: Get full details about the account identified with accountId parameter. parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/AcceptCharset' - $ref: '#/components/parameters/UserAgent' - $ref: '#/components/parameters/FapiInteractionIdHeader' - $ref: '#/components/parameters/AccountIdPath' - $ref: '#/components/parameters/BalanceAsOfDate' responses: '200': description: Commercial Account headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/AccountWithDetails' example: accountId: "17e13f78-20c7-4ce6-ad4e-5afff48c8834" accountNumberDisplay: "X5678" accountNumber: "012345678" accountCategory: COMMERCIAL_ACCOUNT currentAvailableBalance: 1000.10 currentLedgerBalance: 3000.20 openingLedgerBalance: 123.45 closingLedgerBalance: 25000.99 openingAvailableBalance: 15000.5 closingAvailableBalance: 25000.36 balanceAsOf: 2025-08-21 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 '206': description: Partial Success of Commercial Account headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/AccountWithDetails' '400': description: Input sent by client does not satisfy API specification headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid Input: value: code: '401' message: Invalid Input debugMessage: Required header 'x-fapi-interaction-id' is not valid. '401': description: Request lacks valid authentication credentials for the target resource headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Unauthorized: value: code: '603' message: Authentication failed debugMessage: Please update the request and try again. '403': description: Forbidden, server understands the request but refuses to authorize it headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Forbidden: value: code: '403' message: Forbidden debugMessage: Please update the request and try again. '406': description: Content Type not Supported headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Content Type not Supported: value: code: '1203' message: Content Type not Supported debugMessage: "Acceptable representations: [application/json, application/*+json]." /commercial/accounts/v1/list: get: operationId: searchForAccounts tags: - Account Information summary: Search for accounts description: Return information for all client authorized accounts parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/AcceptCharset' - $ref: '#/components/parameters/UserAgent' - $ref: '#/components/parameters/LimitQuery' - $ref: '#/components/parameters/PageKeyQuery' - $ref: '#/components/parameters/FapiInteractionIdHeader' responses: '200': description: Array of accounts (Account) headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Accounts' '400': description: Input sent by client does not satisfy API specification headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid Input: value: code: '401' message: Invalid Input debugMessage: Required header 'x-fapi-interaction-id' is not valid. '401': description: Request lacks valid authentication credentials for the target resource headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Unauthorized: value: code: '603' message: Authentication failed debugMessage: Please update the request and try again. '403': description: Forbidden, server understands the request but refuses to authorize it headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Forbidden: value: code: '403' message: Forbidden debugMessage: Please update the request and try again. '404': description: Data not found for request parameters headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Data not found for request parameters: value: code: '1107' message: Data not found for request parameters debugMessage: Please adjust your search criteria and try again. '406': description: Content Type not Supported headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Content Type not Supported: value: code: '1203' message: Content Type not Supported debugMessage: "Acceptable representations: [application/json, application/*+json]." /commercial/accounts/v1/{accountId}/transactions/previous: get: operationId: searchForPreviousDayAccountTransactionsV1 tags: - Account Transactions description: "Search for account transactions. Example:/accounts/{accountId}/transactions/previous?startTime=value1&endTime=value2" summary: Search prior day account transactions parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/AcceptCharset' - $ref: '#/components/parameters/UserAgent' - $ref: '#/components/parameters/FapiInteractionIdHeader' - $ref: '#/components/parameters/AccountIdPath' - $ref: '#/components/parameters/StartDateQuery' - $ref: '#/components/parameters/EndDateQuery' - $ref: '#/components/parameters/LimitQuery' - $ref: '#/components/parameters/PageKeyQuery' responses: '200': description: Paginated collection of commercial transactions headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Transactions' '206': description: Partial Success of Prior Day headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/AccountWithDetails' '400': description: Input sent by client does not satisfy API specification headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid Input: value: code: '401' message: Invalid Input debugMessage: Required header 'x-fapi-interaction-id' is not valid. '401': description: Request lacks valid authentication credentials for the target resource headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Unauthorized: value: code: '603' message: Authentication failed debugMessage: Please update the request and try again. '403': description: Forbidden, server understands the request but refuses to authorize it headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Forbidden: value: code: '403' message: Forbidden debugMessage: Please update the request and try again. '404': description: Data not found for request parameters headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Data not found for request parameters: value: code: '1107' message: Data not found for request parameters debugMessage: Please adjust your search criteria and try again. '406': description: Content Type not Supported headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Content Type not Supported: value: code: '1203' message: Content Type not Supported debugMessage: "Acceptable representations: [application/json, application/*+json]." /commercial/accounts/v1/{accountId}/transactions/current: get: operationId: searchForCurrentDayAccountTransactionsV1 tags: - Account Transactions description: Search for account transactions that have not posted. summary: Search current day account transactions parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/AcceptCharset' - $ref: '#/components/parameters/UserAgent' - $ref: '#/components/parameters/FapiInteractionIdHeader' - $ref: '#/components/parameters/AccountIdPath' - $ref: '#/components/parameters/LimitQuery' - $ref: '#/components/parameters/PageKeyQuery' responses: '200': description: Paginated collection of commercial transactions headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Transactions' '400': description: Input sent by client does not satisfy API specification headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid Input: value: code: '401' message: Invalid Input debugMessage: Required header 'x-fapi-interaction-id' is not valid. '401': description: Request lacks valid authentication credentials for the target resource headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Unauthorized: value: code: '603' message: Authentication failed debugMessage: Please update the request and try again. '403': description: Forbidden, server understands the request but refuses to authorize it headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Forbidden: value: code: '403' message: Forbidden debugMessage: Please update the request and try again. '404': description: Data not found for request parameters headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Data not found for request parameters: value: code: '1107' message: Data not found for request parameters debugMessage: Please adjust your search criteria and try again. '406': description: Content Type not Supported headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Content Type not Supported: value: code: '1203' message: Content Type not Supported debugMessage: 'Acceptable representations: [application/json, application/*+json].' components: headers: x-fapi-interaction-id: description: Unique identifier for this interaction schema: $ref: '#/components/schemas/FapiInteractionId' example: c770aef3-6784-41f7-8e0e-ff5f97bddb3a parameters: Accept: name: Accept in: header description: Preferred syntax for content type. This content type should be application/json. schema: $ref: '#/components/schemas/ContentTypes' required: true example: application/json AcceptCharset: name: Accept-Charset in: header description: The supported character set for the content. UTF-8 contains the accepted Unicode character list for standard English and Latin characters. schema: $ref: '#/components/schemas/Charsets' required: true example: UTF-8 AccountIdPath: name: accountId in: path description: Account Identifier required: true schema: type: string BalanceAsOfDate: name: balanceAsOf in: query description: "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. The date must be within 180 days of the current date. If a date is not provided, historical balance information is not returned. Format: YYYY-MM-DD" schema: $ref: '#/components/schemas/DateString' FapiInteractionIdHeader: name: x-fapi-interaction-id in: header description: Unique identifier for this interaction. A valid ID must be 36 characters in length. This is used across all API requests and responses. schema: $ref: '#/components/schemas/FapiInteractionId' required: true example: c770aef3-6784-41f7-8e0e-ff5f97bddb3a LimitQuery: name: limit in: query description: 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. schema: type: integer minLength: 1 maxLength: 500 example: 50 PageKeyQuery: name: pageKey in: query description: A secure and flexible pagination capability to retrieve the following set of records. schema: type: string StartDateQuery: name: startDate in: query description: "Start date to search a past date range. Leave blank to search prior day transactions. If you enter a date, you must also specify an end date. Start date can not 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" schema: $ref: '#/components/schemas/DateString' EndDateQuery: name: endDate in: query description: "End date for a date range. Leave 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" schema: $ref: '#/components/schemas/DateString' UserAgent: name: User-Agent in: header description: 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. schema: type: string required: true example: 'Example/1.2.3 Crawler/4.3.1' schemas: Account: title: Account entity description: Contains basic account information type: object allOf: - $ref: '#/components/schemas/AccountDescriptor' Accounts: title: Accounts entity description: Paginated array of accounts type: object allOf: - $ref: '#/components/schemas/PaginatedArray' - type: object properties: accounts: type: array description: A list of commercial accounts items: $ref: '#/components/schemas/Account' AccountWithDetails: title: Account With Details entity description: Detailed information about an authorized client account. If the BalanceAsOfDate is provided, balance summary information is also returned. type: object discriminator: propertyName: accountCategory mapping: COMMERCIAL_ACCOUNT: '#/components/schemas/CommercialAccount' oneOf: - $ref: '#/components/schemas/CommercialAccount' AccountCategory: title: Account Category type description: "The account type for the transaction. Valid values: COMMERCIAL_ACCOUNT" type: string enum: - COMMERCIAL_ACCOUNT AccountDescriptor: title: Account Descriptor entity description: Basic account information including the account category, GUID, and account number. type: object required: - accountCategory discriminator: propertyName: accountCategory properties: accountCategory: $ref: '#/components/schemas/AccountCategory' description: The account type. KeyBank currently supports only commercial account types. accountId: description: A long-term persistent identity of the account that is not the account number. This identity must be unique to the owning institution. $ref: '#/components/schemas/Identifier' accountNumberDisplay: description: The account display number suitable for the interface provider. type: string example: 'X5678' accountNumber: type: string description: The bank account number. example: '012345678' Charsets: title: Character Sets description: 'The supported character set for the content. UTF-8 contains the accepted Unicode character list for standard English and Latin characters.' type: string enum: - UTF-8 CommercialAccount: title: Commercial Account entity description: Information related to the commercial account type: object allOf: - $ref: '#/components/schemas/Account' - type: object properties: balanceAsOf: description: As-of date of balances $ref: '#/components/schemas/Timestamp' openingLedgerBalance: type: number description: The ledger balance at the start of the business day (balance as-of date) for which the activity is being reported. closingLedgerBalance: type: number description: '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: type: number description: '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: type: number description: '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: type: number description: '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: type: number description: '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: type: array description: A list of specific treasury management defined balances items: $ref: '#/components/schemas/CommercialBalance' CommercialBalance: title: Commercial Balance entity description: A specific treasury management defined balance type: object properties: commercialCode: $ref: '#/components/schemas/CommercialCode' description: The code for a specific treasury management defined field amount: type: number description: The treasury management balance amount memo: type: string description: Memo field for the treasury management balance amount CommercialCode: title: Commercial Code entity description: Code for commercial transactions that retrieves the summary, account information, and related transaction codes from the treasury object. The code for a specific treasury management defined field. type: object properties: type: $ref: '#/components/schemas/TreasuryManagementType' description: 'The source of treasury management account definition. Valid values: BAI, BTRS, ISO, SWIFT' code: type: string description: The code of the Treasury Management defined field CommercialTransaction: title: Commercial Transaction entity description: A transaction on a commercial account type. type: object allOf: - $ref: '#/components/schemas/Transaction' - type: object properties: commercialCode: $ref: '#/components/schemas/CommercialCode' description: The treasury management type and code for the account. ContentTypes: title: Content Types description: Types of supported document formats. type: string enum: - application/json DateString: title: Date String description: 'Date format based on ISO 8601 standards. Format: YYYY-MM-DD' type: string format: date maxLength: 10 example: '2025-02-15' Error: title: Error description: Contains details if there is an issue with the API or the account. type: object properties: code: type: string description: Code indicates the type of error that occurred. message: type: string description: Information associated with the code that helps you diagnose the error. debugMessage: type: string description: 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: title: FAPI Interaction ID description: Universally unique identifier for this interaction, used across all API requests and responses. A valid ID must be 36 characters in length. type: string format: uuid minLength: 36 maxLength: 36 example: 'c770aef3-6784-41f7-8e0e-ff5f97bddb3a' FiAttribute: title: FI Attribute entity description: Additional information provided by the client financial institution (FI). This information can be related addenda information and additional data related to the accounts transactions. type: object properties: name: type: string description: Name of attribute example: transactionType value: type: string description: Value of attribute example: ACH HateoasLink: title: HATEOAS Link description: "HATEOAS is 'Hypermedia As The Engine Of Application State,' a REST application constraint for URL addresses." required: [href] type: object properties: href: type: string format: uri-reference description: URL address to invoke the action on the resource. example: "https://partner-api.key.com/accounts/12345" HateoasLinks: title: HATEOAS Links array description: Array of hyperlinks associated with the call. type: array items: $ref: '#/components/schemas/HateoasLink' Identifier: title: Identifier description: Value for a unique identifier type: string maxLength: 256 LineItem: title: Line Item entity description: A line item within a transaction. type: object properties: description: type: string description: Brief details about the transaction. example: ACH amount: type: number description: The amount of money for this line item. PageMetadata: title: Page Metadata description: Page information based on the pagination controls and result set. type: object properties: nextPageKey: type: string example: "2" description: Displays the next page number. This is an opaque identifier and does not need to be numeric or have any specific pattern. previousPageKey: type: string example: "1" description: Display the previous page number. This is an opaque identifier and does not need to be numeric or have any specific pattern. totalElements: type: integer example: 3 description: Total number of elements PageMetadataLinks: title: Page Metadata Links description: Resource URLs for retrieving next or previous datasets. type: object properties: next: $ref: '#/components/schemas/HateoasLink' description: Resource URL for retrieving next dataset prev: $ref: '#/components/schemas/HateoasLink' description: Resource URL for retrieving previous dataset PaginatedArray: title: Paginated Array description: Page metadata and related URLs for the result set. type: object properties: page: $ref: '#/components/schemas/PageMetadata' description: Offset IDs for navigating result sets links: $ref: '#/components/schemas/PageMetadataLinks' description: Resource URLs for navigating result sets Timestamp: title: Timestamp description: "Date and time format based on ISO 8601 standard. Format: 'YYYY-MM-DDThh:mm:ss.nnn" type: string format: date-time Transaction: title: Transaction description: Base entity for financial transactions type: object required: - accountCategory discriminator: propertyName: accountCategory properties: accountCategory: type: string description: "The account type for the transaction. Valid values: COMMERCIAL_ACCOUNT" enum: - COMMERCIAL_ACCOUNT example: 'COMMERCIAL_ACCOUNT' accountId: type: string description: The account identifier for the transaction. maxLength: 256 example: '17e13f78-20c7-4ce6-ad4e-5afff48c8834' transactionId: type: string description: Long term persistent identity of the transaction (unique to account) maxLength: 256 postedTimestamp: type: string description: "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" format: date-time example: '2021-07-15T14:46:41.375' transactionTimestamp: type: string description: "The date and time that the transaction was added to the server and backend systems. Format: 'YYYY-MM-DDThh:mm:ss.nnn" format: date-time example: '2021-07-15T14:46:41.375' description: type: string description: 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: description: "The posting type of a transaction. Valid values: DEBIT, CREDIT" type: string enum: - CREDIT - DEBIT status: type: string description: "The status of the transaction. Valid values: PENDING, POSTED" enum: - PENDING - POSTED amount: type: number description: The amount of funds in the currency of the account owner. lineItem: type: array description: Details by line item to help organize and share transaction details items: $ref: '#/components/schemas/LineItem' fiAttributes: type: array description: Array of attributes specific to the financial institution. items: $ref: '#/components/schemas/FiAttribute' reference: type: string description: A reference number like a check number or lockbox number. TransactionStatus: title: Transaction Status description: 'The status of a transaction. Valid values: PENDING, POSTED' type: string enum: - PENDING - POSTED Transactions: title: Transactions entity description: Optionally paginated array of transactions type: object allOf: - $ref: '#/components/schemas/PaginatedArray' - type: object properties: transactions: description: An array of transactions with for commercial entities. type: array items: discriminator: propertyName: accountCategory mapping: COMMERCIAL_ACCOUNT: '#/components/schemas/CommercialTransaction' oneOf: - $ref: '#/components/schemas/CommercialTransaction' TreasuryManagementType: title: Treasury Management Type description: "Identifies the source of the treasury management account. Valid values: BAI, BTRS, ISO, SWIFT" type: string enum: - BAI - BTRS - ISO - SWIFT example: BAI