Account Validation

clock 4-minute read calender 2.0.1 | updated Oct. 15, 2024

Validate an account and its owner with confidence

Before you begin

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

The Account Validation API evaluates account owner data through an inquiry request and response process, validating the account owner and their account for validity.

API maturity

Account Validation is growing up. Right now there are two operating versions of the Account Validation API with v2 being the most current and v1 about to deprecate. The latest version includes security and request schema enhancements to help deliver more meaningful responses. The first and original version of the Account Validation API will be obsolete by end of the first quarter in 2025. Until then, Account Validation v1 specifications are available here. 

We recommend you use the latest version or upgrade to Account Validation API v2 specifications.

Make a request

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.

Request requirements

When you submit a request, in addition to your authentication credentials, you must provide:

  • The account number of the person or business you want to validate. (accountNumber)
  • The routing number for the financial institution of the person or business. (routingNumber)
  • Set the validation type to Owner to request for owner status and validation. (serviceType)
  • An ID provided during KeyBank onboarding that is a secondary authentication method for the call besides the access token. This is not the same as your client or consumer ID. (secondaryId)

Interpret the response

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:

  • All fields included in the request will be matched against the database.
  • Case, spacing, and punctuation are ignored.
  • 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 the person's full name (firstName and lastName) OR the name of the business (businessName).

 

Result codes

Account Validation responses include a variety of codes and classifications to help you assess if the account is legitimate or not. Refer to the Account Validation User Guide to help decipher codes like these:

  • errorCode: Three-digit code about system errors. If there are no errors, you receive three zeros (000).
  • conditionCode: Three-digit code about the state and validity of account ownership.
  • primaryStatusCode: Three-digit code for account status.
  • accountOwnerResponse object: Account owner field matching showing a Y (Yes), N (No), C (Conditional), or U (Unknown).

Loads of codes

If you get code with your error message, look at our error handling section for more details.

get /accounts/validations/v2/healthCheck

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

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.

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/v2/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
accountValidationV2RequestrequiredObjectaccountValidationV2Request

Request example

copylink
{
    "accountValidationV2Request": {
        "AOARequest": {
            "Inquiry": {
                "serviceType": "Owner",
                "secondaryId": "KeyCli03",
                "additionalId": "AddCli04",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "amount": "110",
                "serialNumber": "",
                "AcctOwner": {
                    "firstName": "Paul",
                    "lastName": "wilson",
                    "middleName": "Dan",
                    "namePrefix": "Mr",
                    "nameSuffix": "Lal",
                    "businessName": "",
                    "addressLine1": "206 GOODWIN ST",
                    "addressLine2": "Land",
                    "city": "MERRIT",
                    "state": "MI",
                    "zipCode": "49667",
                    "homePhone": "3077553623",
                    "workPhone": "3077555330",
                    "ssn": "666082367",
                    "dob": "19730801",
                    "idType": "2",
                    "idNo": "590909812",
                    "idState": "AL"
                },
                "Client": {
                    "clientDate": "2022-12-31",
                    "clientTime": "14:00:80",
                    "userDefined": ""
                }
            }
        }
    }
}
NAMETYPEDESCRIPTION
accountValidationV2ResponserequiredObjectaccountValidationV2Response

Response example (200)

