Account Validation

25-minute read 1.0.1 | updated Sep. 26, 2023

Use the Account Validation API to verify an account and its owner with confidence. This API evaluates account owner data through an inquiry request and response process.

API consumers submit a request to the Account Validation API. The data in that request is compared to information in the National Shared Database Resource. Results from the database comparison are evaluated and then returned to the API consumer in real time in a response payload.

Account Validation responses include specific service-level processing information and account-level information as shown below:

Service-level

  • System error codes
  • Inquiry field validation error codes

Account-level

  • Condition codes
  • Account status codes
  • Account owner field matching

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.

Secondary and additional IDs

KeyBank assigns a unique secondary ID (secondaryId) that is required for all account validation requests. If required, a unique additional ID (additionalId) is also assigned. Both IDs are shared via secure email.

Summary Endpoint
Verify an account post /accounts/validations/v1/verifyAccount

post /accounts/validations/v1/verifyAccount

Verify that an account owner's name, address, and other identifying elements match the account information in the National Shared Database Resource and that they are authorized to transact on the account. The National Shared Database Resource is the financial industry's leading source of up-to-date, collaborative financial data.

When submitting a request, it is recommended that you use the first and last name of the account owner or the business name, but not both. 

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.
BODY FIELD TYPE DESCRIPTION
accountValidationRequestoptional Object accountValidationRequest

Request example

{
    "accountValidationRequest": {
        "AOARequest": {
            "Inquiry": {
                "serviceType": "Owner",
                "secondaryId": "KeyCli01",
                "additionalId": "",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "amount": "",
                "serialNumber": "",
                "AcctOwner": {
                    "firstName": "Paul",
                    "lastName": "Wilson",
                    "middleName": "",
                    "namePrefix": "",
                    "nameSuffix": "",
                    "businessName": "",
                    "addressLine1": "206 GOODWIN ST",
                    "addressLine2": "",
                    "city": "MERRIT",
                    "state": "MI",
                    "zipCode": "49667",
                    "homePhone": "",
                    "workPhone": "",
                    "ssn": "666082367",
                    "dob": "19730801",
                    "idType": "2",
                    "idNo": "590909812",
                    "idState": "AL"
                },
                "Client": {
                    "clientDate": "2022-04-08",
                    "clientTime": "11:45:05",
                    "userDefined": "1234567890"
                }
            }
        }
    }
}
NAME TYPE DESCRIPTION
accountValidationResponseoptional Object accountValidationResponse

Response example (200)

