Use the Check Image Retrieval API to retrieve images of every check deposited and cleared. A successful request returns details of the requested check image (if attachImages
is set to TRUE).
Prerequisites and best practices
KeyBank has some common prerequisites and best practices. All KeyBank APIs require certifications, user credentials, and certain permissions. Make sure to satisfy all prerequisites before building your API.
Follow these steps to prepare for operations:
-
Have valid certificates for a secure connection.
-
Make sure you have the API keys needed for basic authentication and API access.
-
Request a bearer token before you start.
-
Check the health of the API.
-
Have your username and password ready, provided by KeyBank.
Certificates
Certificates are a digital authentication method we use to encrypt the information exchanged between KeyBank and your app or service. To access KeyBank environments, you must exchange valid certificates with KeyBank. These certificates must be properly installed on your system before you start to send API calls.
API keys
You need API keys to get a bearer token and to grant access to the APIs and the Pre-Production or Production environments. These API keys are created only for authenticated users that have partnered with KeyBank. For more information, see API security or sign up to become a KeyBank API consumer
Bearer token
Get a bearer token before you start. Only authenticated users with client credentials can request a bearer token. For more information, see API security or sign up to become a KeyBank API consumer
Health check
Before you start building your API, perform a quick health check. A health check verifies that the API is operational and responding correctly with your system. A bearer token is required to perform a health check. For more information, see Health check.
Username and password
Your assigned username and password for the API is required in the defaultCheckRequest
object of the request body. These credentials are provided by KeyBank after the onboarding process is complete. This information is shared with you via secure email.
Endpoints
Endpoint | Result | Description |
---|---|---|
post /cmi/v1/checkList | Retrieve a check image | Get a single check image associated to the requested check and account information. |
Retrieve a check image
post /cmi/v1/checkList
Get a single check image associated to the requested check and account information.
Request
HEADER FIELD | TYPE | DESCRIPTION |
---|---|---|
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
Content-Typerequired | string | Defines the content type of the API. Common content types are application/json or application/x-www-form-urlencoded. |
BODY FIELD | TYPE | DESCRIPTION |
---|---|---|
attachImagesrequired | boolean | Indicates if check image needs to be attached to the response. If set to true , images are rendered in response. |
defaultChecksRequestrequired | Object | defaultChecksRequest |
featuresoptional | Object | features |
limitrequired | integer | Use default value as 1 . |
startoptional | integer | Start index of the check range to be retrieved |
Request example

{ "attachImages": true, "defaultChecksRequest": { "applicationGroupId": "CPCCHECKS", "applicationId": "CPC-CHECKS", "criterias": [ { "documentIndex": "Account Number", "highValue": "", "lowValue": "1234567890", "operator": "eq" }, { "documentIndex": "Check Number", "highValue": "", "lowValue": "14704523", "operator": "eq" }, { "documentIndex": "Amount", "highValue": "", "lowValue": "85.95", "operator": "eq" }, { "documentIndex": "Check Process Date", "highValue": "", "lowValue": "09\/22\/2021", "operator": "eq" } ], "password": "testuser", "userName": "abc$123#scsf" }, "features": { "compresstoZip": true, "outputFormat": "TIF", "scale": "" }, "limit": 1, "start": 0 }
Responses
Successful response
NAME | TYPE | DESCRIPTION |
---|---|---|
getChecksListResponserequired | array | getChecksListResponse |
messagerequired | string | Indicates the response status description |
totalNoOfChecksrequired | string | Indicates the total number of checks retrieved |
Response example (200)

{ "getChecksListResponse": { "accountNumber": "1234567890", "amount": "85.95", "checkProcessDate": "09\/22\/2021", "checkNumber": "14704523 ", "sequenceNumber": "38581847", "transactionType": "DEBIT", "checkRoutingNumber": "04120704", "checkFrontImage": "lUwXMGBwTm4dy\/5pe8GwlRZULmMfPkzL8yZKfDxRTU7HFMW\/b7DYqjBq0vyC85PxMObQ2UxtcbVe78MWsdgIBkKY7pCB4eE7GQr9QOcFRW2O7FQshj8ExEy0bmCV8cQFyxzKh04XPWIDxp71PIw\/BFWy2GG+R3b1SFP\/Mbj0Hdppoxn+rUxAz7Red+39BodSSz1xZteU8hu6fYvvNmbqasZmkVAEE6hS2H+3uVKqaMmnpHJ2oIie0rtowueFradOWhNGvV5pRuEhEd6j93X\/7mt=", "checkRearImage": "73mfoZbjXF4Gr9XuIYSieWR0o3NV2bvMcwiurzvU8Dyvy2CG+1DYdw3IyHHZRdY6CKiarVFK7mG+IgJKVaDwqA2Ma7YxopwgEIJ5oc8gS\/O8BzX7zms\/6hmRn9wrcZj3ZhaSUmAdOtSc3qOzp6JPLoYyJg2hQwnEtJyormF8GT5ajF8ADV6XQD+d3Ym8bKsR6rHWwGB0bmiKu+9r+33mR8QZmzmmCPIUZXzj6CXaLr0dNA4+xXszgMbWAHI00ZGhTsSfzyWp8FHYZx24fbEOkS9ApuVBRihL+Eb14ldJayOgAXI3OjLJgo2pB4EUvbQmhwu=" }, "message": "Successfully retrieved", "totalNoOfChecks": 1 }
Missing data in the request
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Indicates the status description of the processed request. |
TransactionIdoptional | string | Indicates the unique ID that gets assigned for processed request. |
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
TransactionTimeoptional | string | Time of the occurrence of the error of the message. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (400)

