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
|
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
|
Wire Inquiry | POST /wireInquiry/v1/transactions/details | Optional |
startRowIndex
|
Previous Day | POST /ddaReports/accounts/v1/transactions/list | Optional |
startRowIndex
|
Intraday | POST /ddaReports/accounts/v1/transactions/intraday/list | Optional |
limit
|
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
orendRowIndex
parameters are blank, all the rows of data return up to the maximum limit of theendRowIndex
value for transaction records. - In the response header of the API, an endpoint may return
totalRows
orretrievedRows
. 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.