{
    "accountValidationResponse": {
        "AOAResponse": {
            "Result": {
                "errorCode": "000",
                "systemRecordId": "5934871120174384",
                "primaryId": "TROM122101",
                "secondaryId": "KeyCli01",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "feeAttrib": "HH",
                "AcctOwner": {
                    "conditionCode": "000",
                    "nameMatch": "Y",
                    "firstNameMatch": "Y",
                    "lastNameMatch": "Y",
                    "addressMatch": "Y",
                    "cityMatch": "Y",
                    "stateMatch": "Y",
                    "zipCodeMatch": "Y",
                    "ssnMatch": "Y",
                    "dobMatch": "Y",
                    "idTypeMatch": "Y",
                    "idNoMatch": "Y",
                    "idStateMatch": "Y",
                    "overallMatchScore": "100"
                },
                "AcctStatus": {
                    "primaryStatusCode": "099",
                    "primMessage": "Open Valid"
                },
                "Client": {
                    "clientDate": "2022-04-08",
                    "clientTime": "11:45:05",
                    "userDefined": "1234567890"
                }
            }
        }
    }
}
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": "abcgd133",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "AOAResponse": {
            "Result": {
                "errorCode": "104"
            }
        }
    }
}
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.",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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 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.",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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 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.",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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 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.",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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 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.",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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 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.",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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 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.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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."
    }
}
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.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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."
    }
}
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.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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."
    }
}
NAMETYPEDESCRIPTION
firstNameoptionalstringFirst name of the account owner. Required with lastName if businessName is null.
lastNameoptionalstringLast name of the account owner. Required with firstName if businessName is null.
middleNameoptionalstringMiddle name of the account owner.
namePrefixoptionalstringOptional name prefix of the account owner. This field cannot exceed four characters. Example: Dr., Mr., Mrs.
nameSuffixoptionalstringOptional name suffix of the account owner. This field cannot exceed four characters. Example: Jr., PhD
businessNameoptionalstringBusiness name that owns the account. Required if lastName is null.
addressLine1optionalstringFirst line of the address on the account. This field cannot exceed 40 characters.
addressLine2optionalstringSecond line of the address on the account.
cityoptionalstringCity on the account.
stateoptionalstringTwo-character state abbreviation on the account.
zipCodeoptionalstringZIP code on the account. This can either be five digits or nine digits. If a nine-digit ZIP code is provided, a dash between the groups of digits is acceptable. Do not use a space.
homePhoneoptionalstring10-digit home phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
workPhoneoptionalstring10-digit work phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
ssnoptionalstringFull social security/tax ID number or the last four digits of the social security number of the account owner.
doboptionalstringDate of birth for the individual on the account. Format: YYYYMMDD
idTypeoptionalstringOne-character code that represents the type of identification used to verify the account owner.
idNooptionalstringID number for the account owner's form of identification. This field cannot exceed 28 characters.
idStateoptionalstringTwo-character state of issuance for the account owner's form of identification. If not a US state, enter the place of issuance. This field cannot exceed 6 characters.
NAMETYPEDESCRIPTION
firstNamerequiredstringFirst name of the account owner. Required with lastName if businessName is null.
lastNamerequiredstringLast name of the account owner. Required with firstName if businessName is null.
middleNameoptionalstringMiddle name of the account owner.
namePrefixoptionalstringOptional name prefix of the account owner. This field cannot exceed four characters. Example: Dr., Mr., Mrs.
nameSuffixoptionalstringOptional name suffix of the account owner. This field cannot exceed four characters. Example: Jr., PhD
businessNamerequiredstringBusiness name that owns the account. Required if lastName is null.
addressLine1optionalstringFirst line of the address on the account. This field cannot exceed 40 characters.
addressLine2optionalstringSecond line of the address on the account.
cityoptionalstringCity on the account.
stateoptionalstringTwo-character state abbreviation on the account.
zipCodeoptionalstringZIP code on the account. This can either be five digits or nine digits. If a nine-digit ZIP code is provided, a dash between the groups of digits is acceptable. Do not use a space.
homePhoneoptionalstring10-digit home phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
workPhoneoptionalstring10-digit work phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
ssnoptionalstringFull social security/tax ID number or the last four digits of the social security number of the account owner.
doboptionalstringDate of birth for the individual on the account. Format: YYYYMMDD
idTypeoptionalstringOne-character code that represents the type of identification used to verify the account owner.
idNooptionalstringID number for the account owner's form of identification. This field cannot exceed 28 characters.
idStateoptionalstringTwo-character state of issuance for the account owner's form of identification. If not a US state, enter the place of issuance. This field cannot exceed 6 characters.
NAMETYPEDESCRIPTION
firstNameoptionalstringFirst name of the account owner. Required with lastName if businessName is null.
lastNamerequiredstringLast name of the account owner. Required with firstName if businessName is null.
middleNameoptionalstringMiddle name of the account owner.
namePrefixoptionalstringOptional name prefix of the account owner. This field cannot exceed four characters. Example: Dr., Mr., Mrs.
nameSuffixoptionalstringOptional name suffix of the account owner. This field cannot exceed four characters. Example: Jr., PhD
businessNamerequiredstringBusiness name that owns the account. Required if lastName is null.
addressLine1optionalstringFirst line of the address on the account. This field cannot exceed 40 characters.
addressLine2optionalstringSecond line of the address on the account.
cityoptionalstringCity on the account.
stateoptionalstringTwo-character state abbreviation on the account.
zipCodeoptionalstringZIP code on the account. This can either be five digits or nine digits. If a nine-digit ZIP code is provided, a dash between the groups of digits is acceptable. Do not use a space.
homePhoneoptionalstring10-digit home phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
workPhoneoptionalstring10-digit work phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
ssnoptionalstringFull social security/tax ID number or the last four digits of the social security number of the account owner.
doboptionalstringDate of birth for the individual on the account. Format: YYYYMMDD
idTypeoptionalstringOne-character code that represents the type of identification used to verify the account owner.
idNooptionalstringID number for the account owner's form of identification. This field cannot exceed 28 characters.
idStateoptionalstringTwo-character state of issuance for the account owner's form of identification. If not a US state, enter the place of issuance. This field cannot exceed 6 characters.
NAMETYPEDESCRIPTION
firstNameoptionalstringFirst name of the account owner. Required with lastName if businessName is null.
lastNameoptionalstringLast name of the account owner. Required with firstName if businessName is null.
middleNameoptionalstringMiddle name of the account owner.
namePrefixoptionalstringOptional name prefix of the account owner. This field cannot exceed four characters. Example: Dr., Mr., Mrs.
nameSuffixoptionalstringOptional name suffix of the account owner. This field cannot exceed four characters. Example: Jr., PhD
businessNameoptionalstringBusiness name that owns the account. Required if lastName is null.
addressLine1optionalstringFirst line of the address on the account. This field cannot exceed 40 characters.
addressLine2optionalstringSecond line of the address on the account.
cityoptionalstringCity on the account.
stateoptionalstringTwo-character state abbreviation on the account.
zipCodeoptionalstringZIP code on the account. This can either be five digits or nine digits. If a nine-digit ZIP code is provided, a dash between the groups of digits is acceptable. Do not use a space.
homePhoneoptionalstring10-digit home phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
workPhoneoptionalstring10-digit work phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
ssnoptionalstringFull social security/tax ID number or the last four digits of the social security number of the account owner.
doboptionalstringDate of birth for the individual on the account. Format: YYYYMMDD
idTypeoptionalstringOne-character code that represents the type of identification used to verify the account owner.
idNooptionalstringID number for the account owner's form of identification. This field cannot exceed 28 characters.
idStateoptionalstringTwo-character state of issuance for the account owner's form of identification. If not a US state, enter the place of issuance. This field cannot exceed 6 characters.
NAMETYPEDESCRIPTION
firstNameoptionalstringFirst name of the account owner. Required with lastName if businessName is null.
lastNameoptionalstringLast name of the account owner. Required with firstName if businessName is null.
middleNameoptionalstringMiddle name of the account owner.
namePrefixoptionalstringOptional name prefix of the account owner. This field cannot exceed four characters. Example: Dr., Mr., Mrs.
nameSuffixoptionalstringOptional name suffix of the account owner. This field cannot exceed four characters. Example: Jr., PhD
businessNameoptionalstringBusiness name that owns the account. Required if lastName is null.
addressLine1optionalstringFirst line of the address on the account. This field cannot exceed 40 characters.
addressLine2optionalstringSecond line of the address on the account. This field cannot exceed 40 characters.
cityoptionalstringCity on the account.
stateoptionalstringTwo-character state abbreviation on the account.
zipCodeoptionalstringZIP code on the account. This can either be five digits or nine digits. If a nine-digit ZIP code is provided, a dash between the groups of digits is acceptable. Do not use a space.
homePhoneoptionalstring10-digit home phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
workPhoneoptionalstring10-digit work phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
ssnoptionalstringFull social security/tax ID number or the last four digits of the social security number of the account owner.
doboptionalstringDate of birth for the individual on the account. Format: YYYYMMDD
idTypeoptionalstringOne-character code that represents the type of identification used to verify the account owner.
idNooptionalstringID number for the account owner's form of identification. This field cannot exceed 28 characters.
idStateoptionalstringTwo-character state of issuance for the account owner's form of identification. If not a US state, enter the place of issuance. This field cannot exceed 6 characters.
NAMETYPEDESCRIPTION
conditionCodeoptionalstringThree-digit system response code that reflects the state of the account owner provided.
nameMatchoptionalstringFirst name, middle name, and last name match status. Valid values: Y, N, C, U
firstNameMatchoptionalstringFirst name match status. Valid values: Y, N, U
lastNameMatchoptionalstringLast name match status. Valid values: Y, N, U
middleNameMatchoptionalstringMiddle name or initial match status. Valid values: Y, N, U
namePrefixMatchoptionalstringName prefix match status. U will always be returned for a name prefix if included in the request.
nameSuffixMatchoptionalstringName suffix match status. U will always be returned for a name suffix if included in the request.
businessNameMatchoptionalstringBusiness name match status. Valid values: Y, N, C, U
addressMatchoptionalstringCombined address line one and two match status. Valid values: Y, N, C, U
cityMatchoptionalstringCity match status. Valid values: Y, N, C, U
stateMatchoptionalstringState match status. Valid values: Y, N, U
zipCodeMatchoptionalstringZIP code match status. Valid values: Y, N, C, U
homePhoneMatchoptionalstringHome phone number match status. Valid values: Y, N, C, U
workPhoneMatchoptionalstringWork phone number match status. Valid values: Y, N, C, U
ssnMatchoptionalstringSSN/TIN or last four digits of SSN match status. Valid values: Y, N, C, U
dobMatchoptionalstringDate of birth match status. Valid values: Y, N, C, U
idTypeMatchoptionalstringID type match status. Valid values: Y, N, U
idNoMatchoptionalstringID number match status. Valid values: Y, N, C, U
idStateMatchoptionalstringState or place of issuance match status. Valid values: Y, N, U
overallMatchScoreoptionalstringThe measure of how closely the inquiry request attributes match the actual account ownership data. This number is calculated based on the analysis of all information sent. Valid values: 0-100
NAMETYPEDESCRIPTION
primaryStatusCodeoptionalstringPrimary three-digit account status code. This is an informational response code that represents the status of an account.
primMessageoptionalstringMessage associated with the primary status code.
NAMETYPEDESCRIPTION
InquiryoptionalObjectinquiry
NAMETYPEDESCRIPTION
errorCodeoptionalstringThree-digit error code. Returns a "000" when no errors are present.
systemRecordIdoptionalstringUnique, system-generated transaction ID.
primaryIdoptionalstringPrimary client ID returned via a KeyBank lookup.
secondaryIdoptionalstringSecondary client ID provided in the original request.
additionalIdoptionalstringAdditional client ID, if provided in the original request.
routingNumberoptionalstringNine-digit routing number for the account provided in the original request.
accountNumberoptionalstringFull bank account number provided in the original request.
feeAttriboptionalstringTwo-character code that represents how a transaction took place. Currently, the only value reported is "HH", which represents an ACH transaction.
amountoptionalstringAmount of the transaction, if provided in the original request.
serialNumberoptionalstringSerial number of the check, if provided in the original request.
AcctOwneroptionalObjectaccountOwnerResponse
AcctStatusoptionalObjectaccountStatus
ClientoptionalObjectclient
NAMETYPEDESCRIPTION
accountValidationRequestoptionalObjectaccountValidationRequest
NAMETYPEDESCRIPTION
accountValidationResponseoptionalObjectaccountValidationResponse
NAMETYPEDESCRIPTION
clientDateoptionalstringClient-provided date the inquiry request was made. Format: YYYY-MM-DD
clientTimeoptionalstringClient-provided time the inquiry request was made. Format: HH:MM:SS
userDefinedoptionalstringClient-provided descriptive text about the inquiry request. This field cannot exceed 255 characters.
NAMETYPEDESCRIPTION
ConnectErroroptionalstringAPI connectivity error information, if available.
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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimeoptionalstringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptionaloneOfserviceErrorData connectError
NAMETYPEDESCRIPTION
serviceTyperequiredstringRepresents the type of request made to the API. This value is case-sensitive and must be set to "Owner".
secondaryIdrequiredstringSecondary client ID provided by KeyBank.
additionalIdoptionalstringAdditional client ID provided by KeyBank. This is only required if provided during onboarding.
routingNumberrequiredstringNine-digit routing number for the account, including leading zeroes.
accountNumberrequiredstringFull bank account number, without separators or leading zeroes. The length and format depends on the bank. This field cannot exceed 17 characters.
amountoptionalstringDollar amount of the transaction. The amount can be formatted as a whole dollar amount or with cents. This field cannot exceed 12 characters.
serialNumberoptionalstringSerial number of the check. Serial number does not apply to ACH inquiries.
AcctOwneroptionalanyOfaccountOwnerFirstLastName accountOwnerBusinessFirstName accountOwnerBusinessName accountOwnerBusinessLastName accountOwnerBusinessFirstLastName
ClientoptionalObjectclient
NAMETYPEDESCRIPTION
errorCodeoptionalstringThree-digit error code. Returns a "000" when no errors are present.

