openapi: 3.1.0
info:
#---------------------------------------------------
# Information to contact the API provider
#--------------------------------------------------- 
  title: Commercial Account Reporting
  description: Search for account information and retrieve previous or current day transactions.
  contact: 
   name: "KeyBank Developer Support"
   email: "developers@keybank.com"
  version: 1.0.0           

servers:
#---------------------------------------------------
# List of Environments for the API
#---------------------------------------------------
 - url: https://partner-api-qv.key.com
 - 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/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountWithDetails'
              examples:
                CommercialAccount:
                  value:
                    accountId: 17e13f78-20c7-4ce6-ad4e-5afff48c8834
                    accountNumberDisplay: X2595
                    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 CommercialAccount
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          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/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Invalid Input:
                  value:
                    code: '401'
                    message: Invalid Input
                    debugMessage: Data Provider's custom developer-level error details for troubleshooting
        '401':
          description: Request lacks valid authentication credentials for the target resource
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Unauthorized:
                  value:
                    code: '603'
                    message: Authentication failed
                    debugMessage: Data Provider's custom developer-level error details for troubleshooting
        '403':
          description: Forbidden, server understands the request but refuses to authorize it
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Forbidden:
                  value:
                    code: '403'
                    message: Forbidden
                    debugMessage: Data Provider's custom developer-level error details for troubleshooting
        '406':
          description: Content Type not Supported
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Content Type not Supported:
                  value:
                    code: '1203'
                    message: Content Type not Supported
                    debugMessage: Data Provider's custom developer-level error details for troubleshooting
  
  /commercial/accounts/v1/list:
    get:
      operationId: searchForAccounts
      tags:
        - Account Information
      summary: Search for accounts
      description: Retrieve a list of commercial payment accounts for client authorized accounts. 
      parameters:
        - $ref: '#/components/parameters/Accept'
        - $ref: '#/components/parameters/AcceptCharset'
        - $ref: '#/components/parameters/UserAgent'
        - $ref: '#/components/parameters/LimitQuery'
        - $ref: '#/components/parameters/FapiInteractionIdHeader'
      responses:
        '200':
          description: Success - array of commercial accounts
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Accounts'
        '400':
          description: Missing mandatory information
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Invalid Input:
                  value:
                    code: '401'
                    message: Invalid Input
                    debugMessage: Input does not satisfy API specification. Review required fields and retry request. 
        '401':
          description: Unauthorized request
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Unauthorized:
                  value:
                    code: '603'
                    message: Authentication failed
                    debugMessage: Request lacks valid authentication credentials for the target resource. Review your bearer token response and verify if you have authorization to access this product. 
        '403':
          description: Forbidden request access
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Forbidden:
                  value:
                    code: '403'
                    message: Forbidden
                    debugMessage: The server understands the requests but refuses to authorize the request. This could be an issue with credentials. 
        '404':
          description: Resource not found
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          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: Alter the request parameters to attempt to obtain a successful response. 
        '406':
          description: Content Type not supported
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Content Type not Supported:
                  value:
                    code: '1203'
                    message: Content Type not Supported
                    debugMessage: Review header information to make sure that the content type and encoding values are correct.

  /commercial/accounts/v1/{accountId}/transactions/previous:
    get:
      operationId: searchForPreviousDayAccountTransactionsV1
      tags:
        - Account Transactions
      description: Search prior day transactions by account ID
      summary: Search for 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: Success - paginated collection of commercial transactions for a previous date or date range
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transactions'
        '400':
          description: Missing mandatory information
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Invalid Input:
                  value:
                    code: '401'
                    message: Invalid Input
                    debugMessage: Data Provider's custom developer-level error details for troubleshooting
        '401':
          description: Unauthorized request
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Unauthorized:
                  value:
                    code: '603'
                    message: Authentication failed
                    debugMessage: Data Provider's custom developer-level error details for troubleshooting
        '403':
          description: Forbidden request access
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Forbidden:
                  value:
                    code: '403'
                    message: Forbidden
                    debugMessage: Data Provider's custom developer-level error details for troubleshooting
        '404':
          description: Resource not found
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          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: Data Provider's custom developer-level error details for troubleshooting
        '406':
          description: Content Type not supported
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Content Type not Supported:
                  value:
                    code: '1203'
                    message: Content Type not Supported
                    debugMessage: Data Provider's custom developer-level error details for troubleshooting


  /commercial/accounts/v1/{accountId}/transactions/current:
    get:
      operationId: searchForCurrentDayAccountTransactionsV1
      tags:
        - Account Transactions
      description: Search current day transactions by account ID 
      summary: "Search for account transactions. Example:
        /accounts/{accountId}/transactions/previous?startTime=value1&endTime=value2"
      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: Success - paginated collection of commercial transactions for current day
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transactions'
        '400':
          description: Missing mandatory information
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Invalid Input:
                  value:
                    code: '401'
                    message: Invalid Input
                    debugMessage: Data Provider's custom developer-level error details for troubleshooting
        '401':
          description: Unauthorized request
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Unauthorized:
                  value:
                    code: '603'
                    message: Authentication failed
                    debugMessage: Data Provider's custom developer-level error details for troubleshooting
        '403':
          description: Forbidden request access
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Forbidden:
                  value:
                    code: '403'
                    message: Forbidden
                    debugMessage: Data Provider's custom developer-level error details for troubleshooting
        '404':
          description: Resource not found
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          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: Data Provider's custom developer-level error details for troubleshooting
        '406':
          description: Content Type not supported
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/parameters/FapiInteractionIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Content Type not Supported:
                  value:
                    code: '1203'
                    message: Content Type not Supported
                    debugMessage: Data Provider's custom developer-level error details for troubleshooting

