Developer Portal Terms of Service

4-minute read 0 | updated Sep. 14, 2024

Please read these Developer Portal Terms of Service (the “Agreement”) carefully. This Agreement is between you and KeyBank National Association (“Bank” or “Key”) concerning your access and use of the developer portal service (“Service”) for the Permitted Purpose (as defined below).

Any reference to “you” or “your” in this Agreement will refer to both the individual using the Service and to any Organization represented by such individual, whether such individual is an employee, agent, independent contractor, representative, or other similarly affiliated party. You and Bank are each referred to individually as a “Party” and collectively as the “Parties.”

If you are an individual accessing or using the Service on behalf of, or for the benefit of, any corporation, partnership, or other entity with which you are associated (an “Organization”), then you are agreeing to this Agreement on behalf of both yourself and such Organization. Access to and use of this Service is limited to the individual Party signing this Agreement. A Party may not transfer access to another individual and the sharing of Login Credentials is strictly prohibited. A fully executed Agreement is required for every individual to access and use the Service.

01 DEFINITIONS

"Applicable Laws” means all laws, rules, and regulations of any country, state, municipality or other political entity applicable to the Service, including without limitation: any and all Sanctions, including the Cyber-Related Sanctions Regulations (31 CFR §578); the Export Administration Regulations (15 CFR Part 730, et seq.); Title V of the federal Gramm-Leach-Bliley Act; the federal Economic Espionage Act; The Foreign Corrupt Practices Act of 1977, as amended (15 USC §78dd-1, et seq.); and the Bank Bribery Act (18 USC §215).

"Documentation" means any technical documentation or other instructions provided or made available to you by Bank regarding the proper use of the Service.

"Login Credentials"" means the unique username and password that you create for access to the Service.

“Permitted Purpose” means review Application Programming Interface (“API”) documentation and guides, API simulations testing, downloading YAML content, subscribing to notifications, and key/certification management for the purpose of an integration with KeyBank to use its products and services.

“Sanctioned Person” means any person: (a) that is the subject or target of any Sanctions; (b) located, organized, operating or resident in a country, territory or geographical region which is itself the subject or target of any Sanctions that comprehensively prohibit dealings with that country, territory, or geographical region, or (c) owned or controlled by any such person or persons described in the foregoing clauses (a) or (b).

“Sanctions” means economic or financial sanctions, requirements or trade embargoes imposed, administered or enforced from time to time by: (a) the United States of America, including, but not limited to, those administered by the U.S. Department of the Treasury’s Office of Foreign Assets Control, the U.S. Department of State or the U.S. Department of Commerce; (b) the United Nations Security Council; (c) the European Union; (d) Her Majesty’s Treasury of the United Kingdom; or (e) any other relevant governmental authority.

02 LICENSE

Subject to your compliance with the Agreement, Bank hereby grants to you a limited, non-exclusive, non-assignable, and non-transferable license to access and use the Service solely in accordance with the Documentation and for the Permitted Purpose.

03 RESTRICTIONS

