Check Image Retrieval | API Documentation

See and verify checks paid

Use the Check Image Retrieval API to retrieve images of every check deposited and cleared.

Check Image Retrieval Endpoints

What you can do	Endpoint
Health check	get /cmi/v1/healthCheck
Retrieve a check image	post /cmi/v1/checkList

Before you begin

All KeyBank APIs require certificates, user credentials, and certain permissions. Check out our Getting Started Guide to learn more.

Overview

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

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

Health check

get /cmi/v1/healthCheck

Verify you can connect to the API service. A bearer token is required.

Responses

Successful response

NAME	TYPE	DESCRIPTION
Statusoptional	string	Status of the health check response.
Sourceoptional	string	Origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
Timestampoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpoptional	string	Client IP address the gateway receives from the request.
X-Forwarded-Foroptional	string	Sequence of IP addresses for systems between the client and the gateway.

Response example (200)

{
  "Status": "Ok",
  "Source": "Roundtrip",
  "Timestamp": "2022-09-15T04:49:03",
  "ClientIp": "156.77.111.28",
  "X-Forwarded-For": "[156.77.111.28]"
}

Retrieve a check image

post /cmi/v1/checkList

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

Request

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": {
        "outputFormat": "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 mandatory information

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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource 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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request 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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown 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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "ServiceError": {
        "connectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with appplication support team before resubmitting the request"
    }
}

Unavailable service

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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "connectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process 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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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	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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

connectError

NAME	TYPE	DESCRIPTION
connectErroroptional	string	API connectivity error information, if available.

features

NAME	TYPE	DESCRIPTION
outputFormatrequired	string	Indicates the output format of the check images. Valid values: TIF, TIFG4
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 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

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.

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	The Base64 encoded string for the front image of the check.
checkRearImageoptional	string	The Base64 encoded string for the back image of the check.

serviceErrorData

NAME	TYPE	DESCRIPTION
ErrorDetailsoptional	string	Additional error details about the failed transaction.

Errors

For more information about general errors, see Error handling.

The message field in the getCheckListResponse tells you if the check was "Successfully retrieved" or "Failed". It is possible to receive a HTTP 200 response and have a failure message to resolve. This means that your transaction was successfully received but there was an issue with the request data. Look at the API-specific KeyBank error codes and details are in the serviceErrorData object of the exception schema.

HTTP STATUS CODE	Message status	DESCRIPTION
200	`Successfully retrieved`	`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	`Successfully retrieved`	`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	`Failed`	`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	`Failed`	`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	`Failed`	`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	`Failed`	`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.

Changelog

Release	API version	Change description	Impact
November 2024	1.2.5	Modified the front and back image description to clarify that it is a Base64 encoded string and not an actual image file.	LOW
May 2024	1.2.4	Parameter description updates. This change is for technical content only. The code and operations of the API remain the same. Updated the `getChecksListResponse` object with improved error messaging. `X-CorrelationId` has been removed as a request header field for all endpoints. The parameter is no longer in the request body, but still remains in the code. The system assigns a unique ID when you submit a request and returns the value in the response.	MID
December 2022	1.1.7	Released on the Developer Portal.

Impact levels

LOW: This is a minor change or enhancement that does not alter the operations of the API. Upgrading to the latest specifications is preferable but not required.
MID: The previous API version is valid and operates, but does not contain latest enhancements. You need to update your specifications to get these enhancements.
HIGH: The previous API version is no longer operable. You must upgrade to the latest specifications to access and use this API product.

YAML file