Account Validation

28 minute read 1.0.0 | updated Feb. 13, 2023

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

API consumers submit a request to the Account Validation API. The data in that request is compared to information in the National Shared Database Resource. Results from the database comparison are evaluated and then returned to the API consumer in real time in a response payload.

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

Service-level

  • System error codes
  • Inquiry field validation error codes

Account-level

  • Condition codes
  • Account status codes
  • Account owner field matching

KeyBank has some common prerequisites and best practices. All KeyBank APIs require certifications, user credentials, and certain permissions. Make sure to satisfy all prerequisites before building your API.

Follow these steps to prepare for operations:

  1. Have valid certificates for a secure connection.

  2. Make sure you have the API keys needed for basic authentication and API access.

  3. Request a bearer token before you start.

  4. Check the health of the API.

  5. Have the secondary and additional IDs required for an account verification request.

Certificates are a digital authentication method we use to encrypt the information exchanged between KeyBank and your app or service. To access KeyBank environments, you must exchange valid certificates with KeyBank. These certificates must be properly installed on your system before you start to send API calls.

You need API keys to get a bearer token and to grant access to the APIs and the Pre-Production or Production environments. These API keys are created only for authenticated users that have partnered with KeyBank. For more information, see API security or sign up to become a KeyBank API consumer

Get a bearer token before you start. Only authenticated users with client credentials can request a bearer token. For more information, see API security or sign up to become a KeyBank API consumer

Before you start building your API, perform a quick health check. A health check verifies that the API is operational and responding correctly with your system. A bearer token is required to perform a health check. For more information, see Health check.

KeyBank assigns a unique secondary ID (secondaryId) that is required for all account validation requests. If required, a unique additional ID (additionalId) is also assigned. Both IDs are shared via secure email.

Endpoint Result Description
post /accounts/validations/v1/verifyAccount Verify an account Verify an account owner.

post /accounts/validations/v1/verifyAccount

Verify that an account owner’s name, address, and other identifying elements match the account information in the National Shared Database Resource and that they are authorized to transact on the account. The National Shared Database Resource is the financial industry’s leading source of up-to-date, collaborative financial data.

HEADER FIELD TYPE DESCRIPTION
X-CorrelationIdoptional string Apply a universal ID to trace the transaction across all the systems involved. The ID is unique to each request. The ID must be alphanumeric with no spaces and cannot exceed 16 characters. If this field is left blank, the system generates a unique ID with the response.
BODY FIELD TYPE DESCRIPTION
accountValidationRequestoptional Object accountValidationRequest

Request example

{
    "accountValidationRequest": {
        "AOARequest": {
            "Inquiry": {
                "serviceType": "Owner",
                "secondaryId": "KeyCli01",
                "additionalId": "",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "amount": "",
                "serialNumber": "",
                "AcctOwner": {
                    "firstName": "Paul",
                    "lastName": "Wilson",
                    "middleName": "",
                    "namePrefix": "",
                    "nameSuffix": "",
                    "businessName": "",
                    "addressLine1": "206 GOODWIN ST",
                    "addressLine2": "",
                    "city": "MERRIT",
                    "state": "MI",
                    "zipCode": "49667",
                    "homePhone": "",
                    "workPhone": "",
                    "ssn": "666082367",
                    "dob": "19730801",
                    "idType": "2",
                    "idNo": "590909812",
                    "idState": "AL"
                },
                "Client": {
                    "clientDate": "2022-04-08",
                    "clientTime": "11:45:05",
                    "userDefined": "1234567890"
                }
            }
        }
    }
}
NAME TYPE DESCRIPTION
accountValidationResponseoptional Object accountValidationResponse

Response example (200)