For more information about errors, see Error handling.

When a problem occurs with the capture of the account information from a draftable account item or the evaluation of the request message fields, a 3-digit error code is provided in the response payload (errorCode). If no errors are present, this field is filled with three zeroes.

ERROR CODE DESCRIPTION
000 Normal response - no errors
001 Invalid routing number
003 Invalid account number
005 Invalid serial number
006 Missing a required field
008 Length of account number is incorrect
010 Inquiry field length too short
011 Inquiry field length too long
013 Invalid amount field
103 Client ID does not match
104 Improper data type or value
105 Bad layout or format
106 Missing client record ID
107 Invalid required format
997 Authorization unavailable
998 System failure
999 Timeout

Condition codes reflect the state of the account owner data provided. When a condition code is returned in the response payload (conditionCode), users may still receive a partial response, such as an account status.

CONDITION CODE DESCRIPTION
000 Normal response - no system errors
300 Valid routing number, but not a participant
301 Valid participant, but not an account owner authentication contributor
302 Valid participant, but account owner authentication data is unavailable
304 No name field populated - first, last, or business name
396 No known information for the account number
900/901 No account owner response requested or provided

Account status codes are the specific account codes that may result from an account validation request and are returned in the response payload in the primaryStatusCode field.

STATUS CODE DESCRIPTION
000 Routing number/account number combination cannot be located
012 Account is closed
096 No positive or negative information is known about the account
099 Account is present in participant's master account file and contains no other status code

Depending on the service type configured, the accountOwnerResponse object can contain several fields that end in “Match”. Each of these match fields contains a single-character code that signifies whether or not an account owner element was found.

CODE DESCRIPTION
Y Close or exact match
C Conditional match
N No match
U No identifying data is available

For all fields the following response rules apply:

  • The account data matched in the database is determined based on the routing number and account number in the request.

  • Account matching will be performed only if a request contains:

    • First name and last name, and/or

    • Business name

  • All fields included in the request will be matched against the database.

The following are ignored:

  • Case

  • Spacing

  • Punctuation

"C"onditional (partial) match responses are applicable to the following fields:

  • Full name (firstName + middleName + lastName)

  • Business names

  • Street address (addressLine1 + addressLine2)

  • City

  • ZIP (first five digits)

  • Home phone

  • Work phone

  • SSN (if nine digits are provided)

  • DOB

  • ID number

Only Y/N matches are applicable to the following fields:

  • First name

  • Last name

  • Middle name or initial

  • State

  • SSN (if last four digits are provided)

  • ID type

  • ID state


YAML file