Start building with KeyBank APIs
Verification APIs
Verify an account and its owner with confidence.
Account Validation provides confirmation that account data matches to an account owner.
ACH APIs
Transfer money from bank to bank.
ACH Origination creates a payment and submits it to a clearing house.
ACH Inquiry shows the status of a payment as collected, returned, or posted.
Wires APIs
Send payments and track status.
Wire Inquiry tracks the progress of a wire payment and reports its status.
Real-time payment APIs
Send money quickly with more data.
RTP Send Payment speeds up the payment process for faster, more efficient transactions.
Information reporting APIs
Review account activity.
Previous Day presents posted transactions like deposit activity, paid checks, incoming ACH debits and credits, incoming wires, and ACH and wire transactions together in one report.
Intraday presents memo transactions like deposit activity, CDA funding requirements, incoming CDA checks, incoming ACH debits and credits, incoming wires, and ACH and wire transactions together in one report.
Checking APIs
Track activity, stop payments, and view checks.
Check Image Retrieval collects images of every check deposited and cleared to create a searchable catalog of past transactions.
Stop Payment stops checks quickly before it is cashed.
API security
At KeyBank, we take security seriously. To keep the APIs and the returned data protected, we use authentication and authorization methods to stop any potential threats.
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 non-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.
We will share more information as our portal develops.
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 Originate |
GET /ach/payments/v1/healthCheck |
ACH Inquiry |
GET /accounts/transactions/v1/healthCheck |
Wire Inquiry |
GET /wireInquiry/v1/healthCheck |
RTP Send Payment |
GET /rtp/v1/payment/healthCheck |
Previous Day Information Reporting |
GET /ddaReports/accounts/v1/healthCheck |
Intraday Information Reporting |
GET /ddaReports/accounts/v1/healthCheck |
Check Image Retrieval |
GET /cmi/v1/healthCheck |
Stop Payment |
GET /accounts/payments/v1/healthCheck |
Request recommendations and requirements
Some field objects for the request may be required, most are optional, and some are strongly encouraged.
Recommendations
Consider these recommendations 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.
Content-Type
The Content-Type header communicates how you want the information returned. Use one of two options: application/x-www-form-url-encoded/ or application/json. To request a bearer token, use application/x-www-form-url-encoded. For API calls, use application/json.
X-CorrelationID
The X-CorrelationID field 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 non-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.
API REQUIREMENTS PROVIDED BY KEYBANK
API | REQUIRED FIELDS |
---|---|
Account Validation | secondaryId
The |
ACH Origination | point , collectionApplicationId , collectionApplicationType
The point is the client and the collectionApplicationId and collectionApplicationType are for the client account. These values are not environment-specific and can be used in both environments. |
ACH Inquiry Wires Inquiry Previous Day Intraday |
mdmId
Use the MDM ID provided for API payload and objects. KeyBank assigns a Master Data Management (MDM) ID to each client. The MDM ID is used for account entitlement. With your API keys, you may also get an MDM ID. This ID needs to be part of the API request to authorize the account’s data retrieval. The MDM ID can associate an ID with a single account or many accounts for verification and data retrieval. |
Check Image Retrieval | userName , password
Username and password (NHID) shared via secure email. Use these credentials in the API payload, DefaultChecksRequest object. |
Stop Payment | PaymentRequest
Enter the bank account number in the PaymentRequest object. |
RTP Send Payment | KeyClientId
The KeyBank client ID is a 32-character string that identifies you as the client. The KeyClientId value is provided by KeyBank during the onboarding process. |
HTTP standard 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 400s and 500s 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. |
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.
We can help
KeyBank has a team of developers to help you. Look at the top info section of the YAML file to find the contact information for KeyBank API development support.