components:
  parameters:
    Accept:
      name: Accept
      in: header
      description: Preferred syntax for content type. This content type should be application/json. 
      required: true
      schema:
        title: Content Types
        type: string
        enum:
          - application/json
      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:
        title: Character Sets
        type: string
        enum:
          - UTF-8
        maxLength: 16
    AccountIdPath:
      name: accountId
      in: path
      description: An unique identification number generated from the /commercial/accounts/v1/list endpoint.
      required: true
      schema:
        type: string
    BalanceAsOfDate:
      name: balanceAsOf
      in: query
      description: "A query option to return the balance information from a certain date. The date must be withing 180 days of the current date. If a date is not provided, balance information is not be included in the response. Format: YYYY-MM-DD"
      schema:
        title: Date String
        type: string
        format: date
        maxLength: 10
      example: '2025-02-15'
    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:
        title: FAPI Interaction ID
        type: string
        format: uuid
        minLength: 36
        maxLength: 36
      example: c770aef3-6784-41f7-8e0e-ff5f97bddb3a
    LimitQuery:
      name: limit
      in: query
      description: Restrict the amount of data you receive. The limit can be an integer from 1 to 500. If the limit is not specified, a default limit of 100 will be used.
      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
        example: need example
    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. Format: YYYY-MM-DD"
      schema:
        title: Date String
        type: string
        format: date
        maxLength: 10
      example: '2025-02-15'
    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. Format: YYYY-MM-DD"
      schema:
        title: Date String
        type: string
        format: date
        maxLength: 10
      example: '2025-06-15'
    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: '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'
  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/AccountWithDetails'
    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. Currently, KeyBank supports 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.
          type: string
          maxLength: 256
        accountNumberDisplay:
          description: The account display number suitable for the interface provider.
          type: string
    AccountWithDetails:
      title: Account with details entity
      description: Contains details about the commercial account. 
      type: object
      discriminator:
        propertyName: accountCategory
        mapping:
          COMMERCIAL_ACCOUNT: '#/components/schemas/CommercialAccount'
      oneOf:
        - $ref: '#/components/schemas/CommercialAccount'
    CommercialAccount:
      title: Commercial Account entity
      description: Information related to the commercial account
      type: object
      allOf:
        - $ref: '#/components/schemas/Account'
    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'
        code:
          type: string
          description: The code of the Treasury Management defined field
          example: 398
    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. 
    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.
    FiAttribute:
      title: FI Attribute entity
      description: Free-form text fields to define a name:value pair. Typically, the name:value is used to define transaction type. 
      type: object
      properties:
        name:
          type: string
          description: Name of attribute
          example: transactionType
        value:
          type: string
          description: Value of attribute
          example: CHECK
    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://api.fi.com/fdx/v4/accounts/12345"
    HateoasLinks:
      title: HATEOAS Links array
      description: Array of hyperlinks associated with the call. 
      type: array
      items:
        $ref: '#/components/schemas/HateoasLink'
    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: CHECK
        amount:
          type: number
          description: The amount of money for this line item.
        checkNumber:
          type: integer
          description: The check number for a check payment associated with the line item. 
          example: 9876
    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
    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
        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[Z]"
          format: date-time
          example: '2021-07-15T14:46:41.375Z'
        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[Z]"
          format: date-time
          example: '2021-07-15T14:46:41.375Z'
        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, MEMO"
          type: string
          enum:
            - CREDIT
            - DEBIT
            - MEMO
        status:
          type: string
          description: "The status of the transaction. Valid values: PENDING, MEMO, POSTED, AUTHORIZATION"
          enum:
          - AUTHORIZATION
          - MEMO
          - 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'
    TransactionStatus:
      title: Transaction Status
      description: The status of a transaction
      type: string
      enum:
        - AUTHORIZATION
        - MEMO
        - 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 entity type dependent on the account type
                (commercial, deposit, insurance, investment, line of credit, loan or digital wallet)
              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