{
    "accountValidationResponse": {
        "AOAResponse": {
            "Result": {
                "errorCode": "000",
                "systemRecordId": "5934871120174384",
                "primaryId": "TROM122101",
                "secondaryId": "KeyCli01",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "feeAttrib": "HH",
                "AcctOwner": {
                    "conditionCode": "000",
                    "nameMatch": "Y",
                    "firstNameMatch": "Y",
                    "lastNameMatch": "Y",
                    "addressMatch": "Y",
                    "cityMatch": "Y",
                    "stateMatch": "Y",
                    "zipCodeMatch": "Y",
                    "ssnMatch": "Y",
                    "dobMatch": "Y",
                    "idTypeMatch": "Y",
                    "idNoMatch": "Y",
                    "idStateMatch": "Y",
                    "overallMatchScore": "100"
                },
                "AcctStatus": {
                    "primaryStatusCode": "099",
                    "primMessage": "Open Valid"
                },
                "Client": {
                    "clientDate": "2022-04-08",
                    "clientTime": "11:45:05",
                    "userDefined": "1234567890"
                }
            }
        }
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message that describes the type or source of the error.
TransactionIdoptional string The unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional string The universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
TransactionTimeoptional string The 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"
            }
        }
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message that describes the type or source of the error.
TransactionIdoptional string The unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional string The universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
TransactionTimeoptional string The 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"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message that describes the type or source of the error.
TransactionIdoptional string The unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional string The universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
TransactionTimeoptional string The 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"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message that describes the type or source of the error.
TransactionIdoptional string The unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional string The universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
TransactionTimeoptional string The 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"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message that describes the type or source of the error.
TransactionIdoptional string The unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional string The universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
TransactionTimeoptional string The 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"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message that describes the type or source of the error.
TransactionIdoptional string The unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional string The universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
TransactionTimeoptional string The 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"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message that describes the type or source of the error.
TransactionIdoptional string The unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional string The universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
TransactionTimeoptional string The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occured in the service, please check with appplication support team before resubmitting the request",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message that describes the type or source of the error.
TransactionIdoptional string The unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional string The universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
TransactionTimeoptional string The 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 occured with the downstream service(Unexpected EOF at target), please check with appplication support team before resubmitting the request"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message that describes the type or source of the error.
TransactionIdoptional string The unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional string The universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
TransactionTimeoptional string The 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 appplication support before resubmitting the request."
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message that describes the type or source of the error.
TransactionIdoptional string The unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional string The universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
TransactionTimeoptional string The 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"
    }
}

The idType field is a one-character code that represents the type of identification used to verify the account owner.

CODE DESCRIPTION
0 Driver's License USA
1 Military USA
2 Passport
3 Resident Alien ID
4 State identification
5 Student identification
6 Driver's License foreign
7 Driver's License Canada
8 Driver's License Mexico
9 Other primary ID foreign
A Matricula Consular card
B South American Cedula No.
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message that describes the type or source of the error.
TransactionIdoptional string The unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional string The universal ID to trace the transaction across all the systems involved. The ID is unique to each request.
TransactionTimeoptional string The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError
NAME TYPE DESCRIPTION
ConnectErroroptional string Error information about the connectivity with downstream service.
NAME TYPE DESCRIPTION
errorCodeoptional string The three-digit error code. Returns a "000" when no errors are present. See system error codes for more information.
NAME TYPE DESCRIPTION
accountValidationRequestoptional Object accountValidationRequest
NAME TYPE DESCRIPTION
Inquiryoptional Object 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.
additionalIdoptional string Additional client ID provided by KeyBank. This is only required if 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. The amount can be formatted as a whole dollar amount or with cents. This field cannot exceed 12 characters.
serialNumberoptional string Serial number of the check. Serial number does not apply to ACH inquiries.
AcctOwneroptional anyOf accountOwnerFirstLastName accountOwnerBusinessFirstName accountOwnerBusinessName accountOwnerBusinessLastName accountOwnerBusinessFirstLastName
Clientoptional Object client
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. This field cannot exceed 40 characters.
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. See idType for more information.
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 cannot exceed 6 characters.
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. See idType for more information.
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 cannot exceed 6 characters.
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. See idType for more information.
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 cannot exceed 6 characters.
NAME TYPE DESCRIPTION
firstNameoptional string First name of the account owner. Required with lastName if businessName is null.
lastNamerequired 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
businessNamerequired 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. See idType for more information.
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 cannot exceed 6 characters.
NAME TYPE DESCRIPTION
firstNamerequired string First name of the account owner. Required with lastName if businessName is null.
lastNamerequired 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
businessNamerequired 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. See idType for more information.
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 cannot exceed 6 characters.
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.
NAME TYPE DESCRIPTION
errorCodeoptional string The three-digit error code. Returns a "000" when no errors are present. See system error codes for more information.
systemRecordIdoptional string The unique, system-generated transaction ID.
primaryIdoptional string The primary client ID returned via a KeyBank lookup.
secondaryIdoptional string The secondary client ID provided in the original request.
additionalIdoptional string The additional client ID, if provided in the original request.
routingNumberoptional string The nine-digit routing number for the account provided in the original request.
accountNumberoptional string The full bank account number provided in the original request.
feeAttriboptional string The two-character code that represents how a transaction took place. Currently, the only value reported is "HH", which represents an ACH transaction.
amountoptional string The amount of the transaction, if provided in the original request.
serialNumberoptional string The serial number of the check, if provided in the original request.
AcctOwneroptional Object accountOwnerResponse
AcctStatusoptional Object accountStatus
Clientoptional Object client
NAME TYPE DESCRIPTION
accountValidationResponseoptional Object accountValidationResponse
NAME TYPE DESCRIPTION
primaryStatusCodeoptional string The primary three-digit account status code. This is an informational response code that represents the status of an account. See account status codes for more information.
primMessageoptional string The message associated with the primary status code.

