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).
Before you begin
All KeyBank APIs require certificates, user credentials, and certain permissions. Before you begin, see Key concepts to learn more about these fundamental elements as well as other recommended best practices.
API-specific requirements
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.
Check Image Retrieval Endpoints
Summary | Endpoint |
---|---|
Retrieve a check image | post /cmi/v1/checkList |
Retrieve a check image
post /cmi/v1/checkList
Get a single check image associated with the requested check and account information.
Request
header FIELD | TYPE | DESCRIPTION |
---|---|---|
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
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 the 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 | The number of checks returned. Because this endpoint returns a single check image, limit must be set to 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": { "outputForamt": "TIF", "compresstoZip": true, "scale": "" }, "limit": 1, "start": 0 }
Responses
Successful response
NAME | TYPE | DESCRIPTION |
---|---|---|
getChecksListResponserequired | array | getChecksListResponse |
messagerequired | string | A human-readable message that describes the response status. |
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
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | A human-readable message that describes the type or source of the error. |
TransactionIdoptional | string | A unique transaction ID returned with the response, useful for traceability. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (400)

{ "ErrorMessage": "Please make sure your request is correct and try again.", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ErrorDetails": "Error message details from backend servers." } }
Unauthorized request
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | A human-readable message that describes the type or source of the error. |
TransactionIdoptional | string | A unique transaction ID returned with the response, useful for traceability. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (401)

{ "ErrorMessage": "Please make sure you're using the correct credentials. Then log in again.", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ErrorDetails": "Error message details from backend servers for unauthorized access." } }
Access denied
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | A human-readable message that describes the type or source of the error. |
TransactionIdoptional | string | A unique transaction ID returned with the response, useful for traceability. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (403)

{ "ErrorMessage": "You don't have access to this resource. Contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Not found
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | A human-readable message that describes the type or source of the error. |
TransactionIdoptional | string | A unique transaction ID returned with the response, useful for traceability. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (404)

{ "ErrorMessage": "We can't seem to find what you're looking for. Please verify the resource and try again.", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Request method denied
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | A human-readable message that describes the type or source of the error. |
TransactionIdoptional | string | A unique transaction ID returned with the response, useful for traceability. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (405)

{ "ErrorMessage": "Looks like something went wrong. Please check your request method and try again.", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Media type not supported
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | A human-readable message that describes the type or source of the error. |
TransactionIdoptional | string | A unique transaction ID returned with the response, useful for traceability. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (415)

{ "ErrorMessage": "We currently don't support that format. Please check the format type defined in your request and try again. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.", "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
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | A human-readable message that describes the type or source of the error. |
TransactionIdoptional | string | A unique transaction ID returned with the response, useful for traceability. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (429)

{ "ErrorMessage": "Looks like you've sent too many requests. Please wait a moment and try again later.", "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 | A human-readable message that describes the type or source of the error. |
TransactionIdoptional | string | A unique transaction ID returned with the response, useful for traceability. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (500)

{ "ErrorMessage": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ErrorDetails": "Error Message from Backend Servers for internal server error" } }
Bad gateway
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | A human-readable message that describes the type or source of the error. |
TransactionIdoptional | string | A unique transaction ID returned with the response, useful for traceability. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (502)

{ "ErrorMessage": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "connectError": "A connectivity error occurred with the downstream service(unexpected end of file at the target). Please check with your KeyBank Client Success Manager or email developers@keybank.com before trying the request again." } }
Service unavailable
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | A human-readable message that describes the type or source of the error. |
TransactionIdoptional | string | A unique transaction ID returned with the response, useful for traceability. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (503)

{ "ErrorMessage": "Looks like something went wrong. Please try again later. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "connectError": "This service is currently unavailable (there are no active targets). Please check with your KeyBank Client Success Manager or email developers@keybank.com before trying the request again." } }
Gateway timeout
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | A human-readable message that describes the type or source of the error. |
TransactionIdoptional | string | A unique transaction ID returned with the response, useful for traceability. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (504)

{ "ErrorMessage": "Your request took too long to process. Please try again. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "connectError": "The request could not be processed on time (gateway timeout). Please wait a moment and try again later." } }
Schemas
connectError
NAME | TYPE | DESCRIPTION |
---|---|---|
connectErroroptional | string | API connectivity error information, if available. |
criteria
NAME | TYPE | DESCRIPTION |
---|---|---|
documentIndexrequired | string | Required parameters to retrieve a check image. A total of four criteria objects should be included in the request - one for each of the four values required to retrieve a check image. Valid values: Account Number, Check Number, Check Amount, Check Process Date |
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. Must be set to "eq". |
defaultChecksRequest
NAME | TYPE | DESCRIPTION |
---|---|---|
applicationGroupIdrequired | string | Indicates the application group ID for check images. Must be set to "CPCCHECKS". |
applicationIdrequired | string | Indicates the application ID for check images. Must be set to "CPC-CHECKS". |
criteriasrequired | array | criteria |
userNamerequired | string | Username provided by KeyBank during client onboarding. |
passwordrequired | string | Encrypted password provided by KeyBank during client onboarding. |
exception
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | A human-readable message that describes the type or source of the error. |
TransactionIdoptional | string | A unique transaction ID returned with the response, useful for traceability. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
features
NAME | TYPE | DESCRIPTION |
---|---|---|
outputForamtrequired | string | Indicates the output format of the check images. Valid values: BMP, JPEG, PDF, PNG, TIF, TIFG4 |
compresstoZipoptional | boolean | Reserved for future use. Please leave this field blank. |
scaleoptional | string | Reserved for future use. Please leave this field blank. |
getCheckListBean
NAME | TYPE | DESCRIPTION |
---|---|---|
getChecksListResponserequired | array | getChecksListResponse |
messagerequired | string | A human-readable message that describes the response status. |
totalNoOfChecksrequired | string | Indicates the total number of checks retrieved. |
getCheckListRequest
NAME | TYPE | DESCRIPTION |
---|---|---|
attachImagesrequired | boolean | Indicates if the 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 | The number of checks returned. Because this endpoint returns a single check image, limit must be set to 1. |
startoptional | integer | Start index of the check range to be retrieved |
getChecksListResponse
NAME | TYPE | DESCRIPTION |
---|---|---|
accountNumberoptional | string | Account number of the check image |
amountoptional | string | Amount of the check |
checkProcessDateoptional | string | Check processed date (MM-DD-YYYY) |
checkNumberoptional | string | Check number |
sequenceNumberoptional | string | Sequence number of the check |
transactionTypeoptional | string | Transaction type of the check |
checkRoutingNumberoptional | string | Routing number of the check |
checkFrontImageoptional | string | Front image of the check |
checkRearImageoptional | string | Back image of the check |
serviceErrorData
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorDetailsoptional | string | Additional error details about the failed transaction. |
Errors
For more information about errors, see Error handling.
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. |
YAML file
