Account Validation User Guide | API Documentation

Key takeaways

Use API v2 for the latest enhancements and for more meaningful results.
Help reduce fraud by validating the owner of an account, matching the intended counterparty before moving funds.
Help minimize returns by confirming an account is open and valid before transacting with the account.
Comply with Nacha rules requiring account validation for web debits in real time without need for prenotes or micro-deposits.
Help save time with immediate validation for account inquiries.

Try it yourself

If you want to use our Account Validation API, please contact us to learn more.
Contact us

Everyone needs validation

With the Account Validation API, you can inquire about an account and a get real-time confirmation back on the status of the account and whether the ownership data matches. By real-time, we mean like 5 seconds or less on average. This is a far contrast to pre-notes or micro deposits which can take days and possibly accrue cost if there a return involved for illegitimate accounts.

Account validation is simple. You send an inquiry request to evaluate the account information from a draft account item, typically a check or an ACH item. KeyBank completes Account Ownership Authentication (AOA). This is an API service that enables payment processors to verify the information matches data in the National shared Database (NSD). It reviews the payer’s name, address, and other elements and responds with whether the payer is authorized to transact on the account.

This service is priced per each successful transaction. Speak with your Embedded Banking Payments Advisor to learn more. You can see our Getting Started Guide to learn more about how to partner with KeyBank APIs.

See the v2 specs

Inquire about an account owner

When you make a request, you must know the following parameter information:

secondaryID: This is a unique identification assigned by KeyBank to each client of the API and identifies which client is making the call. This is not the same as your client credentials used to get an access token.
routingNumber: The routing number of the bank account holder.
accountNumber: The bank account number of the account owner.

Search by...

You can search by a person or a business, but not both.

A personal inquiry validates an account with the owner's full name.
(firstName + lastName)

A business inquiry validates an account with a business or company name.
(businessName)

Share the details

To include more data points for verification, you can use the AcctOwner object to inquire about a personal or business account. The information you provide in the request is reviewed for a match in the database. If you do not enter any information in a field, it will not be reviewed for a match and returns as a blank field.

Good to know

AOA is possible at KeyBank with the Account Validation API product.
We only confirm account ownership. At the moment, we do not provide a detailed account status or risk-based score.

Validate ownership

In each response, the result shows the levels of review that take place to validate an account that can be broken up into four categories.

Request summary - Returns the search parameters sent in the request.
Account ownership - Reviews the AcctOwner attributes provided in the request and responds with if they match the data in the NSD. This includes the overall match score, a score from 1 to 100 for how much of the data matched.
Account status - The validity of the account and routing numbers.

Request summary

The response starts with an error code (errorCode), a three-digit code that lets you know if there are any errors present with the account information from a draftable account item or the evaluation of the request message fields. If no errors are present, this field is filled with three zeroes. If you do not get magical three zeroes, go to the Account Validation API document to view specific error handling codes.

Following the error code, is a summary of the request information provided. Client information that is part of the submitted request is returned as part of the response. This includes pertinent identification parameters useful for reference, traceability, and security.

Important API identifiers

systemRecordId: The system record ID is a unique ID assigned to the response for traceability purposes.
primaryID: The primary ID is a KeyBank ID that is generated as part of the data lookup. This indicates that the call came from inside the house.
secondaryId: The secondary ID is your unique ID that is assigned to you as part of the API onboarding process. This indicates that you made the call for verification.
additionalId: This ID is rarely used. If it is used, KeyBank will provide you with the additional ID value during API onboarding.

It also returns the account number, routing number, and amount if provided in the request. The fee attribute (feeAttrib) only returns the 'HH' value for ACH transaction types.

Account ownership

Basic validation passes additional data points from the AcctOwner object like the address, phone number, and date of birth to compare with the NSD. The case, spacing, and punctuation are ignored when matching values.

The response returns:

a condition code telling you the state of the account owner data provided.
match codes that confirm the data is the found or not with a Y (Yes), N (No), C (Conditional), or U (Unknown).
an overall match score is generated based on number of data points that did and did not match. If most of the match codes are Y, you will have a higher match score.

If the response returns an empty field, there is no entry in the database.

Condition codes

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

Match codes

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

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

Overall match score

The provided overall match score uses an banking industry standard to calculate on a scale of 1 to 100 the level of data that matches between the account owner and the NSD. The industry recommendation is to approve any account with a match score of 81 and above.

