Check Image Retrieval

11 minute read 1.2.0 | updated Feb. 13, 2023

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).

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:

  1. Have valid certificates for a secure connection.

  2. Make sure you have the API keys needed for basic authentication and API access.

  3. Request a bearer token before you start.

  4. Check the health of the API.

  5. Have your username and password ready, provided by KeyBank.

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.

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

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

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.

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.

Endpoint Result Description
post /cmi/v1/checkList Retrieve a check image Get a single check image associated to the requested check and account information.

post /cmi/v1/checkList

Get a single check image associated to the requested check and account information.

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
}
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
}
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"
}
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"
}
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"
}
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"
}
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"
}
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"
}
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"
}
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"
}
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"
    }
}
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."
    }
}
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."
    }
}
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".
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.
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
NAME TYPE DESCRIPTION
connectErroroptional string Error information of the connectivity with downstream service.
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.
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
NAME TYPE DESCRIPTION
getChecksListResponserequired array getChecksListResponse
messagerequired string Indicates the response status description
totalNoOfChecksrequired string Indicates the total number of checks retrieved
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
NAME TYPE DESCRIPTION
ErrorDetailsoptional string Additional error details about the failed transaction.

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.

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.

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.

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.

Missing or invalid field – Check Date

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.

This Application is not configured for CMI transaction.

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.

500 – Internal Server Error

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.

Mandatory data not provided, please verify the data and resubmit the request.
401   Received request is unauthorized.

Received request is unauthorized, please provide valid credentials.
403   Request is forbidden to access the resource.

Access to requested resource is forbidden.
404   Request resource is not found.

Requested resource is not found, please verify the resource and resubmit the request.
405   Request method is not allowed.

Requested method is not allow, please verify the method and resubmit the request.
415   Requested unsupported media type.

Requested media type is not allowed, please verify the media type and resubmit the request.
429   Too many request received.

Number requests threshold reached, please resubmit the request after sometime.
500   Internal server error.

Unknown error occurred, please resubmit the request.
502   Bad Gateway.

Bad Gateway, please resubmit the request
503   Service Unavailable.

Service is currently unavailable, please resubmit the request.
504   Gateway timeout.

Request could not be processed on time, please resubmit the request.
YAML file