Account Validation

Validate an account and its owner with confidence

Account Validation Endpoints

What can you do	Endpoint
Health check	get /accounts/validations/v2/healthCheck
Verify an account	post /accounts/validations/v2/verifyAccount

Key notes

Before you begin

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

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)

Verification rules

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

Verify an account

post /accounts/validations/v2/verifyAccount

Verify that an account owner details and if they are authorized to transact on the account by matching the account information provided to the National Shared Database Resource, the financial industry's leading source of up-to-date, collaborative financial data.

Request

NAME	TYPE	DESCRIPTION
accountValidationV2Requestrequired	Object	accountValidationV2Request

Request example

{
    "accountValidationV2Request": {
        "AOARequest": {
            "Inquiry": {
                "serviceType": "Owner",
                "secondaryId": "KeyCli03",
                "additionalId": "AddCli04",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "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": "",
                    "idNo": "590909812",
                    "idState": "AL"
                },
                "Client": {
                    "clientDate": "2022-12-03",
                    "clientTime": "14:00:00",
                    "userDefined": ""
                }
            }
        }
    }
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
accountValidationV2Responserequired	Object	accountValidationV2Response

Response example (200)

{
    "accountValidationV2Response": {
        "AOAResponse": {
            "Result": {
                "errorCode": "000",
                "systemRecordId": "2360130828140884",
                "primaryId": "TROM122101",
                "secondaryId": "KeyCli03",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "feeAttrib": "HH",
                "AcctOwner": {
                    "conditionCode": "000",
                    "nameMatch": "Y",
                    "firstNameMatch": "Y",
                    "lastNameMatch": "Y",
                    "middleNameMatch": "N",
                    "namePrefixMatch": "U",
                    "nameSuffixMatch": "U",
                    "addressMatch": "Y",
                    "cityMatch": "Y",
                    "stateMatch": "Y",
                    "zipCodeMatch": "Y",
                    "ssnMatch": "Y",
                    "dobMatch": "Y",
                    "idNoMatch": "Y",
                    "idStateMatch": "Y",
                    "overallMatchScore": "85"
                },
                "AcctStatus": {
                    "primaryStatusCode": "099",
                    "primMessage": "Open Valid"
                },
                "Client": {
                    "clientDate": "2022-12-31",
                    "clientTime": "14:00:80",
                    "userDefined": ""
                }
            }
        },
        "errorResponse": {
            "businessFault": {
                "errorDescription": "Description if an error is found."
            }
        }
    }
}

Missing mandatory information

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/accounts/validations/v2/verifyAccount",
    "ServiceError": {
        "AOAResponse": {
            "Result": {
                "errorCode": "104"
            }
        }
    }
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/accounts/validations/v2/verifyAccount"
}

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/accounts/validations/v2/verifyAccount"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/accounts/validations/v2/verifyAccount"
}

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/accounts/validations/v2/verifyAccount"
}

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/accounts/validations/v2/verifyAccount"
}

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/accounts/validations/v2/verifyAccount"
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/accounts/validations/v2/verifyAccount",
    "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
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/accounts/validations/v2/verifyAccount",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	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",
    "Api-Url": "/accounts/validations/v2/verifyAccount",
    "ServiceError": {
        "ConnectError": "Request could not be processed on time (GatewayTimeout), please wait a moment and resubmit the request"
    }
}

Schemas

healthResponse

NAME	TYPE	DESCRIPTION
Status	string	Status of the health check response.
Source	string	Origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
Timestamp	string	Date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIp	string	Client IP address the gateway receives from the request.
X-Forwarded-For	string	Sequence of IP addresses for systems between the client and the gateway.

exception

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	serviceErrorData connectError

connectError

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

serviceErrorData

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

accountValidationV2Request

NAME	TYPE	DESCRIPTION
AOARequest	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 value is different from your client credentials.
additionalId	string	This ID is rarely used. If it is 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.
AcctOwner	Object	AcctOwner
Client	Object	Client

AOARequest

NAME	TYPE	DESCRIPTION
Inquiry	Object	Inquiry

AOAResponse

NAME	TYPE	DESCRIPTION
Result	Object	Result

errorResponse

NAME	TYPE	DESCRIPTION
businessFault	Object	businessFault
systemFault	Object	systemFault

AcctOwner_1