You will not, and will not allow any third party to, directly or indirectly: (a) disclose, distribute, make available, sell, lease, or otherwise allow any third party to access or use the Service; (b) access or use the Service for any purpose other than the Permitted Purpose; (c) decompile, reverse engineer, reverse assemble, or otherwise attempt to discover any source code of the Service; (d) copy, mirror, frame, modify, or create derivative works based on the Service; (e) access the Service in order to build a competitive product or service, or copy any features, functions or graphics of the Service; (f) use the Service to store or transmit material in violation of any third party rights or Applicable Law; (g) use the Service to transmit any viruses, malware, or other malicious code; (h) interfere with, disrupt the integrity or performance of, or attempt to gain unauthorized access to the Service or any related systems or networks, including by exceeding any applicable limitations on transactions per second implemented by Bank; or (i) access, or allow access to, the Service beyond the United States (except with Bank's prior written approval). Breach of this Section 3 may result in the throttling, suspension, or termination of your account as more fully described in Section 15 herein.

04 REGISTRATION/LOGIN CREDENTIALS

You will be required to register and create Login Credentials to use all or part of the Service. Bank may reject, or require that you change any username, password, or other information that you provide to Bank in registering. Login Credentials are for the personal use of the individual to whom they are assigned only and should be kept confidential. You, and not Bank, are responsible for any use or misuse of your Login Credentials, and you must promptly notify Bank of any confidentiality breach or unauthorized use of your Login Credentials or your account.

05 MODIFICATIONS

Bank may, from time to time in its sole discretion, modify or update the Service in connection with its ongoing delivery of the programs and related features and functionality under the Agreement by notifying you of such modifications or updates by any reasonable means. Such changes will apply across Bank's relevant user base, and you acknowledge that any such modifications or updates may require you to undertake certain integration or implementation efforts.

06 CONFIDENTIALITY AND OWNERSHIP

6.1 Confidentiality

“Confidential Information” means the Service, Documentation, any and all information and data that is accessed through the Service or through the exercise of your rights and licenses under the Agreement, and other sensitive or proprietary information that is reasonably understood, given the nature of the information or circumstance, to be confidential, in each case whether orally or in written, electronic, or other form or media, and whether or not marked, designated, or otherwise identified as "confidential". You will: (a) protect and safeguard the confidentiality of Bank's Confidential Information with at least the same degree of care as you would protect your own Confidential Information, but in no event with less than a commercially reasonable degree of care; (b) not use Bank's Confidential Information, or permit it to be accessed or used, for any purpose other than to exercise your rights or perform your obligations under the Agreement; and (c) not disclose any such Confidential Information to any person or entity, except to your representatives who need to know the Confidential Information to assist you or act on your behalf. You will be responsible for any breach of this section caused by any of your representatives. At Bank's request, you will promptly return, and will require your representatives to return, to Bank all copies of Bank's Confidential Information, or, upon Bank's request, destroy all such copies and certify in writing to Bank that such Confidential Information has been destroyed. In addition to all other remedies available at law, Bank may seek equitable relief (including injunctive relief) against you and your representatives to prevent the breach or threatened breach of this section and to secure its enforcement.

6.2 Intellectual Property

07 PRIVACY AND SECURITY

Bank understands the need to safeguard your information and records from unauthorized use and disclosure. Please see the KeyCorp Privacy Policy and Security Disclosures posted on www.key.com.

08 CROSS BORDER TRANSMISSION OF DATA

You acknowledge and agree that by providing Bank with your personal or proprietary information in any application or transaction request through the Service, you hereby consent to the transmission of such personal or proprietary information to or by Bank, and its service providers or marketers, over state and international borders as necessary for handling your application or transaction request in accordance with Bank's standard business practices, subject to Bank's Privacy Policy.

09 ILLEGAL, FRAUDULENT, OR IMPROPER ACTIVITY

You will not use the Service, or any financial service or product provided by Bank, for any illegal, fraudulent, unauthorized, or improper activity (a "Prohibited Use"). If Bank suspects that you may be engaging in any Prohibited Use, including any violation of any terms or conditions relating to this Service or any financial service or product provided by Bank, your access to the Service and any financial service or product may be suspended or terminated without notice. Also, access to the Service may be suspended or terminated if any access device or code has been reported lost or stolen, or you do not follow Bank’s applicable security procedures, or when Bank reasonably believes that there is unusual activity on any of your financial accounts with us. You agree to cooperate fully with Bank to investigate any suspected Prohibited Activity or unauthorized use.

10 INDEMNIFICATION

You covenant and agree to indemnify, defend, and hold harmless Bank, its subsidiaries and affiliates, and their respective officers, directors, employees, agents, and permitted assigns (collectively, the "Indemnitees"), as such, against any and all losses, liabilities, fines, penalties or expenses (including reasonable attorney's fees and expenses) arising from any third-party legal action, claim, demand, or proceedings brought against any of the Indemnitees arising from or related to: (a) any breach of any of the provisions of the Agreement; (b) any use of the Service in violation of Applicable Law or the Agreement; (c) any modification of the Service other than at Bank's express direction or instruction; or (d) any combination of the Service with any third party hardware, software, or other materials or information not provided by, or performed at the express direction, approval, or instruction of, Bank.

11 DISCLAIMER

Bank provides the service on an "as is" and "as available" basis, without any warranties (express, implied, or statutory) including any warranties of fitness ofr a particular purpose, merchantability, title, or non-infringement. Bank does not guarantee that the service or the data provided by use of the service will be uninterrupted, continuously available, accurate, complete, or error-free. Your use or reliance on the service is at your own risk.

12 LIMITATION OF LIABILITY

In no event shall Bank of any of Bank's vendors be liable for any damages, including any incidental, consequential, special, direct or indirect damages, losses, or expenses arising in connection with the service or any linked website, user thereof or inability to use, by any party or in connection with any failure of performance, error, omission, interruption, defect, delay in operation, or transmission, computer virus, or line or system failure, including any loss data, even if Bank or its representative thereof, is advised of the possibility of such damages, losses or expenses, except as limited by applicable law. Some states do not allow the exclusion or limitation of incidental or consequential damages, so the above may not apply to you.

13 AVAILABILITY

The Service is not intended for distribution to, or use by, any person or entity in any jurisdiction or country where such distribution or use would be contrary to Applicable Law or regulation. Bank will restrict the availability of the Service during the time when you are in the following countries: Cuba, Iran, Liberia, Myanmar/Burma, North Korea, Sudan, and Syria in order to facilitate Bank's compliance with the U.S. laws administered by the Office of Foreign Assets Control.

14 CHANGES TO AGREEMENT

Bank reserves the right to modify this Agreement at any time without notice, but the most current version of the Agreement will always be available to you by clicking on the link at the bottom of the Developer Portal website. If you find the Agreement unacceptable at any time, you may discontinue your use of the Service, but such Agreement shall survive such discontinuation with respect to activity occurring prior to such discontinuation. By continuing to use the Service after the date of any change of the Agreement, including accessing the Developer Portal website, you agree to be bound by the provisions contained in the most recent version of the Agreement.

15 TERM/TERMINATION

15.1 Term

The Term of this Agreement commences on the date in which you checked the box marked “Accept” in connection with the Service or the date in which you first used the Service, whichever is earlier, and continues in effect until terminated in accordance with the provisions of the Agreement (the “Term”).

15.2 Termination

Either Party may terminate this Agreement at any time for any reason or no reason upon written notice to the other Party.

Bank may throttle or otherwise restrict your use of the Service or suspend your account and/or your access to the Service, if Bank reasonably believes: (i) you have materially breached this Agreement; (ii) the Service is experiencing technical problems; or (iii) such suspension is necessary to protect the rights or property of the Parties or applicable third parties or to comply with Applicable Law.

15.3 Effects Of Termination

Upon any termination of this Agreement (i) all licenses granted to you hereunder will end, (ii) you must cease any access and use of the Service; and Bank may, without liability to you or any third party, immediately deactivate or delete your username, password, and account, and all associated materials, without any obligation to provide any further access to such materials.

Sections 1, 3, 5, 6, 10, 11, 12, 13, 15, 16, 17, 18, 19, and 20 of this Agreement will survive the expiration or termination hereof.

16 APPLICABLE LAW/FORUM

The terms of this Agreement shall be governed by the statutes and laws of the State of Ohio, and the federal laws of the U.S.A., without regard to the conflicts of laws principles thereof. The application of the United Nations Convention of Contracts for the International Sale of Goods, and the model Uniform Computer Information Transactions Act approved by the National Conference of Commissioners on Uniform State Laws (as enacted and/or modified into any state law in the U.S.A.), are expressly excluded and shall not apply.

17 ARBITRATION

The terms and conditions of Key's Arbitration Provision posted on key.com is incorporated into and made a part of this Agreement.

18 ENFORCEABILITY

In the event any of the provisions of this Agreement shall be held to be unenforceable, the remaining provisions shall be unimpaired, and the unenforceable provision shall be replaced by such enforceable term or provision as comes closest to the intention underlying the unenforceable term or provision. This Agreement shall be subject to any other agreements you have entered into with Bank.

19 ELECTRONIC COMMUNICATIONS

To the fullest extent permitted by Applicable Law, this Agreement and any other agreements, notices, disclosures, messages or alerts, or other communications regarding the Service (collectively referred to as "Communications"), may be provided to you electronically and you agree to receive Communications in an electronic form. Electronic Communications may be posted on the pages within the Developer Portal website and/or delivered to your e-mail address on record with us. You will print a paper copy of any electronic Communication and retain it for your records. All electronic Communications will be considered to be "in writing," and to have been received and effective upon posting on the Developer Portal website or dissemination to your email address, whether or not you have retrieved or read the electronic Communication. Bank reserves the right to provide Communications in paper format. Your consent to receive Communications electronically is valid until you revoke your consent by notifying Bank by a paper writing of your decision to do so. If you revoke your consent to receive Communications electronically, Bank may terminate your right to use the Service.

20 COMPLICANCE WITH SANCTIONS REGULATIONS

You represent, warrant and covenant that neither you, nor any of the agents, subcontractors, or employees of the associated Organization under this Agreement is (i) an individual or entity that is listed in the annex to, or is otherwise subject to the prohibitions contained in, Executive Order No. 13224 on Terrorist Financing, effective September 24, 2001 (“Executive Order”) of the Office of Foreign Asset Control (“OFAC”) regulations; (ii) an individual or entity with whom Key or any financial institution is prohibited from dealing or otherwise engaging in business under any United States law, regulation, executive order (including, without limitation, the Executive Order, Section 19 of the Federal Deposit Insurance Act) or list published by OFAC; (iii) an individual or entity that is named on the current “Specially Designated Nationals and Blocked Persons List” and “Consolidated Non-SDN List” published by OFAC on its official website or any replacement website or other replacement official publication of such list; (iii) or otherwise a Sanctioned Person; or (iv) an individual prevented from providing Services to Key pursuant to background check. You are not, directly or indirectly, owned or controlled by or under common ownership or control with a Sanctioned Person.

21 MISCELLANEOUS

21.1 Monitoring

Bank may (but have no obligation to) monitor or analyze your access to or use of the Service. Bank may disclose information regarding your access to and use of the Service, and the circumstances surrounding such access and use, to anyone for any reason or purpose.

21.2 Force Majeure

Bank will not be liable to you for failure or delay in performing its obligations under the Agreement if such failure or delay is due to acts of any governmental body, war, insurrection, sabotage, or embargo; fire, flood or other Act of God; strike or other labor disturbance; interruption of or delay in transportation; unavailability of, interruption of or delay in telecommunications or third party services; epidemic, pandemic or other spread of disease; inability to obtain raw materials, supplies or power used in or equipment needed for performance of its obligations; or any other cause beyond Bank's reasonable control.

21.3 Relationship Of Parties

This Agreement does not, and will not be construed to, create any partnership, joint venture, employer-employee, agency, or franchisor-franchisee relationship between you and Bank.

21.4 Assignment and No Third-Party Beneficiaries

You may not assign or transfer any or all of your rights or obligations under this Agreement without Bank's express prior written consent. Bank may assign or transfer any or all of its rights or obligations under this Agreement without restriction. Any purported assignments, transfers, or delegations in violation of this section will be null and void. Nothing in this Agreement will confer any rights upon any person other than the Parties hereto and their respective heirs, successors, and permitted assigns.

21.5 Interpretation

For purposes of interpreting this Agreement, unless otherwise specifically stated, (a) the singular includes the plural, and the plural includes the singular; (b) the words "herein," "hereof," and "hereunder" and other words of similar import refer to this Agreement as a whole and not to any particular section or paragraph; (c) the words "include" and "including" will not be construed as terms of limitation, and will therefore mean "including but not limited to" and "including without limitation"; (d) the words "writing" or "written" mean preserved or presented in retrievable or reproducible form, whether electronic (including email but excluding voice mail) or hard copy; (e) the captions and section and paragraph headings used in this Agreement are inserted for convenience only and will not affect the meaning or interpretation of this Agreement; and (f) the references herein to the Parties will refer to their permitted successors and assigns..

21.6 Entire Agreement and Waiver

This Agreement is the final and complete expression of the agreement between the Parties regarding the subject matter of this Agreement. This Agreement supersedes, and the terms of this Agreement govern, all previous oral and written communications regarding these matters, all of which are merged into this Agreement. No waiver of this Agreement will be binding unless in writing and executed by Bank.

By checking the box marked “Accept” in connection with the Service, or by using the Service, you agree to the terms of the Agreement as indicated above.

Account Validation v2

4-minute read 2.0.0 | updated Aug. 07, 2024

Validate an account and its owner with confidence

Account Validation v2 API Endpoints

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

Before you begin

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

Overview

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

Make a request

When you submit a request to the Account Validation API, the data in that request is compared to information in the National Shared Database. The National Shared Database is the financial industry's leading source of up-to-date, collaborative financial data. Results from the database comparison are evaluated and then returns a response to you in real time, verifying the account owner status quickly.

Request requirements

When you submit a request, in addition to your authentication credentials, you must provide:

The account number of the person or business you want to validate. (accountNumber)
The routing number for the financial institution of the person or business. (routingNumber)
Set the validation type to Owner to request for owner status and validation. (serviceType).
An ID provided during KeyBank onboarding that is a secondary authentication method for the call besides the access token. This is not the same as your client or consumer ID. (secondaryId)

Interpret the response

Results from the database comparison are evaluated and then returns a response to you in real time, verifying the account owner status quickly. The following response rules apply for all fields:

All fields included in the request will be matched against the database.
Case, spacing, and punctuation are ignored.
The account data matched in the database is determined based on the account number (accountNumber) and routing number (routingNumber) in the request.
Account matching will be performed only if a request contains the person's full name (firstName and lastName) OR the name of the business (businessName).

Result codes

Account Validation responses include a variety of codes and classifications to help you assess if the account is legitimate or not. Refer to the Account Validation User Guide to help decipher codes like these:

errorCode: Three-digit code about system errors. If there are no errors, you receive three zeros (000).
conditionCode: Three-digit code about the state and validity of account ownership.
primaryStatusCode: Three-digit code for account status.
accountOwnerResponse object: Account owner field matching showing a Y (Yes), N (No), C (Conditional), or U (Unknown).

Loads of codes

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

Health check

get /accounts/validations/v2/healthCheck

Request

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

Request example

curl -k -X GET http://{host}/accounts/validations/v2/healthCheck

Responses

Successful response

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

Response example (200)

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

Verify an account

post /accounts/validations/v2/verifyAccount

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

Request

BODY FIELD	TYPE	DESCRIPTION
accountValidationV2Requestrequired	Object	accountValidationV2Request

Request example

{
    "accountValidationV2Request": {
        "AOARequest": {
            "Inquiry": {
                "serviceType": "Owner",
                "secondaryId": "KeyCli03",
                "additionalId": "AddCli04",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "amount": "110.99",
                "serialNumber": "",
                "AcctOwner": {
                    "firstName": "Paul",
                    "lastName": "wilson",
                    "middleName": "Dan",
                    "namePrefix": "Mr",
                    "nameSuffix": "Lal",
                    "businessName": "",
                    "addressLine1": "206 GOODWIN ST",
                    "addressLine2": "Land",
                    "city": "MERRIT",
                    "state": "MI",
                    "zipCode": "49667",
                    "homePhone": "3077553623",
                    "workPhone": "3077555330",
                    "ssn": "666082367",
                    "dob": "19730801",
                    "idType": "2",
                    "idNo": "590909812",
                    "idState": "AL"
                },
                "Client": {
                    "clientDate": "2022-12-31",
                    "clientTime": "14:00:80",
                    "userDefined": ""
                }
            }
        }
    }
}

Responses

OK

NAME	TYPE	DESCRIPTION
accountValidationV2Responserequired	Object	accountValidationV2Response

Response example (200)

{
    "accountValidationV2Response": {
        "AOAResponse": {
            "Result": {
                "errorCode": "000",
                "systemRecordId": "8168140724120284",
                "primaryId": "TROM122101",
                "secondaryId": "KeyCli01",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "feeAttrib": "HH",
                "AcctOwner": {
                    "conditionCode": "000",
                    "addressMatch": "Y",
                    "cityMatch": "Y",
                    "stateMatch": "Y",
                    "zipCodeMatch": "Y",
                    "ssnMatch": "Y",
                    "overallMatchScore": "100"
                },
                "AcctStatus": {
                    "primaryStatusCode": "099",
                    "primMessage": "Open Valid"
                },
                "Client": {
                    "clientDate": "2022-12-31",
                    "clientTime": "14:00:80",
                    "userDefined": ""
                }
            }
        }
    }
}

Missing mandatory information

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

Response example (400)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "abcgd133",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "AOAResponse": {
            "Result": {
                "errorCode": "104"
            }
        }
    }
}

