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 secondaryId is a ten-digit string that identifies you as the client. This value is provided by KeyBank during the onboarding process. 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 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. 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.