Check Image Retrieval
2-minute read
1.2.5 | updated Nov. 19, 2024
Use the Check Image Retrieval API to retrieve images of every check deposited and cleared.
Check Image Retrieval Endpoints
Copied to Clipboard
Before you begin
All KeyBank APIs require certificates, user credentials, and certain permissions. Check out our Getting Started Guide to learn more.
Overview
Copied to Clipboard
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
Copied to Clipboard
get /cmi/v1/healthCheck
Verify you can connect to the API service. A bearer token is required.
Responses
Copied to ClipboardSuccessful response
Copied to ClipboardNAME | 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. |
Copy code
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
Copied to Clipboard
post /cmi/v1/checkList
Get a single check image associated with the requested check and account information.
Request
Copied to ClipboardBODY 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 |
Copy code
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
Copied to ClipboardSuccessful response
Copied to ClipboardNAME | 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. |
Copy code
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
Copied to ClipboardNAME | 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 |
Copy code
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
Copied to ClipboardNAME | 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 |
Copy code
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
Copied to ClipboardNAME | 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 |
Copy code
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
Copied to ClipboardNAME | 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 |
Copy code
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
Copied to ClipboardNAME | 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 |
Copy code
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
Copied to ClipboardNAME | 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 |
Copy code
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
Copied to ClipboardNAME | 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 |
Copy code
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
Copied to ClipboardNAME | 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 |
Copy code
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
Copied to ClipboardNAME | 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 |
Copy code
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
Copied to ClipboardNAME | 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 |
Copy code
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
Copied to ClipboardNAME | 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 |
Copy code
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
Copied to Clipboard
criteria
Copied to Clipboard
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
Copied to Clipboard
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
Copied to Clipboard
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
Copied to Clipboard
NAME | TYPE | DESCRIPTION |
---|
connectErroroptional | string | API connectivity error information, if available. |
features
Copied to Clipboard
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
Copied to Clipboard
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
Copied to Clipboard
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
Copied to Clipboard
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
Copied to Clipboard
NAME | TYPE | DESCRIPTION |
---|
ErrorDetailsoptional | string | Additional error details about the failed transaction. |
Errors
Copied to Clipboard
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.
Changelog
Copied to Clipboard
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