Check Image Retrieval | API Documentation

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

YAML file