Depending on the service type configured, the accountOwnerResponse object can contain several fields that end in “Match”. Each of these match fields contains a single-character code that signifies whether or not an account owner element was found. See account owner field matching for more information.

NAME TYPE DESCRIPTION
conditionCodeoptional string The three-digit system response code that reflects the state of the account owner provided. See condition codes for more information.
nameMatchoptional string First name, middle name, and last name match status. Valid values: Y, N, C, or U.
firstNameMatchoptional string First name match status. Valid values: Y, N, or U.
lastNameMatchoptional string Last name match status. Valid values: Y, N, or U.
middleNameMatchoptional string Middle name or initial match status. Valid values: Y, N, or 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, C, or U.
addressMatchoptional string Combined address line one and two match status. Valid values: Y, N, C, or U.
cityMatchoptional string City match status. Valid values: Y, N, C, or U.
stateMatchoptional string State match status. Valid values: Y, N, or U.
zipCodeMatchoptional string ZIP code match status. Valid values: Y, N, C, or U.
homePhoneMatchoptional string Home phone number match status. Valid values: Y, N, C, or U.
workPhoneMatchoptional string Work phone number match status. Valid values: Y, N, C, or U.
ssnMatchoptional string SSN/TIN or last four digits of SSN match status. Valid values: Y, N, C, or U.
dobMatchoptional string Date of birth match status. Valid values: Y, N, C, or U.
idTypeMatchoptional string ID type match status. Valid values: Y, N, or U.
idNoMatchoptional string ID number match status. Valid values: Y, N, C, or U.
idStateMatchoptional string State or place of issuance match status. Valid values: Y, N, or 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.

An error can indicate a problem with the request, the network, or the API itself. Use the error handling information to get a better understanding of what went wrong and possible corrective actions.

An erroneous response returns the HTTP code number with the content of the exception schema. Additional information in this schema like the transaction ID and transaction time can help you diagnose the issue.

The schema includes the X-CorrelationId field to help with traceability.

When a problem occurs with the capture of the account information from a draftable account item or the evaluation of the request message fields, a 3-digit error code is provided in the response payload (errorCode). If no errors are present, this field is filled with three zeroes.

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

Condition codes reflect the state of the account owner data provided. When a condition code is returned in the response payload (conditionCode), users may still receive a partial response, such as an account status.

CONDITION CODE DESCRIPTION
000 Normal response - no system errors
300 Valid routing number, but not a participant
301 Valid participant, but not an account owner authentication contributor
302 Valid participant, but account owner authentication data is unavailable
304 No name field populated - first, last, or business name
396 No known information for the account number
900/901 No account owner response requested or provided

Account status codes are the specific account codes that may result from an account validation request and are returned in the response payload in the primaryStatusCode field.

STATUS CODE DESCRIPTION
000 Routing number/account number combination cannot be located
012 Account is closed
096 No positive or negative information is known about the account
099 Account is present in participant's master account file and contains no other status code

Depending on the service type configured, the accountOwnerResponse object can contain several fields that end in “Match”. Each of these match fields contains a single-character code that signifies whether or not an account owner element was found.

CODE DESCRIPTION
Y Close or exact match
C Conditional match
N No match
U No identifying data is available

For all fields the following response rules apply:

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

  • Account matching will be performed only if a request contains:

    • First name and last name, and/or

    • Business name

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

The following are ignored:

  • Case

  • Spacing

  • Punctuation

"C"onditional (partial) match responses are applicable to the following fields:

  • Full name (firstName + middleName + lastName)

  • Business names

  • Street address (addressLine1 + addressLine2)

  • City

  • ZIP (first five digits)

  • Home phone

  • Work phone

  • SSN (if nine digits are provided)

  • DOB

  • ID number

Only Y/N matches are applicable to the following fields:

  • First name

  • Last name

  • Middle name or initial

  • State

  • SSN (if last four digits are provided)

  • ID type

  • ID state

YAML file