Account Validation | API Documentation

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

Before you begin

All KeyBank APIs require certificates, user credentials, and certain permissions. Before you begin, see Key concepts to learn more about these fundamental elements as well as other recommended best practices.

API-specific requirements

Secondary and additional IDs

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.

Account Validation API Endpoints

Summary	Endpoint
Verify an account	post /accounts/validations/v1/verifyAccount

Verify an account

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.

When submitting a request, it is recommended that you use the first and last name of the account owner or the business name, but not both.

Request

header FIELD	TYPE	DESCRIPTION
X-CorrelationIdoptional	string	A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.

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

Responses

Successful response

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

Missing data

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Please make sure your request is correct and try again.",
    "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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Please make sure you're using the correct credentials. Then log in again.",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Access denied

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
    "ErrorMessage": "You don't have access to this resource. Contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
    "ErrorMessage": "We can't seem to find what you're looking for. Please verify the resource and try again.",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Media type not supported

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
    "ErrorMessage": "We currently don't support that format. Please check the format type defined in your request and try again. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Too many requests

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
    "ErrorMessage": "Looks like you've sent too many requests. Please wait a moment and try again later.",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Internal server 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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
    "ErrorMessage": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "A connectivity error occurred with the downstream service (unexpected end of file at the target). Please check with your KeyBank Client Success Manager or email developers@keybank.com before trying the request again."
    }
}

Service unavailable

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Looks like something went wrong. Please try again later. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "This service is currently unavailable (there are no active targets). Please check with your KeyBank Client Success Manager or email developers@keybank.com before trying the request again."
    }
}

Gateway 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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
    "ErrorMessage": "Your request took too long to process. Please try again. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "The request could not be processed on time (gateway timeout). Please wait a moment and try again later."
    }
}

Schemas

accountOwnerBusinessFirstName

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 cannot exceed 6 characters.

accountOwnerBusinessFirstLastName

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

accountOwnerBusinessLastName

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

accountOwnerBusinessName

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 cannot exceed 6 characters.

accountOwnerFirstLastName

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

accountOwnerResponse

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, C, 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, C, U
addressMatchoptional	string	Combined address line one and two match status. Valid values: Y, N, C, U
cityMatchoptional	string	City match status. Valid values: Y, N, C, U
stateMatchoptional	string	State match status. Valid values: Y, N, U
zipCodeMatchoptional	string	ZIP code match status. Valid values: Y, N, C, U
homePhoneMatchoptional	string	Home phone number match status. Valid values: Y, N, C, U
workPhoneMatchoptional	string	Work phone number match status. Valid values: Y, N, C, U
ssnMatchoptional	string	SSN/TIN or last four digits of SSN match status. Valid values: Y, N, C, U
dobMatchoptional	string	Date of birth match status. Valid values: Y, N, C, U
idTypeMatchoptional	string	ID type match status. Valid values: Y, N, U
idNoMatchoptional	string	ID number match status. Valid values: Y, N, C, 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

accountStatus

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.

accountValidationRequest

NAME	TYPE	DESCRIPTION
Inquiryoptional	Object	inquiry

accountValidationResponse

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.
secondaryIdoptional	string	Secondary client ID provided in the original request.
additionalIdoptional	string	Additional client ID, if provided in the original request.
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.
serialNumberoptional	string	Serial number of the check, if provided in the original request.
AcctOwneroptional	Object	accountOwnerResponse
AcctStatusoptional	Object	accountStatus
Clientoptional	Object	client

aoaVerifyAccountRequest

NAME	TYPE	DESCRIPTION
accountValidationRequestoptional	Object	accountValidationRequest

aoaVerifyAccountResponse

NAME	TYPE	DESCRIPTION
accountValidationResponseoptional	Object	accountValidationResponse

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.

connectError

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

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

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

serviceErrorData

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

Service-level information

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

Account-level information

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

Account status codes

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

Account owner field matching

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