Check Image Retrieval

See and verify checks paid

Check Image Retrieval Endpoints

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

Health check

get /cmi/v1/healthCheck

Request

Check the health of an API service and verify you can successfully connect. A bearer token is required.

Request example

curl "https://partner-api-qv.key.com/cmi/v1/healthCheck"
--header 'Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Successful response

NAME	TYPE	DESCRIPTION
Statusoptional	string	The status of the health check response.
Sourceoptional	string	The origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
Timestampoptional	string	The date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpoptional	string	The client IP address the gateway receives from the request.
X-Forwarded-Foroptional	string	The sequence of the 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"
            }
        ]
    },
    "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
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/cmi/v1/checkList"
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/cmi/v1/checkList"
}

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/cmi/v1/checkList"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/cmi/v1/checkList"
}

Invalid request method

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/cmi/v1/checkList"
}

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/cmi/v1/checkList"
}

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/cmi/v1/checkList"
}

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/cmi/v1/checkList"
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/cmi/v1/checkList",
    "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
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/cmi/v1/checkList",
    "ServiceError": {
        "connectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/cmi/v1/checkList",
    "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
userNameoptional	string	Username provided by KeyBank during client onboarding.
passwordoptional	string	Encrypted password provided by KeyBank during client onboarding.

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.

exception

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	serviceErrorData connectError

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

September 2025

API Version: 1.2.7 | Impact: LOW

Added Api-Url parameter to all instances of the exception schema. This parameter is now a standard part of all error messages to help you identify which call triggered an unsuccessful response.

April 2025

API Version: 1.2.6 | Impact: LOW

For the defaultChecksRequest object, the userName and password parameters are no longer required.

November 2024

API Version: 1.2.5 | Impact: LOW

Modified the front and back image description to clarify that it is a Base64 encoded string and not an actual image file.

May 2024

API Version: 1.2.4 | Impact: MID

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.

December 2022

API Version: 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

Check Image Retrieval Endpoints

Health check

Request

Request example

Successful response

Response example (200)

Retrieve a check image

Request

Request example

Responses

Successful response

Response example (200)

Missing mandatory information

Response example (400)

Unauthorized request

Response example (401)

Forbidden request access

Response example (403)

Resource not found

Response example (404)

Invalid request method

Response example (405)

Invalid request type

Response example (415)

Request timeout

Response example (429)

Unknown error

Response example (500)

Bad gateway

Response example (502)

Unavailable service

Response example (503)

Unable to process request

Response example (504)

Schemas

criteria

defaultChecksRequest

connectError

features

getCheckListRequest

getCheckListBean

getChecksListResponse

serviceErrorData

exception

Errors

Changelog

September 2025

April 2025

November 2024

May 2024

December 2022

Impact levels

We value your feedback