Check Image Retrieval

clock 2-minute read calender 1.2.3 | updated Apr. 24, 2024

See and verify checks paid

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.

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.


get /cmi/v1/healthCheck

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

header FIELD TYPE DESCRIPTION
X-CorrelationIdoptional string A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
 
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)

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

post /cmi/v1/checkList

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

header FIELD TYPE DESCRIPTION
X-CorrelationIdoptional string A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
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

copylink
{
    "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
}
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)

copylink
{
    "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 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)

copylink
{
    "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"
}
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)

copylink
{
    "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"
}
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)

copylink
{
    "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"
}
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)

copylink
{
    "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"
}
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)

copylink
{
    "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"
}
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)

copylink
{
    "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"
}
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)

copylink
{
    "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"
}
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)

copylink
{
    "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"
}
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)

copylink
{
    "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"
    }
}
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)

copylink
{
    "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."
    }
}
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)

copylink
{
    "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."
    }
}
NAMETYPEDESCRIPTION
connectErroroptionalstringAPI connectivity error information, if available.
NAMETYPEDESCRIPTION
documentIndexrequiredstringRequired 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
highValueoptionalstringIndicates the high range of the criteria. Reserved for future use, should be left blank.
lowValuerequiredstringIndicates the starting range of the criteria.
operatorrequiredstringIndicates the operation type. Must be set to "eq".
NAMETYPEDESCRIPTION
applicationGroupIdrequiredstringIndicates the application group ID for check images. Must be set to "CPCCHECKS".
applicationIdrequiredstringIndicates the application ID for check images. Must be set to "CPC-CHECKS".
criteriasrequiredarraycriteria
userNamerequiredstringUsername provided by KeyBank during client onboarding.
passwordrequiredstringEncrypted password provided by KeyBank during client onboarding.
NAMETYPEDESCRIPTION
ErrorMessageoptionalstringA human-readable message that describes the type or source of the error.
TransactionIdoptionalstringA unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptionalstringA unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptionalstringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptionaloneOfserviceErrorData connectError
NAMETYPEDESCRIPTION
outputForamtrequiredstringIndicates the output format of the check images. Valid values: BMP, JPEG, PDF, PNG, TIF, TIFG4
compresstoZipoptionalbooleanReserved for future use. Please leave this field blank.
scaleoptionalstringReserved for future use. Please leave this field blank.
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.
NAMETYPEDESCRIPTION
attachImagesrequiredbooleanIndicates if the check image needs to be attached to the response. If set to true, images are rendered in response.
defaultChecksRequestrequiredObjectdefaultChecksRequest
featuresoptionalObjectfeatures
limitrequiredintegerThe number of checks returned. Because this endpoint returns a single check image, limit must be set to 1.
startoptionalintegerStart index of the check range to be retrieved
NAMETYPEDESCRIPTION
accountNumberoptionalstringAccount number of the check image
amountoptionalstringAmount of the check
checkProcessDateoptionalstringCheck processed date (MM-DD-YYYY)
checkNumberoptionalstringCheck number
sequenceNumberoptionalstringSequence number of the check
transactionTypeoptionalstringTransaction type of the check
checkRoutingNumberoptionalstringRouting number of the check
checkFrontImageoptionalstringFront image of the check
checkRearImageoptionalstringBack image of the check
NAMETYPEDESCRIPTION
StatusoptionalstringStatus of the health check response.
SourceoptionalstringOrigin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
TimestampoptionalstringDate (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpoptionalstringClient IP address the gateway receives from the request.
X-Forwarded-ForoptionalstringSequence of IP addresses for systems between the client and the gateway.
NAME TYPE DESCRIPTION
ErrorDetailsoptional string Additional error details about the failed transaction.

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.

 


YAML file download