Account Validation v2 | API Documentation

Validate an account and its owner with confidence

Account Validation v2 API Endpoints

Summary	Endpoint
Health check	get /accounts/validations/v2/healthCheck
Verify an account	post /accounts/validations/v2/verifyAccount

Before you begin

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

Overview

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

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

There are some codes you may need help with deciphering. Look at our Data values or if your code is part of an error message, look at our error handling section.

Health check

get /accounts/validations/v2/healthCheck

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

Request

Responses

Successful response

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)

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

Verify an account

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.

Request

BODY FIELD	TYPE	DESCRIPTION
accountValidationV2Requestrequired	Object	accountValidationV2Request

Request example

{
    "accountValidationV2Request": {
        "AOARequest": {
            "Inquiry": {
                "serviceType": "Owner",
                "secondaryId": "KeyCli03",
                "additionalId": "AddCli04",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "amount": "110.99",
                "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": ""
                }
            }
        }
    }
}

Responses

OK

NAME	TYPE	DESCRIPTION
accountValidationV2Responserequired	Object	accountValidationV2Response

Response example (200)

{
    "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": ""
                }
            }
        }
    }
}

Missing mandatory information

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

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

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

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

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
    "ErrorMessage": "Access Denied for client ip",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

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

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

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

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

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

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

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

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

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

Unavailable service

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

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

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

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

Schemas

healthResponse

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.

exception

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

connectError

NAME	TYPE	DESCRIPTION
ConnectErroroptional	string	API connectivity error information, if available.

serviceErrorData

NAME	TYPE	DESCRIPTION
errorCodeoptional	string	Three-digit error code. Returns a "000" when no errors are present.

accountValidationV2Request

NAME	TYPE	DESCRIPTION
AOARequestoptional	Object	AOARequest

Inquiry

NAME	TYPE	DESCRIPTION
serviceTyperequired	string	Represents the type of request made to the API. This value is case-sensitive and must be set to "Owner".
secondaryIdrequired	string	Secondary client ID provided by KeyBank. No special characters are allowed. This values is provided by KeyBank during onboarding.
additionalIdoptional	string	Additional client ID provided by KeyBank. This is rarely used and if required, the value is provided during onboarding.
routingNumberrequired	string	Nine-digit routing number for the account, including leading zeroes.
accountNumberrequired	string	Full bank account number, without separators or leading zeroes. The length and format depends on the bank. This field cannot exceed 17 characters.
amountoptional	string	Dollar amount of the transaction or the field can be zero-filled. The amount can be formatted as a whole dollar with or without cents. This field cannot exceed 12 characters.
serialNumberoptional	string	Serial number of the check. Serial number does not apply to ACH inquiries.
AcctOwneroptional	Object	AcctOwner
Clientoptional	Object	Client

AOARequest

NAME	TYPE	DESCRIPTION
Inquiryoptional	Object	Inquiry

AOAResponse

NAME	TYPE	DESCRIPTION
Resultoptional	Object	Result

errorResponse

NAME	TYPE	DESCRIPTION
businessFaultoptional	Object	businessFault
systemFaultoptional	Object	systemFault

AcctOwner_1

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, 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.
nameSuffixMatchoptional	string	Name suffix match status. U will always be returned for a name suffix if included in the request.
businessNameMatchoptional	string	Business name match status. Valid values: Y, N, U
addressMatchoptional	string	Combined address line one and two match status. Valid values: Y, N, U
cityMatchoptional	string	City match status. Valid values: Y, N, U
stateMatchoptional	string	State match status. Valid values: Y, N, U
zipCodeMatchoptional	string	ZIP code match status. Valid values: Y, N, U
homePhoneMatchoptional	string	Home phone number match status. Valid values: Y, N, U
workPhoneMatchoptional	string	Work phone number match status. Valid values: Y, N, U
ssnMatchoptional	string	SSN/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
dobMatchoptional	string	Date of birth match status. Valid values: Y, N, U
idTypeMatchoptional	string	ID type match status. Valid values: Y, N, U
idNoMatchoptional	string	ID number match status. Valid values: Y, N, 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

Result