This may not be your standard of owner validity. It is important to know what is an appropriate risk tolerance for account owner validation. Reaching out to one of KeyBank's Payment Advisors is a good place to begin this conversation if you need help.

Account owner status

The account status object (AcctStatus) returns a three-digit code for the current condition of the bank account. The primary status code (primaryStatusCode) indicates if the account is open, closed, or not found. Each code has an associated message with additional details (primMessage).

Account status codes

Code	Message
000	Routing number and account number combination cannot be found
012	Account is closed
096	No positive or negative information in known about the account
099	Account is present in the participant’s master account file and has no other status code

Common terms

AOA: Account Owner Authentication matches the account owner identity to the bank account, confirming if data is accurate when compared against the NSD.
EB: Embedded Banking is a sector of KeyBank dedicated to developing and delivering quality digital services integration in both traditional and modern environments.
Micro deposits: Small amounts of money sent from one financial account to another to verify and authenticate account ownership.
Nacha: National Automated Clearing House Association the organization responsible for managing the rules and regulations governing the ACH network in the US.
NSD: National Shared Database is the collection of data contributed to by consumers and used to verify account owner information.
Prenotes: Test transactions to help confirm the correct bank account information, like the penny test.
Onboarding: The process of helping KeyBank partners and API consumers get familiar with our suite of API products. This can include assessment, setup, and environment access.

Request and response example

All requests require the secondaryId provided during KeyBank onboarding, routing number, and an account number.
If this is a personal inquiry, at a minimum search by accountNumber and routingNumber with firstName and lastName.
If this is a business inquiry, at a minimum search by accountNumber, routingNumber, and businessName.

Request

Response

accountValidationRequest: {                                                                                                                      AOARequest: {                                                                                                                          Inquiry: {
      serviceType: "Owner",
      secondaryID: "KeyCli01",
      additionalID: "",
      routingNumber: "122199983",
      accountNumber: "89455",
      amount:"50.50",
      serialNumber: "",
      AcctOwner: {
        firstName: " Paul;",
        lastName: "Wilson ",
        middleName: "V",
        namePrefix: "Mr",
        nameSuffix: "",
        businessName: "Bizness by Paul",
        addressLine1: "206 GOODWIN ST",
        addressLine2: "",
        city: "MERRIT",
        state: "MI",
        zipCode: "49667",
        homePhone: "5555551234",
        workPhone: "5555561234",
        ssn: "9999",
        dob: "19730801",
        idType: "2",
        idNo: "6788",
        idState: "AL"
      },
      Client: {
        ClientDt: "2022-03-04",
        ClientTime: "14:45:05",
        UserDef: "123xyz"
      }
  }}

"accountValidationResponse": {
  AOAResponse: {
    Result: {
      errorCode: "000",
      systemRecordId: "5934871120174384",
      primaryId: "TROM122101",
      secondaryId: "KeyCli01",
      additionalId: "",
      routingNumber: "122199983",
      accountNumber: "89455",
      feeAttrib: "HH",
      amount:"50.50",
      serialNumber:"",
      AcctOwner: {
        conditionCode: "000",
        nameMatch: "Y",
        firstNameMatch: "Y",
        lastNameMatch: "Y",
        middleNameMatch: "Y",
        namePrefixMatch: "",
        nameSuffixMatch: "",
        businessNameMatch: "Y",
        addressMatch: "Y",
        cityMatch: "Y",
        stateMatch: "Y",
        zipCodeMatch: "Y",
        homePhoneMatch: "",
        workPhoneMatch: "",
        ssnMatch: "Y",
        dobMatch: "Y",
        idTypeMatch: "Y",
        idNoMatch: "Y",
        idStateMatch: "Y",
        overallMatchScore: "100"
      },
      AcctStatus": {
        primaryStatusCode: "099",
        primMessage: "Open Valid"
      },
      Client: {
        clientDate: "2022-03-04",
        clientTime: "14:45:05",
        userDefined: "123xyz"
     } 
   }
 }}

What to expect

The data provided in the request is compared to the NSD. After evaluation, you get a response that indicates if there is a match or any discrepancies.
Review the response and interpret the information according to your needs and business rules. You can consider the response data in your decision-making process, along with other risk management information.

What's next?

View our Getting Started Guide to get an overview of the onboarding process.
Get better acquainted with our API and check out the Account Validation API reference material.