Account Validation v1

clock 4-minute read calender 1.0.4 | updated May. 29, 2024

Verify an account and its owner with confidence

Important note: This version will soon deprecate and be replaced with Account Validation API v2. We recommend using the latest version and for existing clients to upgrade to v2.

What you can do Endpoint
Health check GET /accounts/validations/v1/healthCheck
Verify an account POST /accounts/validations/v1/verifyAccount

Before you begin

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

When you submit a request to the Account Validation API, the data in that request is compared to information in the National Shared Database. The National Shared Database is the financial industry's leading source of up-to-date, collaborative financial data. Results from the database comparison are evaluated and then returns a response to you in real time, verifying the account owner status quickly.

The following response rules apply for all fields:

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

  • Account matching will be performed only if a request contains firstName and lastName, and/or businessName.

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

  • Case, spacing, and punctuation are ignored.

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

 

Service-level

  • System error codes (errorCode)
  • Inquiry field validation error codes

Account-level

  • Condition codes (conditionCode)
  • Account status codes (primaryStatusCode)
  • Account owner field matching (accountOwnerResponse)

 


get /accounts/validations/v1/healthCheck

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

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

BODY FIELDTYPEDESCRIPTION
accountValidationRequestoptionalObjectaccountValidationRequest

Request example

copylink
{
    "accountValidationRequest": {
        "AOARequest": {
            "Inquiry": {
                "serviceType": "Owner",
                "secondaryId": "KeyCli01",
                "additionalId": "",
                "routingNumber": "122199983",
                "accountNumber": "123456789",
                "amount": "50.50",
                "serialNumber": "",
                "AcctOwner": {
                    "firstName": "Paul",
                    "lastName": "Wilson",
                    "middleName": "V",
                    "namePrefix": "Mr",
                    "nameSuffix": "Son",
                    "businessName": "Business by Paul",
                    "addressLine1": "127 Public Square",
                    "addressLine2": "Suite A",
                    "city": "Cleveland",
                    "state": "OH",
                    "zipCode": "44114",
                    "homePhone": "",
                    "workPhone": "",
                    "ssn": "9976",
                    "dob": "19730801",
                    "idType": "2",
                    "idNo": "6788",
                    "idState": "AL"
                },
                "Client": {
                    "clientDate": "2022-04-08",
                    "clientTime": "11:45:05",
                    "userDefined": "1234567890"
                }
            }
        }
    }
}
NAMETYPEDESCRIPTION
accountValidationResponseoptionalObjectaccountValidationResponse

Response example (200)

copylink
{
    "accountValidationResponse": {
        "AOAResponse": {
            "Result": {
                "errorCode": "000",
                "systemRecordId": "650580221072984",
                "primaryId": "TROM122101",
                "secondaryId": "KeyCli01",
                "routingNumber": "122199983",
                "accountNumber": "123456789",
                "feeAttrib": "HH",
                "amount": "50.50",
                "AcctOwner": {
                    "conditionCode": "000",
                    "nameMatch": "Y",
                    "firstNameMatch": "Y",
                    "lastNameMatch": "Y",
                    "middleNameMatch": "N",
                    "namePrefixMatch": "U",
                    "nameSuffixMatch": "U",
                    "addressMatch": "Y",
                    "cityMatch": "Y",
                    "stateMatch": "Y",
                    "zipCodeMatch": "Y",
                    "ssnMatch": "N",
                    "dobMatch": "Y",
                    "idTypeMatch": "Y",
                    "idNoMatch": "N",
                    "idStateMatch": "Y",
                    "overallMatchScore": "62"
                },
                "AcctStatus": {
                    "primaryStatusCode": "099",
                    "primMessage": "Open Valid"
                },
                "Client": {
                    "clientDate": "2022-04-08",
                    "clientTime": "11:45:05",
                    "userDefined": "1234567890"
                }
            }
        }
    }
}
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

Response example (400)

copylink
{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "abcgd133",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "AOAResponse": {
            "Result": {
                "errorCode": "104"
            }
        }
    }
}
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

Response example (401)

copylink
{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
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

Response example (403)

copylink
{
    "ErrorMessage": "Access Denied for client ip",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
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

Response example (404)

copylink
{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
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

Response example (415)

copylink
{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
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

Response example (429)

copylink
{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
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

Response example (500)

copylink
{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
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

Response example (502)

copylink
{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}
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

Response example (503)

copylink
{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable(NoActiveTargets), please check with appplication support before resubmitting the request."
    }
}
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

Response example (504)

copylink
{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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
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.
NAME TYPE DESCRIPTION
conditionCodeoptional string Three-digit system response code that reflects the state of the account owner provided.
nameMatchoptional string First name, middle name, and last name match status. Valid values: Y, N, C, U
firstNameMatchoptional string First name match status. Valid values: Y, N, U
lastNameMatchoptional string Last name match status. Valid values: Y, N, U
middleNameMatchoptional string Middle name or initial match status. Valid values: Y, N, U
namePrefixMatchoptional string Name prefix match status. U will always be returned for a name prefix if included in the request. Valid values: Y, N, U
nameSuffixMatchoptional string Name suffix match status. U will always be returned for a name suffix if included in the request. Valid values: Y, N, U
businessNameMatchoptional string Business name match status. Valid values: Y, N, C, U
addressMatchoptional string Combined address line one and two match status. Valid values: Y, N, C, U
cityMatchoptional string City match status. Valid values: Y, N, C, U
stateMatchoptional string State match status. Valid values: Y, N, U
zipCodeMatchoptional string ZIP code match status. Valid values: Y, N, C, U
homePhoneMatchoptional string Home phone number match status. Valid values: Y, N, C, U
workPhoneMatchoptional string Work phone number match status. Valid values: Y, N, C, U
ssnMatchoptional string SSN/TIN or last four digits of SSN match status. Valid values: Y, N, C, U
dobMatchoptional string Date of birth match status. Valid values: Y, N, C, U
idTypeMatchoptional string ID type match status. Valid values: Y, N, U
idNoMatchoptional string ID number match status. Valid values: Y, N, C, U
idStateMatchoptional string State or place of issuance match status. Valid values: Y, N, U
overallMatchScoreoptional string The 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 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
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.
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.

You can get a confirmation of Y (Yes), N (No), C (Conditional), or U (Unknown). If you get a U with the businessNameMatch it could indicate that the routing and account numbers have been found in the database, but there is no business name associated with the account.

CODE DESCRIPTION Applies to match fields
Y Close or exact match firstNameMatch, lastNameMatch, middleNameMatch, namePrefixMatch, nameSuffixMatch, stateMatch, ssnMatch (if the last four digits are provided in the request), idType, idState
N No match
C Conditional match nameMatch, businessNameMatch, addressMatch, cityMatch, zipCodeMatch,homePhoneMatch, workPhoneMatch, ssnMatch (if nine digits are provided in the request),dobMatch, idNoMatch
U No identifying data is available Applies to all fields