NAME	TYPE	DESCRIPTION
conditionCode	string	Three-digit system response code that reflects the state of the account owner provided.
nameMatch	string	First name, middle name, and last name match status. Valid values: Y, N, U
firstNameMatch	string	First name match status. Valid values: Y, N, U
lastNameMatch	string	Last name match status. Valid values: Y, N, U
middleNameMatch	string	Middle name or initial match status. Valid values: Y, N, U
namePrefixMatch	string	Name prefix match status. U will always be returned for a name prefix if included in the request.
nameSuffixMatch	string	Name suffix match status. U will always be returned for a name suffix if included in the request.
businessNameMatch	string	Business name match status. Valid values: Y, N, U
addressMatch	string	Combined address line one and two match status. Valid values: Y, N, U
cityMatch	string	City match status. Valid values: Y, N, U
stateMatch	string	State match status. Valid values: Y, N, U
zipCodeMatch	string	ZIP code match status. Valid values: Y, N, U
homePhoneMatch	string	Home phone number match status. Valid values: Y, N, U
workPhoneMatch	string	Work phone number match status. Valid values: Y, N, U
ssnMatch	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
dobMatch	string	Date of birth match status. Valid values: Y, N, U
idTypeMatch	string	ID type match status. Valid values: Y, N, U
idNoMatch	string	ID number match status. Valid values: Y, N, U
idStateMatch	string	State or place of issuance match status. Valid values: Y, N, U
overallMatchScore	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
errorCode	string	Three-digit error code. Returns a "000" when no errors are present.
systemRecordId	string	Unique, system-generated transaction ID.
primaryId	string	Primary client ID returned via a KeyBank lookup. This is a KeyBank ID.
secondaryId	string	Secondary client ID provided in the original request.
additionalId	string	Additional client ID, if provided in the original request. This is rarely used.
routingNumber	string	Nine-digit routing number for the account provided in the original request.
accountNumber	string	Full bank account number provided in the original request.
feeAttrib	string	Two-character code that represents how a transaction took place. Currently, the only value reported is "HH", which represents an ACH transaction.
AcctOwner	Object	AcctOwner_1
AcctStatus	Object	AcctStatus
Client	Object	Client_1

systemFault

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

AcctStatus

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

accountValidation_POST_bodyParameters

NAME	TYPE	DESCRIPTION
accountValidationV2Requestrequired	Object	accountValidationV2Request

businessFault

NAME	TYPE	DESCRIPTION
errorDescription	string	Contains business system messages generated if there is an issue.

Client

NAME	TYPE	DESCRIPTION
clientDate	string	Client-provided date the inquiry request was made. Format: YYYY-MM-DD
clientTime	string	Client-provided time the inquiry request was made. Format: HH:MM:SS
userDefined	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
AOAResponse	Object	AOAResponse
errorResponserequired	Object	errorResponse

Client_1

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

AcctOwner

NAME	TYPE	DESCRIPTION
firstName	string	First name of the account owner. Required with lastName for a personal inquiry.
lastName	string	Last name of the account owner. Required with firstName for a personal inquiry.
middleName	string	Middle initial or name of the account owner. If the middle initial is provided do not include a period.
namePrefix	string	Optional name prefix of the account owner. This field cannot exceed four characters. Example: Dr., Mr., Mrs.
nameSuffix	string	Optional name suffix of the account owner. This field cannot exceed four characters. Example: Jr., PhD
businessName	string	Business name or the individual's full name (first and last name) that owns the account. This is a required field for a business inquiry.
addressLine1	string	First line of the address on the account. This field cannot exceed 40 characters.
addressLine2	string	Second line of the address on the account. For international addresses, combine province, country, and postal code in this second address line.
city	string	The city of the account owner if in the US. Keep this field blank for international addresses.
state	string	The two-character state abbreviation if in the US. Keep this field blank for international addresses.
zipCode	string	ZIP code of the account if in the US. 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. Keep this field blank for international addresses.
homePhone	string	10-digit home phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
workPhone	string	10-digit work phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
ssn	string	Full social security/tax ID number or the last four digits of the social security number of the account owner.
dob	string	Date of birth for the individual on the account. Format: YYYYMMDD
idType	string	One-character code that represents the type of identification used to verify the account owner. Valid values: 0-9, A-Z
idNo	string	ID number for the account owner's form of identification. This field cannot exceed 28 characters.
idState	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

The Account Validation API returns information about the requested item in one to two sections of the response.

AOARequest: A three-digit code in the response payload, errorCode , indicates if there was problem during data retrieval or not.
- If no errors are present, this field returns three zeroes.
- If there is a problem capturing account information from a draftable account item or an issue evaluating one of the request message fields, the API returns a 3-digit error code that tells you what needs to be corrected before the request is re-sent. Go to the Account Validation User Guide to error code details.
The errorResponse object is part of the response if an issue occurs from the application (businessFault) or backend system (systemFault). If there is an issue with the API connection, the connectError field is included in this response.

For help with common issues and errors, check out our Developer support pages.

View our Error handling information to understand how KeyBank reports errors.
Go to our Troubleshooting to get help diagnosing and resolving common HTTP errors.

Changelog

Release	API version	Change description	Impact
September 2025	2.0.4	Added `Api-Url` parameter to all instances of the `exception` schema. This parameter is now a standard part of all error messages to help you identify which call triggered an unsuccessful response.	LOW
April 2025	2.0.3	Modified `adrLine2`, `city`, `state`, and `zipCode` for international addresses in the `AcctOwner` object . With international addresses, leave the city, state, and zip code fields blank. Combine the province, country, and postal code in the `adrLine2` field.	LOW
December 2024	2.0.2	The `amount` and `serialNumber` parameters have deprecated. These parameters are no longer in from the `Inquiry` and `Result` objects.	LOW
October 2024	2.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 2024	2.0.0	We introduced the Account Validation API v2. This API executes the same objective as its predecessor, but now with a sleeker search criteria that condenses the code base to improve performance. Account Validation V1 is deprecating. The first and original version of the Account Validation API will be obsolete by end of the first quarter in 2025. Account Validation v1 specifications are available here.	MID
May 2024	1.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 2023	1.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