{ "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": "Error Message from Backend Servers" }
Received request is unauthorized
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Indicates the status description of the processed request. |
TransactionIdoptional | string | Indicates the unique ID that gets assigned for processed request. |
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
TransactionTimeoptional | string | Time of the occurrence of the error of the message. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (401)

{ "ErrorMessage": "Received request is unauthorized, please provide valid credentials", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": "Error Message from Backend Servers for unauthorized access" }
Request is forbidden to access the resource
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Indicates the status description of the processed request. |
TransactionIdoptional | string | Indicates the unique ID that gets assigned for processed request. |
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
TransactionTimeoptional | string | Time of the occurrence of the error of the message. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (403)

{ "ErrorMessage": "Access to requested resource is forbidden", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested resource is not found
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Indicates the status description of the processed request. |
TransactionIdoptional | string | Indicates the unique ID that gets assigned for processed request. |
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
TransactionTimeoptional | string | Time of the occurrence of the error of the message. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (404)

{ "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested method is not allowed.
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Indicates the status description of the processed request. |
TransactionIdoptional | string | Indicates the unique ID that gets assigned for processed request. |
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
TransactionTimeoptional | string | Time of the occurrence of the error of the message. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (405)

{ "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested unsupported media type
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Indicates the status description of the processed request. |
TransactionIdoptional | string | Indicates the unique ID that gets assigned for processed request. |
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
TransactionTimeoptional | string | Time of the occurrence of the error of the message. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (415)

{ "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Too many requests received
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Indicates the status description of the processed request. |
TransactionIdoptional | string | Indicates the unique ID that gets assigned for processed request. |
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
TransactionTimeoptional | string | Time of the occurrence of the error of the message. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (429)

{ "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Internal server error
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Indicates the status description of the processed request. |
TransactionIdoptional | string | Indicates the unique ID that gets assigned for processed request. |
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
TransactionTimeoptional | string | Time of the occurrence of the error of the message. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (500)

{ "ErrorMessage": "Unknown error occurred, please resubmit the request", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": "Error Message from Backend Servers for internal server error" }
Bad Gateway
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Indicates the status description of the processed request. |
TransactionIdoptional | string | Indicates the unique ID that gets assigned for processed request. |
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
TransactionTimeoptional | string | Time of the occurrence of the error of the message. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (502)

{ "ErrorMessage": "Bad Gateway, please resubmit the request", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "connectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request" } }
Service Unavailable
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Indicates the status description of the processed request. |
TransactionIdoptional | string | Indicates the unique ID that gets assigned for processed request. |
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
TransactionTimeoptional | string | Time of the occurrence of the error of the message. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (503)

{ "ErrorMessage": "Service is currently unavailable, please resubmit the request", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "connectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request." } }
Gateway timeout
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Indicates the status description of the processed request. |
TransactionIdoptional | string | Indicates the unique ID that gets assigned for processed request. |
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
TransactionTimeoptional | string | Time of the occurrence of the error of the message. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (504)

{ "ErrorMessage": "Request could not be processed on time(Gateway timeout), please resubmit the request", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "connectError": "Request could not be processed on time (GatewayTimeout), please wait a moment and resubmit the request." } }
Schemas
criteria
NAME | TYPE | DESCRIPTION |
---|---|---|
documentIndexrequired | string | Requird parameters to retrieve a check image. Values are Account Number, Check Number, Check Amount and Check Process Date. All 4 values are required to retrieve a check image. |
highValueoptional | string | Indicates the high range of the criteria. Reserved for future use, should be left blank. |
lowValuerequired | string | Indicates the starting range of the criteria. |
operatorrequired | string | Indicates the operation type. Should be defaulted to "eq". |
defaultChecksRequest
NAME | TYPE | DESCRIPTION |
---|---|---|
applicationGroupIdrequired | string | Indicates the application groupID for check images. Should be defaulted to "CPCCHECKS" always. |
applicationIdrequired | string | Indicates the applicationID for check images. Should be defaulted to "CPC-CHECKS" always. |
criteriasrequired | array | criteria |
passwordrequired | string | User name provided during client onboarding. |
userNamerequired | string | Encrypted Password provided during client onboarding. |
exception
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Indicates the status description of the processed request. |
TransactionIdoptional | string | Indicates the unique ID that gets assigned for processed request. |
X-CorrelationIdoptional | string | Universal id to trace the transaction across all the systems involved. |
TransactionTimeoptional | string | Time of the occurrence of the error of the message. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
connectError
NAME | TYPE | DESCRIPTION |
---|---|---|
connectErroroptional | string | Error information of the connectivity with downstream service. |
features
NAME | TYPE | DESCRIPTION |
---|---|---|
outputForamtrequired | string | Indicates the output format of the check images. Valid value - TIF |
compresstoZipoptional | boolean | Reserved for future use. Please leave this field blank. |
scaleoptional | string | Reserved for future use. Please leave this field blank. |
getCheckListRequest
NAME | TYPE | DESCRIPTION |
---|---|---|
attachImagesrequired | boolean | Indicates if check image needs to be attached to the response. If set to true , images are rendered in response. |
defaultChecksRequestrequired | Object | defaultChecksRequest |
featuresoptional | Object | features |
limitrequired | integer | Use default value as 1 . |
startoptional | integer | Start index of the check range to be retrieved |
getCheckListBean
NAME | TYPE | DESCRIPTION |
---|---|---|
getChecksListResponserequired | array | getChecksListResponse |
messagerequired | string | Indicates the response status description |
totalNoOfChecksrequired | string | Indicates the total number of checks retrieved |
getChecksListResponse
NAME | TYPE | DESCRIPTION |
---|---|---|
accountNumberoptional | string | Account number of the check image |
amountoptional | string | Amount of the check |
checkProcessDateoptional | string | Check process date |
checkNumberoptional | string | Check number |
checkFrontImageoptional | string | Front image of the check |
checkRearImageoptional | string | Back image of the check |
sequenceNumberoptional | string | Sequence number of the check |
checkRoutingNumberoptional | string | Check routing number |
transactionTypeoptional | string | Transaction type of the check |
serviceErrorData
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorDetailsoptional | string | Additional error details about the failed transaction. |
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. Additional information in this schema like the transaction ID and transaction time can help you diagnose the issue.
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.
KeyBank uses the serviceErrorData
object for errors specific to the API. Review the ErrorDetails
to view the custom message.
Error codes and messages
Standard errors use the typical HTTP status codes. Messages specific to KeyBank have an asterisk (*) after the message code number. The serviceErrorData
object has additional information specific to the API.
HTTP STATUS CODE | CUSTOM STATUS CODE | DESCRIPTION |
---|---|---|
200* | S | Specified checks not found.
There is invalid data in the request payload. Make sure mandatory fields are complete and field entries are in the correct format. |
200* | S | checkFrontImage and checkRearImage are blank.
The Boolean value for the attachImages field is set to False in the request and you will not receive check images. |
200* | F | Error received from backend service.
You are missing mandatory information in your request. Enter the starting check date in MMDDYYYY format in the criterias object > lowValue field. |
200* | F | Error received from backend service.
You are missing some mandatory information in the defaultsCheckRequest object. Make sure you have the correct information in the applicationGroupId field. |
200* | F | Error received from backend service.
You are missing mandatory information or have an invalid value in the criterias object. Review the request to make sure that all requirements are met before retrying the call. |
200* | F | Unknown error occured(Expected STRING or NUMBER or OBJECT or ARRAY at line 2), please check and resubmit the request
Make sure that the Boolean value for the attachImages field is set to True to receive check images. |
400 | Missing data in the request.
|
|
401 | Received request is unauthorized.
|
|
403 | Request is forbidden to access the resource.
|
|
404 | Request resource is not found.
|
|
405 | Request method is not allowed.
|
|
415 | Requested unsupported media type.
|
|
429 | Too many request received.
|
|
500 | Internal server error.
|
|
502 | Bad Gateway.
|
|
503 | Service Unavailable.
|
|
504 | Gateway timeout.
|
YAML file