Unauthorized request

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

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

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

Response example (403)

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

Resource not found

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

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

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

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

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

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

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

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

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

Response example (502)

{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Unavailable service

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

Response example (503)

{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

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

Response example (504)

{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Request could not be processed on time (GatewayTimeout), please wait a moment and resubmit the request"
    }
}

Schemas

healthResponse

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

exception

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

connectError

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

serviceErrorData

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

accountValidationV2Request

NAME	TYPE	DESCRIPTION
AOARequestoptional	Object	AOARequest

Inquiry

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

AOARequest

NAME	TYPE	DESCRIPTION
Inquiryoptional	Object	Inquiry

AOAResponse

NAME	TYPE	DESCRIPTION
Resultoptional	Object	Result

errorResponse

NAME	TYPE	DESCRIPTION
businessFaultoptional	Object	businessFault
systemFaultoptional	Object	systemFault

AcctOwner_1

NAME	TYPE	DESCRIPTION
conditionCodeoptional	string	Three-digit system response code that reflects the state of the account owner provided.
nameMatchoptional	string	First name, middle name, and last name match status. Valid values: Y, N, U
firstNameMatchoptional	string	First name match status. Valid values: Y, N, U
lastNameMatchoptional	string	Last name match status. Valid values: Y, N, U
middleNameMatchoptional	string	Middle name or initial match status. Valid values: Y, N, U
namePrefixMatchoptional	string	Name prefix match status. U will always be returned for a name prefix if included in the request.
nameSuffixMatchoptional	string	Name suffix match status. U will always be returned for a name suffix if included in the request.
businessNameMatchoptional	string	Business name match status. Valid values: Y, N, U
addressMatchoptional	string	Combined address line one and two match status. Valid values: Y, N, U
cityMatchoptional	string	City match status. Valid values: Y, N, U
stateMatchoptional	string	State match status. Valid values: Y, N, U
zipCodeMatchoptional	string	ZIP code match status. Valid values: Y, N, U
homePhoneMatchoptional	string	Home phone number match status. Valid values: Y, N, U
workPhoneMatchoptional	string	Work phone number match status. Valid values: Y, N, U
ssnMatchoptional	string	SSN/TIN or last four digits of SSN match status. If you are a merchant provider, the value returned will always be 'U'. Valid values: Y, N, U
dobMatchoptional	string	Date of birth match status. Valid values: Y, N, U
idTypeMatchoptional	string	ID type match status. Valid values: Y, N, U
idNoMatchoptional	string	ID number match status. Valid values: Y, N, U
idStateMatchoptional	string	State or place of issuance match status. Valid values: Y, N, U
overallMatchScoreoptional	string	The measure of how closely the inquiry request attributes match the actual account ownership data. This number is calculated based on the analysis of all information sent. Valid values: 0-100

Result

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

systemFault

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

AcctStatus

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

accountValidation_POST_bodyParameters

NAME	TYPE	DESCRIPTION
accountValidationV2Requestrequired	Object	accountValidationV2Request

businessFault

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

Client

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

accountValidation_POST_response

NAME	TYPE	DESCRIPTION
accountValidationV2Responserequired	Object	accountValidationV2Response

accountValidationV2Response

NAME	TYPE	DESCRIPTION
AOAResponseoptional	Object	AOAResponse
errorResponserequired	Object	errorResponse

Client_1

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

AcctOwner

NAME	TYPE	DESCRIPTION
firstNameoptional	string	First name of the account owner. Required with lastName if businessName is null.
lastNameoptional	string	Last name of the account owner. Required with firstName if businessName is null.
middleNameoptional	string	Middle name of the account owner.
namePrefixoptional	string	Optional name prefix of the account owner. This field cannot exceed four characters. Example: Dr., Mr., Mrs.
nameSuffixoptional	string	Optional name suffix of the account owner. This field cannot exceed four characters. Example: Jr., PhD
businessNameoptional	string	Business name that owns the account. Required if lastName is null.
addressLine1optional	string	First line of the address on the account. This field cannot exceed 40 characters.
addressLine2optional	string	Second line of the address on the account.
cityoptional	string	City on the account.
stateoptional	string	Two-character state abbreviation on the account.
zipCodeoptional	string	ZIP code on the account. This can either be five digits or nine digits. If a nine-digit ZIP code is provided, a dash between the groups of digits is acceptable. Do not use a space.
homePhoneoptional	string	10-digit home phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
workPhoneoptional	string	10-digit work phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
ssnoptional	string	Full social security/tax ID number or the last four digits of the social security number of the account owner.
doboptional	string	Date of birth for the individual on the account. Format: YYYYMMDD
idTypeoptional	string	One-character [code that represents the type of identification used to verify the account owner.
idNooptional	string	ID number for the account owner's form of identification. This field cannot exceed 28 characters.
idStateoptional	string	Two-character state of issuance for the account owner's form of identification. If not a US state, enter the place of issuance. This field must be between 2-6 characters in length.

Errors

For more information about errors, see Error handling.

System error codes

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

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

YAML file

Account Validation

2-minute read v2, v1 | updated Sep. 15, 2024

Temporarily, there are two operating versions of the Account Validation API with v2 being the most current and v1 about to deprecate.

What changes are in v2?

This latest version includes security and request schema enhancement to help deliver more meaningful responses.

Enabled OAS validation for required request parameters.
- Going forward, the serviceType must be set to 'Owner' to be a valid request.
- Search for the account owner information by full name (firstName and lastName) OR by business name (businessName).
Condensed 5 similar schemas into one simple request object, AcctOwner.
Error responses built out for better clarification about the status of the results.

Learn more

Read our user guide to get a better idea of what to expect with our Account Validation API, how to make a quality inquiry, and interpret the response.

Latest v2 specifications

Account Validation API v2 includes validation enhancements as well as an improved and simplified search logic for account owner verification. Use this version or upgrade to v2 to take advantage of these changes.

Deprecating v1 specifications

Account Validation API v1 has the original search criteria schemas without enforced account owner validation. If you are an existing client, we encourage you to upgrade to v2.

Release notes

3-minute read 3.1.0 | updated Aug. 07, 2024

KeyBank will post release notes to this page for every minor and major portal release. Release notes summarize breaking and non-breaking changes made to the API product and/or the API developer portal.

The developer portal release notes are organized by month and year of the release, starting with the most current. Each release also identifies the level of impact for the changes made. This is a quick cue to know if you need to make any necessary changes immediately or if you can integrate the API enhancements at your own pace.

August 2024

MID IMPACT

Introduction of the Account Validation API v2.
Enhancements to the Account Validation API User Guide that includes information about version 2 of the API with greater clarity about significant parameters that can help improve your validation process.
ACH Inquiry API has retired the following endpoints:
- /accounts/transactions/v1/ACHStatusInquiry/list
- /accounts/transaction/v1/collectedACHtransactions/list
- /accounts/transactions/v1/postedACHtransactions/list
- /accounts/transactions/v1/returnACHtransactions/list
Webhooks ACH alert code consolidated to a single value AL00906.
Data values now has the full list of all Wire/RTP webhook statuses including intermittent statuses and account validation ID types.
Sign up has been postponed for the time being as we develop our authenticated portal. If you are interested in using an Embedded Banking API product, please go to the EB Payments Advisor Contact Form.

May 2024

LOW IMPACT

X-CorrelationId has been removed as a request header field for all endpoints in each API product. 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 X-CorrelationId value in the response.
In the ACH Inquiry API, added two new endpoints. These endpoints will eventually replace the other status queries in the upcoming v2 of the API.
- /accounts/transactions/v1/ach/details/{parNumber}
- /accounts/transaction/v1/ach/list
Added the requestReference parameter to the getWireInquiryResult object in the Wire Inquiry API.
KeyVAM introduction on the dev portal home page and an summary guide on KeyVAM with links to learn more.
API Simulator product is now available for ACH API products endpoints (ACH Origination and ACH Inquiry). Speak to your Payments Advisor to learn more.

Change management

Levels of impact

Impact level	Description
Low	Non-breaking changes Small change requests to improve content like to better define a term or provide an example for added clarity.
Mid	May include breaking changes like adding or removing an API parameter. Code or configuration enhancement to an API in Production.
High	Breaking changes and/or a hot fix. New product being released.

Types of API changes

API product changes are changes made to the code or configuration of the API product or related services. This can include adding a schema, adding or remove parameters, modification of parameter type or function, etc.

Breaking changes require upgrading to a new version of the API framework. These changes can cause incompatibility and possibly disrupt your connection to API services. Some examples of breaking changes are a change to the type of a parameter, removing request fields, or developing an existing object with additional parameters.
Non-breaking changes are changes that do not require you to upgrade to a new version or disrupt your connection to current API services. Some examples of a non-breaking change are to add an optional parameter field like a custom data field or removing a deprecating parameter no longer valid or in use.

API specification versioning

The API version in the API specification file (YAML) is a three-number format that incrementally increase based on the significance of the change. All API specifications are initially released with the version 1.0.0.

There are three numbers for the major version, minor version, and patch number (X.X.X).

MAJOR	MINOR	PATCH
1.3.5	1.3.5	1.3.5
There is a significant release for code and functional changes. This includes breaking changes like developing new schemas, breaking existing integration points, removing attributes, changing a parameter type, etc.	A smaller release that include new operations and enhancements.	Small incremental, non-breaking changes that are often backend or related to technical content like minor improvements or grammatical edits/clarity. This can include hot fixes.

KeyVAM

clock 1-minute read calender 2.5.0 | updated May. 29, 2024

Make managing multiple accounts as easy as managing just one

Key takeaways

There are many benefits to virtual account management at KeyBank. With KeyVAM, you can:

Send and receive ACH, RTP, and Wire transactions on behalf of the parent account.
Instant opening and closed of sub-accounts for an individual or business.
View transaction and reconciliation data for each virtual sub-account while the total funds settle in one parent account with advance reporting.

Virtually amazing

Check it out yourself. There is a lot of great information on the Key Virtual Account Management site.

If you are ready to get started or have any questions, reach out to an Embedded Banking advisor.

What is VAM?

Key Virtual Account Management (KeyVAM) is an embedded service of the KeyNavigator platform. KeyVAM enhances how you manage money by linking a set of a set of virtual accounts (sub-accounts) to a single, physical account (parent). You can create and manage virtual sub-accounts in real-time. This is a great option if you need to open and close high-value virtual sub-accounts common in industries like technology, property management, or corporate cost centers.

KeyVAM APIs

Integrate your application with APIs. KeyVAM APIs are available to further develop your virtual account management experience with task automation for common activities like creating accounts, transferring funds, or reports. View the Key Virtual Account Management API Documentation to see what is possible.

Account Validation User Guide

clock 8-minute read calender 3.1.0 | updated Aug. 07, 2024

Get immediate confirmation of account ownership

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.

Custom data

3-minute read 2.4.0 | updated Apr. 24, 2024

Add data or tags specific to your application or use case

If you send or validate a payment with the ACH Origination API or the Wire Origination API, you can add information to the customData in the request payload.

Custom data is client-specific metadata that you can:

Use to append certain information or details
Use as an identifier to filter certain types of transactions

The customData information is not transmitted with the payment or stored in any KeyBank database. This information is only visible to you, the originator, with the ACH Inquiry API or the Wire Inquiry API. In the inquiry response, the customData field returns any custom values that were part of the payment request stored for recall after a successful ACH or wire transaction completes. This information is not visible to the recipient or any of the participating parties.

Here's how it works

Define the customData in the request payload. It is a free-form text field that can contain up to 500 alphanumeric characters that you can use however you like - for invoice number, product number, customer number, date/time stamp, etc.
KeyBank recommends the common custom data format of name-value pairs. You can list multiple name-value pairs in the custom data field within the 500-character limit. The custom data fields will return exactly what is sent; it does not parse name-value pairs within the API response. The custom data should not contain any personal identifiable information (PII).
Custom data examples
```
//Example of name:value pairs
"customData": "Type:DD; Status:Submitted; POnumber:12556"

//Example of regular text
"customData": "General products"

//Example of timestamp
"customData": "05-MAR-2023:12:19:53EST"
```
As the originator, you can use the ACH Inquiry API or Wire Inquiry API to retrieve the custom data information.
Review the response for the customData field.
- If there is custom data, it returns any custom values that were part of the payment request stored for recall after a successful ACH or wire transaction completes.
- If no custom data is defined, the response returns an empty field.

Available for these APIs

Error handling

5-minute read 2.4.0 | updated Mar. 13, 2024

Is it you? Is it me? Is it us? Let's figure it out.

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.

HTTP status codes

Each error response returns the standard HTTP code number with the exception schema. KeyBank utilized the standard HTTP messaging so nothing too fancy.

Code	Status	Description
200	OK; Successful	The action was successful. No additional actions are needed.
400	Missing mandatory information	Request is missing required information.
401	Unauthorized request	Invalid credentials for the request.
403	Forbidden request access	You do not have permission to complete the request.
404	Resource not found	The resource for the request cannot be found.
405	Invalid request method	The wrong request method was used.
415	Invalid request type	The wrong media type submitted with the request.
429	Request timeout	There are too many requests to the API and a timeout goes into effect.
500	Unknown error	There was an unknown error with the server.
502	Bad gateway	The servers cannot talk to each other or there is a miscommunication.
503	Unavailable service	The service is temporarily down.
504	Unable to process request	Request needs more time to be processed.

Standard error message format

The exception schema includes the error message, your unique X-CorrelationId, and additional information like TransactionId and TransactionTime. The transaction ID and timestamp are helpful in diagnosing the issue. The X-CorrelationId is helpful for transaction traceability and may help determine where did the error occurred.

The exception schema may also contain the ServiceError field for API-specific errors or problems with backend services. This object can contain a few different values, depending on the API or circumstance:

connectError - error information of the connectivity with downstream service.
detailMessage - an error code with a detailed message.
serviceErrorData - API-specific error details about the failed transaction.
variable field based on API - custom messages about API-related functional business messages or faults.

Standard error format

{
"ErrorMessage": string,
"X-CorrelationId": string,
"TransactionId": string,
"TransactionTime": string,
"ServiceError": object
}

Response header status messages

Some APIs contain status messages in the responseHeader object of the response payload. Review the status field to see if the transaction was successful (S), was successful but has a warning (W), or failed (F). Additional information is shared in the statusDescription field.

S: A successful response. (HTTP 200)
W: The transaction was not not processed as expected. A warning message means the request was successfully received, but there was a minor issue that requires your attention. (HTTP 299)
F: The transaction was not processed. (HTTP 400s/500s)

API-specific status messages are explained in depth on the API doc pages where applicable.

Status message example

{
                  "responseHeader": {
                     "status": "S",
                     "statusDescription": "Successfully returned results for the requested range 1 to 1",
                     "retrivedRows": "1",
                     "totalRows": "1",
                     "dataLoadDate": "2022-07-13"
                     },
                }

Pagination

2-minute read 2.4.0 | updated Apr. 24, 2024

It's a real page-turner

You can use pagination parameters to manage a response with large amounts of data. Adjusting these parameters can improve system performance. You can limit or parse data to prevent a lag or delay in a response. You can control how much information is returned in a response.

Pagination parameters are usually available on APIs that return lists of transactions like the ACH Inquiry API, Wire Inquiry API, Previous Day API, Intraday API, and RTP Send Payment API. There are several pagination parameters that can help you control how an endpoint will return the information requested.

Endpoints with Pagination

PAGINATION PARAMETER	API	ENDPOINT	REQUIRED OR OPTIONAL
`startRowIndex` `endRowIndex`	ACH Inquiry	POST /accounts/transactions/v1/returnACHtransactions/list POST /accounts/transactions/v1/collectedACHtransactions/list POST /accounts/transactions/v1/postedACHtransactions/list POST /accounts/transactions/v1/ACHStatusInquiry/list	Optional
`startRowIndex` `endRowIndex`	Wire Inquiry	POST /wireInquiry/v1/transactions/details	Optional
`startRowIndex` `endRowIndex`	Previous Day	POST /ddaReports/accounts/v1/transactions/list	Optional
`startRowIndex` `endRowIndex`	Intraday	POST /ddaReports/accounts/v1/transactions/intraday/list	Optional
`limit` `offset`	RTP Send Payment	GET /rtp/v1/payment/rtp/participant	Required

Common pagination controls

Row pagination

There are common pagination parameters like startRowIndex and endRowIndex that help retrieve and organize large data sets into separate, scrollable pages. This is commonly used with information reporting and transaction inquiry APIs. These are optional fields and not required for the request.

The startRowIndex query string parameter sets the first row of data of the response. The default value is 1.
The endRowIndex query string parameter sets the final row of data of the response. The default value is 1000 records and is also the maximum number of records allowed in a single transaction.
If the startRowIndex or endRowIndex parameters are blank, all the rows of data return up to the maximum limit of the endRowIndex value for transaction records.
In the response header of the API, an endpoint may return totalRows or retrievedRows. These parameters provide a summary of the total number of transactions that match the request criteria or were retrieved based on the request criteria.

Example

Here is an example of a request with general pagination parameters applied in the query string for the Previous Day API:

POST /ddaReports/accounts/v1/transactions/list?startRowIndex=1&endRowIndex=20

In this example, the startRowIndex is 5 so the first row of data is the fifth row, skipping the first four rows of data. The endRowIndex is 20 so that there is only 20 records per page following the fifth row.

Offset pagination

The offset pagination parameters are limit and offset. These parameters tell the server how many records to search for at a time and what records to skip. This parameter is not reliant on the sort controls and is not a recommended parameter for very large sets of data. Offset pagination is available with the RTP Send Payment API and is required for the RTP list of participants endpoint.

The limit is a query string parameter field that tells the server what items to return during a search. The limit restricts how many rows are returned. There is no maximum limit to this parameter.
The offset is a query string parameter field that specifies which set of rows to return. You can use this field to set the starting row for the data that is returned, and control what rows of data to skip. The default value is zero (0).
Be cautious when you use these parameters because if the data set changes it can affect the result and may return an incorrect response.

Example

Here is an example of a request with the offset pagination parameters applied in the query string for the RTP Send Payment API:

GET /rtp/v1/payment/rtp/participant?limit=15&offset=0

In this example, the offset is 0 so that no items are skipped, and the limit is 15 meaning the request will search 15 items at a time.

Getting Started Guide

clock 8-minute read calender 3.1.0 | updated Aug. 07, 2024

We've created this simple, user-friendly developer portal with you in mind. Here's a few good things to know first.

Key takeaways

TL;DR? We got you. Here are the highlights to this guide:

You need to be an authenticated and authorized user with our developer portal to use our APIs. To get started, see our overview of the onboarding process.
After you onboard, you get your own private API keys and can access our test environment.
Get an access token to connect to your APIs and start building.

Want in?

Contact a Payments Advisor to learn more about the KeyBank API developer portal and we'll have someone contact you with more information!
Contact us

Quick overview of the onboarding process

01 Contact and consult

If you are interested in a particular API product or a group of APIs, sign up for our waitlist. KeyBank will follow-up with you to help get you started.

To work with KeyBank APIs, there needs to be an established agreement between the service provider (KeyBank) and the client (you). This agreement details the API services you want, its services, and settings. It also gathers important system information needed for the KeyBank onboarding team to configure and secure the provisioned app.

02 Determine API needs

Determine which APIs are needed, define the frequency of use, and the transaction activity timeframe. Some APIs require specific configurations and may have a certain object to include in the call. Also, be mindful of our rate limiting.

For each API, provide the following information:

General details like transaction volume
Call frequency (number of calls per second, number of calls per minute, etc.)
Call timeframe (e.g., 24 hours a day or only during business hours)

The KeyBank onboarding team will reach out via email communication for additional details, if necessary.

03 Set up security

It is essential to have a secure connection before we start exchanging data, especially data as sensitive as financial data. For us to trust one another and verify that our pathways are safe, private, and guarded, we need to know your IP address and exchange certificates.

A digital certificate verifies your identity and keeps your data safe. Think of it like a virtual ID card for a website, or in this case the developer portal. When you connect to the site, the certificate legitimizes your identity. Then, when making API requests and transferring data on a cloud network, the certificate helps encrypt the data.

We use a mTLS authentication mechanism. This means when you request a mTLS certificate, you will get a public certificate chain and a private key. On your end, configure your application with the private key and certificate. You do not need to share your private key with KeyBank. After we exchange certificates, you will use the private key to encrypt the exchange and KeyBank uses the public certificate chain to verify it.

Certificate requirements:

Must have a CSR and private key. Do not share the private key.
Must include the root, intermediate, and leaf.
File format can be *.pem, *.crt, or *.cer.
Certificates cannot be self-signed.
Issued by a trusted certificate authority organization like DigiCert.
Only one certificate is required for all APIs.

04 Grant access

KeyBank sets up your account entitlements. Entitlements authenticate your identity and contain the authorization rules for the APIs you need to access. Part of the account entitlements are the API keys.

KeyBank shares the API keys needed to create an access token and make an API call.

KeyBank will set you up with a test environment to start and help you get a better idea of how the API functions and how it can integrate with your application. We share the environment details to you once setup is complete.

Common terms

Access token: A temporary token to that gives you permission to use the API. Use your API keys to generate the token. This is also known as a bearer token.
API consumer:: An authenticated developer portal user that has completed the onboarding process, has access to API services and possibly the KeyBank test environment.
API keys:: There are two sets of API keys that we privately share with you to authenticate and authorize your ability to use and access our API products. Can’t turn that engine without a key.
Authentication:: A method of identifying you and your application as a trusted and accepted source to exchange data. With authentication, we use your KeyBank client credentials (part of your API keys) to identify you.
Authorization:: A method of permitting access to certain APIs and services.
Certificates:: A digital exchange of several encrypted codes that verify your ability to connect with our API products safely, securely, and cautiously. These certificates typically expire annually.
CSR:: Certificate signing request is an encoded message that contains the information needed by the Certificate Authority (CA) to create your certificate. This can include your name, domain, organization information, or location.
Domain:: A human-readable name for an application or web address that identifies the name of the online application. Domain names are used to help set up web servers, communication, and other online services.
IP address:: The internet protocol address is a numerical label assigned to each device or application connected to the internet. Addresses can uniquely identify devices and route data to its intended destination.
mTLS:: Mutual Transport Layer Security is mechanism for the mutual authentication between the service provider and the client. No catfishing here. Digital certificates are exchanged and signed with the PKI framework.
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.
PKI:: A public key infrastructure is a system to create, store, and distributes digital certificates. This framework matches the public keys to digital entities to authenticate the identity of users, devices, and services.
Pre-production:: A test environment that allows you try the API product using sample data.
Production:: KeyBank’s live environment that exchanges real proprietary data between your application and our API products.
Service agreement:: A contract between KeyBank and financial businesses and applications that intend to use and integrate with KeyBank’s suite of APIs. The service agreement identifies the API products allowed, data volume, and other specifics require to ensure a proper configuration of services.

Using our APIs

Health checks

We recommend that you always start your API builds with a health check. To perform a health check, you must have valid certificates exchanged with KeyBank and API keys to request an access token.

Rate limiting

To ensure efficient and consistent API performance, we've placed a limit of 5 transactions per second (TPS) across all KeyBank APIs. API requests that exceed the rate limit receive an HTTP 429 response status code. If you've exceeded this limit, wait for at least 2 minutes before making another API call.

While we established the 5 TPS threshold to maximize stability and performance, we understand that your consumption needs might not fit within those limits. To request an increased rate limit, contact your KeyBank Client Success Manager.

X-CorrelationId

The X-CorrelationId is a unique 36-digit alphanumeric identification code generated automatically for each API transaction. This field helps support teams at KeyBank quickly track down an inquiry or issue. The ID stays with the transaction so we can trace the chain of API operations in the event logs. If you see different X-CorrelationId values for the same transaction, this could indicate that duplicate requests.

Request an access token

KeyBank requires an OAuth 2.0 access token to authorize API calls. To make a call for a token, you must have access to our environments, your certificates, private key, and API keys.

Copy and modify the cURL command template. Be sure to replace the curly brackets {{xxxx}} with your specific information.

For line 1, identify the certificates.
- For client.crt, enter the location of your certificate signing request (CSR). The file must be in one of these formats *.pem, *.crt, or *.cer.
- For client.key, enter the name of your certificate’s private key file.
- For ca.crt, enter the name of your certificate authority (CA) certificate.
For line 2, identify the host. Enter the URL address for the KeyBank environment. Make sure to add scope=rs-read as a path parameter in the URL.
For line 3, enter your application credentials (consumer_key and consumer_secret) API keys in Base64 encoded format. Use a trusted site to generate an encoded string for your consumer key and secret.
For line 6, enter your client credentials from KeyBank. For client id enter your client_id API key and for client password, enter the client_secret API key from KeyBank.

cURL command template

curl -X POST --cert {{client.crt}} --key {{client.key}} --cacert {{ca.crt}} \
                    ‘{{host}}/oauth/v1/token?scope=rs-read'
                    -H 'Authorization: Basic {{base64 encoded consumer key and secret}}' 
                    -H 'Content-type: application/x-www-form-urlencoded'
                    -H 'Accept: application/json'
                    -d 'Id={{client id}}&Key={{client password}}&grant_type=client_credentials'

Request and response example

The response contains a field named access_token. Use this access token in the Authorization header when you call the API over a secure mTLS connection.
If you are unable to retrieve an access code, reassess your setup, review your API keys, and make sure you are properly connected to the environment before you try again.

Request

Response

curl -X POST --cert client.crt --key client.key --cacert ca.crt \
'https://api.qv.keybank.com/oauth/v1/token’
-H 'Authorization: Basic KFddrcHQwQ3JDGQTamdqRUI0bEFHVVlHQcg'
-H 'Content-type: application/x-www-form-urlencoded'
-H 'Accept: application/json'
-d 'Id=b1194a183b8e01&Key=165a15dfanqf1d60&grant_type=client_credentials'

curl -X POST --cert {{client.crt}} --key {{client.key}} --cacert {{ca.crt}} \
{
"refresh_token_expires_in": "0",
   "api_product_list": "[API 1, API 2, API 3]",
   "api_product_list_json": [
      "API Inquiry",
      "API test product",
   ],
   "organization_name": "keybank-non-prod",
   "developer.email": "yourEmail",
   "token_type": "BearerToken",
   "issued_at": "2255448892"
   "client_id": "KBConsumerKey”,
   "access_token": "gPd4ZXMi927aoWhvmc",
   "application_name": "9IIa42-134320dk32s",
   "scope": "apiauth-read apiauth-write rs-create rs-delete rs-oauth rs-read rs-update rs-write",
   "Id": "KBClientId",
   "expires_in": "86399",
   "refresh_count": "0",
   "status": "approved"
}

What to expect

You get a response with access token and information about which API products you can use, the refresh token time cycle, expiration time, etc.
Select and copy the access_token value to use with your API requests.
The access token remains valid for 24 hours. If it expires, try the refresh token to receive a new access token and pass in the API request.

What's next?

If this all sounds nice to you, sign up to speak with an Embedded Banking Payments Advisor. Our people will reach out to your people.
Read our API documentation to learn more about KeyBank’s API products. Or if you prefer to look under the hood, download an API specification file in YAML format.

Subscribe to