copylink
{
    "accountValidationV2Response": {
        "AOAResponse": {
            "Result": {
                "errorCode": "000",
                "systemRecordId": "8168140724120284",
                "primaryId": "TROM122101",
                "secondaryId": "KeyCli01",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "feeAttrib": "HH",
                "AcctOwner": {
                    "conditionCode": "000",
                    "addressMatch": "Y",
                    "cityMatch": "Y",
                    "stateMatch": "Y",
                    "zipCodeMatch": "Y",
                    "ssnMatch": "Y",
                    "overallMatchScore": "100"
                },
                "AcctStatus": {
                    "primaryStatusCode": "099",
                    "primMessage": "Open Valid"
                },
                "Client": {
                    "clientDate": "2022-12-31",
                    "clientTime": "14:00:80",
                    "userDefined": ""
                }
            }
        },
        "errorResponse": {
            "businessFault": {
                "errorDescription": "Text displays if there is an issue with the business applications."
            },
            "systemFault": {
                "errorDescription": "Text displays if there is an issue with backend systems."
            }
        }
    }
}
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 application 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
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
ConnectErroroptionalstringAPI connectivity error information, if available.
NAMETYPEDESCRIPTION
errorCodeoptionalstringThree-digit error code. Returns a "000" when no errors are present.
NAMETYPEDESCRIPTION
AOARequestoptionalObjectAOARequest
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. No special characters are allowed. This value is different from your client credentials.
additionalIdoptionalstringThis ID is rarely used. If it is required, KeyBank will provide this value 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.
amountoptionalstringDo not use. This field is deprecating in an upcoming version. Dollar amount of the transaction or this field can be zero-filled. The amount must be a whole number and cannot exceed 12 characters.
serialNumberoptionalstringDo not use. This field is deprecating in an upcoming version. Serial number of the check. This number does not apply for ACH inquiries.
AcctOwneroptionalObjectAcctOwner
ClientoptionalObjectClient
NAMETYPEDESCRIPTION
InquiryoptionalObjectInquiry
NAMETYPEDESCRIPTION
ResultoptionalObjectResult
NAMETYPEDESCRIPTION
businessFaultoptionalObjectbusinessFault
systemFaultoptionalObjectsystemFault
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, 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, U
addressMatchoptionalstringCombined address line one and two match status. Valid values: Y, N, U
cityMatchoptionalstringCity match status. Valid values: Y, N, U
stateMatchoptionalstringState match status. Valid values: Y, N, U
zipCodeMatchoptionalstringZIP code match status. Valid values: Y, N, U
homePhoneMatchoptionalstringHome phone number match status. Valid values: Y, N, U
workPhoneMatchoptionalstringWork phone number match status. Valid values: Y, N, U
ssnMatchoptionalstringSSN/TIN or last four digits of SSN match status. If you are a merchant provider, the value returned will always be 'U'. Valid values: Y, N, U
dobMatchoptionalstringDate of birth match status. Valid values: Y, N, U
idTypeMatchoptionalstringID type match status. Valid values: Y, N, U
idNoMatchoptionalstringID number match status. Valid values: Y, N, 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
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. This is a KeyBank ID.
secondaryIdoptionalstringSecondary client ID provided in the original request.
additionalIdoptionalstringAdditional client ID, if provided in the original request. This is rarely used.
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.
amountoptionalstringDo not use. This field is deprecating. Amount of the transaction, if provided in the original request.
AcctOwneroptionalObjectAcctOwner_1
AcctStatusoptionalObjectAcctStatus
ClientoptionalObjectClient_1
NAMETYPEDESCRIPTION
errorDescriptionoptionalstringDescriptive error message that identifies if it is a system issue or business fault.
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.

accountValidation_POST_bodyParameters

NAMETYPEDESCRIPTION
accountValidationV2RequestrequiredObjectaccountValidationV2Request
NAMETYPEDESCRIPTION
errorDescriptionoptionalstringDescriptive error message that identifies if it is a system issue or business fault.
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.

accountValidation_POST_response

NAMETYPEDESCRIPTION
accountValidationV2ResponserequiredObjectaccountValidationV2Response
NAMETYPEDESCRIPTION
AOAResponseoptionalObjectAOAResponse
errorResponserequiredObjecterrorResponse
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
firstNameoptionalstringFirst name of the account owner. Required with lastName for a personal inquiry.
lastNameoptionalstringLast name of the account owner. Required with firstName for a personal inquiry.
middleNameoptionalstringMiddle initial or name of the account owner. If the middle initial is provided do not include a period.
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 or the individual's full name (first and last name) that owns the account. This is a required field for a business inquiry.
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. Possible examples: 52255, 522551313, or 52255-1313.
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. Valid values: 0-9, A-Z
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 must be between 2-6 characters in length.

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

 

ReleaseAPI versionChange descriptionImpact
October 20242.0.1
  • For the amount field, the whole dollar amount is an acceptable value (no cents). Note, this field will be deprecating in the future.
  • Updated the businessName field and any supporting content to specify that you can use an individual's full name for a business account inquiry.
  • Added format and field description details to help define the meaning, use, and limitations of the field.
MID
August 20242.0.0MID
May 20241.0.3
  • 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.
LOW
May 20231.0.2
  • 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 download