This page provides foundational information to help you become familiar with our APIs. Security At KeyBank, we take security seriously. To keep the APIs and the returned data protected, we use several authentication and authorization methods to stop any potential threats. Certificates We use the Mutual Transport Layer Security (mTLS) protocol to ensure that API traffic to and from KeyBank is secure and trusted. This mutual authentication requires both you and KeyBank to exchange valid digital certificates with each other, establishing a shared trust. Certificates are electronic documents that verify your authenticity and identity. Your certificate cannot be self-signed but must be issued and signed by a publicly trusted certificate authority. Authentication and authorization To protect the KeyBank API server and your application, we secure our REST APIs with OAuth 2.0 security (an industry standard protocol for authentication and authorization). The terms authorization and authentication are used often and typically with one another, but there are two different meanings. Authentication validates your identity with KeyBank client credentials (part of your API keys). Authorization permits use of the APIs with a bearer token. Authentication and authorization are mutually exclusive, each a different layer of security. For instance, it is possible that you can authenticate an API that you are not authorized to use. API keys For the pre-production test environment and the production environment, both application credentials and client credentials are required. These API keys are created only for authenticated users that have partnered with KeyBank. Bearer token Bearer tokens are the primary way to access an API secured with OAuth 2.0. Only authenticated users with client credentials can request a bearer token. Health check A health check accesses the API to make sure that the application endpoint can receive the request and confirm there are no interruptions to service. KeyBank recommends that you perform a health check before you start building with the APIs. To perform a health check, you must complete the onboarding process and be an authenticated user with KeyBank. As an authenticated user, you will have your system configured and receive the necessary information required to access KeyBank APIs. For a health check, you must have valid certificates exchanged with KeyBank, have API keys like client credentials, and can get bearer token to pass in the health check call. If the API is operating correctly, the HTTP 200 status message displays that the system is okay. Below is an example of the format for a successful API health check. { "Status": "Ok", "Source": "Roundtrip", "Timestamp": "2022-09-15T04:49:03", "ClientIp": "156.77.111.28", "X-Forwarded-For": "[156.77.111.28]" } If the API is not in service, the HTTP 400 status message displays that the API service is not available. Health check endpoints API Endpoint Account Validation GET /accounts/validations/v1/healthCheck ACH Origination GET /ach/payments/v1/healthCheck ACH Inquiry GET /accounts/transactions/v1/healthCheck Wire Origination GET /rtp/v1/payment/healthCheck Wire Inquiry GET /wireInquiry/v1/healthCheck RTP Send Payment GET /rtp/v1/payment/healthCheck Previous Day Reporting GET /ddaReports/accounts/v1/healthCheck Intraday Reporting GET /ddaReports/accounts/v1/healthCheck Check Image Retrieval GET /cmi/v1/healthCheck Stop Payment GET /accounts/payments/v1/healthCheck Requests Rate limiting To ensure efficient and consistent API performance, we've placed a limit of 5 transactions per second (TPS) across all KeyBank APIs. Exceeding the rate limit API requests that exceed the rate limit receive an HTTP 429 response status code. If you've exceeded this limit, wait for at least 2 minutes before making another API call. Requesting a rate limit increase While we established the 5 TPS threshold to maximize stability and performance, we understand that your consumption needs might not fit within those limits. To request an increased rate limit, contact your KeyBank Client Success Manager. Request header recommendations Consider these recommended request headers when you build your APIs. These recommendations are to improve your experience as you test, integrate, and use the KeyBank APIs. Each suggested practice helps reduce potential errors. If an error occurs, these additional settings give you a better understanding of when and where an issue happened. Accept The Accept request header communicates what type of media should be in the response. In most cases this should be application/json. Content-Type The Content-Type request header communicates what type of media is being sent in the request. Use one of two options: To request a bearer token, use application/x-www-form-urlencoded. For API calls, use application/json. X-CorrelationID The X-CorrelationID request header creates a unique identifier for each API operation. This field allows you to trace the chain of API operations in event logs. KeyBank strongly recommends that you use this header in each request to better support troubleshooting or data refinement. Requirements by API Some APIs have required request fields with KeyBank-provided values. The KeyBank onboarding team shares these required field values with you via email. All required request fields must be complete to be able to successfully submit a request. Most of the required request values are environment specific. This means that there will be different values provided for the pre-production and the production environments. The only exception is the ACH Origination API which can use the values provided for its required request fields in both environments. Pagination You can use pagination parameters to manage a response with large amounts of data. Adjusting these parameters can improve system performance. You can limit or parse data to prevent a lag or delay in a response. You can control how much information is returned in a response. Pagination parameters are usually available on APIs that return lists of transactions like the ACH Inquiry API, Wire Inquiry API, Previous Day API, Intraday API, and RTP Send Payment API. There are several pagination parameters that can help you control how an endpoint will return the information requested. ENDPOINTS WITH PAGINATION PAGINATION PARAMETER API ENDPOINT REQUIRED OR OPTIONAL startRowIndex endRowIndex ACH Inquiry POST /accounts/transactions/v1/returnACHtransactions/list POST /accounts/transactions/v1/collectedACHtransactions/list POST /accounts/transactions/v1/postedACHtransactions/list POST /accounts/transactions/v1/ACHStatusInquiry/list Optional startRowIndex endRowIndex Wire Inquiry POST /wireInquiry/v1/transactions/details Optional startRowIndex endRowIndex Previous Day POST /ddaReports/accounts/v1/transactions/list Optional startRowIndex endRowIndex Intraday POST /ddaReports/accounts/v1/transactions/intraday/list Optional limit offset RTP Send Payment GET /rtp/v1/payment/rtp/participant Required Common pagination controls Row pagination There are common pagination parameters like startRowIndex and endRowIndex that help retrieve and organize large data sets into separate, scrollable pages. This is commonly used with information reporting and transaction inquiry APIs. These are optional fields and not required for the request. The startRowIndex query string parameter sets the first row of data of the response. The default value is 1. The endRowIndex query string parameter sets the final row of data of the response. The default value is 1000 records and is also the maximum number of records allowed in a single transaction. If the startRowIndex or endRowIndex parameters are blank, all the rows of data return up to the maximum limit of the endRowIndex value for transaction records. In the response header of the API, an endpoint may return totalRows or retrievedRows. These parameters provide a summary of the total number of transactions that match the request criteria or were retrieved based on the request criteria. Example Here is an example of a request with general pagination parameters applied in the query string for the Previous Day API: POST /ddaReports/accounts/v1/transactions/list?startRowIndex=1&endRowIndex=20 In this example, the startRowIndex is 5 so the first row of data is the fifth row, skipping the first four rows of data. The endRowIndex is 20 so that there is only 20 records per page following the fifth row. Offset pagination The offset pagination parameters are limit and offset. These parameters tell the server how many records to search for at a time and what records to skip. This parameter is not reliant on the sort controls and is not a recommended parameter for very large sets of data. Offset pagination is available with the RTP Send Payment API and is required for the RTP list of participants endpoint. The limit is a query string parameter field that tells the server what items to return during a search. The limit restricts how many rows are returned. There is no maximum limit to this parameter. The offset is a query string parameter field that specifies which set of rows to return. You can use this field to set the starting row for the data that is returned, and control what rows of data to skip. The default value is zero (0). Be cautious when you use these parameters because if the data set changes it can affect the result and may return an incorrect response. Example Here is an example of a request with the offset pagination parameters applied in the query string for the RTP Send Payment API: GET /rtp/v1/payment/rtp/participant?limit=15&offset=0 In this example, the offset is 0 so that no items are skipped, and the limit is 15 meaning the request will search 15 items at a time. Responses KeyBank uses the standard HTTP message responses. Each API response contains a status code and information about whether the request was successful or not. Status code numbers within the 200s indicate successful responses, while 4XX and 5XX error codes indicate an unfavorable or failure response. Our API documentation contains specific error details by API. HTTP STATUS CODES Code Status Description 200 OK; Successful The action was successful. No additional actions are needed. 400 Missing mandatory information Request is missing required information. 401 Unauthorized request Invalid credentials for the request. 403 Forbidden request access You do not have permission to complete the request. 404 Resource not found The resource for the request cannot be found. 405 Invalid request method The wrong request method was used. 415 Invalid request type The wrong media type submitted with the request. 429 Request timeout There are too many requests to the API and a timeout goes into effect. 500 Unknown error There was an unknown error with the server. 502 Bad gateway The servers cannot talk to each other or there is a miscommunication. 503 Unavailable service The service is temporarily down. 504 Unable to process request Request needs more time to be processed. Error handling An error can indicate a problem with the request, the network, or the API itself. Use the error handling information to get a better understanding of what went wrong and possible corrective actions. Standard error message format An erroneous response returns the HTTP code number with the content of the exception schema. Exception schema The following code snippet is the generic exception schema that is returned in the case of an error: { "ErrorMessage": string, "X-CorrelationId": string, "TransactionId": string, "TransactionTime": string, "ServiceError": object } The ServiceError field can contain a few different options, depending on the API: connectError - error information of the connectivity with downstream service. detailMessage - an error code with a detailed message. serviceErrorData - API-specific error details about the failed transaction. Custom API-specific error object. Additional information in the schema like TransactionId and TransactionTime can help you diagnose the issue. The schema also includes the X-CorrelationId field to help with traceability. API-specific error messages Custom messages are used for API-related functional business messages or faults. Each API can contain custom messages specific to KeyBank operations or the API. These messages can be part of the exception schema or a separate object. Status messages Some APIs contain status messages in the responseHeader object of the response payload. The status field returns the status code S, W, or F. Successful responses return the status code S with an HTTP 200 status code. Responses that were not processed as expected or failed to be processed at all return the status code W for warning or F for failure. Warning messages are associated with HTTP 299 status code. A warning message means the request was successfully received, but there was a minor issue that requires your attention. Failure messages are associated with the HTTP 400 or 500 status codes. Additional information is shared in the statusDescription field. These specific status messages are explained in depth on the API doc pages where applicable.