NAME	TYPE	DESCRIPTION
errorCodeoptional	string	Three-digit error code. Returns a "000" when no errors are present.
systemRecordIdoptional	string	Unique, system-generated transaction ID.
primaryIdoptional	string	Primary client ID returned via a KeyBank lookup. This is a KeyBank ID.
secondaryIdoptional	string	Secondary client ID provided in the original request.
additionalIdoptional	string	Additional client ID, if provided in the original request. This is rarely used.
routingNumberoptional	string	Nine-digit routing number for the account provided in the original request.
accountNumberoptional	string	Full bank account number provided in the original request.
feeAttriboptional	string	Two-character code that represents how a transaction took place. Currently, the only value reported is "HH", which represents an ACH transaction.
amountoptional	string	Amount of the transaction, if provided in the original request.
AcctOwneroptional	Object	AcctOwner_1
AcctStatusoptional	Object	AcctStatus
Clientoptional	Object	Client_1

systemFault

NAME	TYPE	DESCRIPTION
errorDescriptionoptional	string	Descriptive error message that identifies if it is a system issue or business fault.

AcctStatus

NAME	TYPE	DESCRIPTION
primaryStatusCodeoptional	string	Primary three-digit account status code. This is an informational response code that represents the status of an account.
primMessageoptional	string	Message associated with the primary status code.

accountValidation_POST_bodyParameters

NAME	TYPE	DESCRIPTION
accountValidationV2Requestrequired	Object	accountValidationV2Request

businessFault

NAME	TYPE	DESCRIPTION
errorDescriptionoptional	string	Descriptive error message that identifies if it is a system issue or business fault.

Client

NAME	TYPE	DESCRIPTION
clientDateoptional	string	Client-provided date the inquiry request was made. Format: YYYY-MM-DD
clientTimeoptional	string	Client-provided time the inquiry request was made. Format: HH:MM:SS
userDefinedoptional	string	Client-provided descriptive text about the inquiry request. This field cannot exceed 255 characters.

accountValidation_POST_response

NAME	TYPE	DESCRIPTION
accountValidationV2Responserequired	Object	accountValidationV2Response

accountValidationV2Response

NAME	TYPE	DESCRIPTION
AOAResponseoptional	Object	AOAResponse
errorResponserequired	Object	errorResponse

Client_1

NAME	TYPE	DESCRIPTION
clientDateoptional	string	Client-provided date the inquiry request was made. Format: YYYY-MM-DD
clientTimeoptional	string	Client-provided time the inquiry request was made. Format: HH:MM:SS
userDefinedoptional	string	Client-provided descriptive text about the inquiry request. This field cannot exceed 255 characters.

AcctOwner

NAME	TYPE	DESCRIPTION
firstNameoptional	string	First name of the account owner. Required with lastName if businessName is null.
lastNameoptional	string	Last name of the account owner. Required with firstName if businessName is null.
middleNameoptional	string	Middle name of the account owner.
namePrefixoptional	string	Optional name prefix of the account owner. This field cannot exceed four characters. Example: Dr., Mr., Mrs.
nameSuffixoptional	string	Optional name suffix of the account owner. This field cannot exceed four characters. Example: Jr., PhD
businessNameoptional	string	Business name that owns the account. Required if lastName is null.
addressLine1optional	string	First line of the address on the account. This field cannot exceed 40 characters.
addressLine2optional	string	Second line of the address on the account.
cityoptional	string	City on the account.
stateoptional	string	Two-character state abbreviation on the account.
zipCodeoptional	string	ZIP 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.
homePhoneoptional	string	10-digit home phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
workPhoneoptional	string	10-digit work phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
ssnoptional	string	Full social security/tax ID number or the last four digits of the social security number of the account owner.
doboptional	string	Date of birth for the individual on the account. Format: YYYYMMDD
idTypeoptional	string	One-character [code that represents the type of identification used to verify the account owner.
idNooptional	string	ID number for the account owner's form of identification. This field cannot exceed 28 characters.
idStateoptional	string	Two-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.

Errors

For more information about errors, see Error handling.

System error codes

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

YAML file