About BankQUALIFY

Welcome to the BankQUALIFY Integration Guide. The guide contains three sections:

About BankQUALIFY
Integration Documentation
Results Data

By completing this guide, you will have a solid understanding of BankQUALIFY, how to create inquiries through our API, and how to understand inquiry results.

This guide contains a varied collection of articles on a breadth of topics. Articles are marked by their primary field:

General / top-level
Software technology
Data & operations

What is BQ?

BankQUALIFY ("BQ") uses basic account information and PII to identify account ownership, flag potential fraud, and assess payment affordability risk based on several simple attributes.

Provide basic customer PII (name, address, phone, email) and their account and routing number. BankQUALIFY takes less than a second.

Is this the right product for my business?

ValidiFI's REST API contains 3 INSIGHTS products:

BankQUALIFY - Use basic PII and account/routing number to quickly identify the lead quality.
BankVERIFY+ - Use basic PII and account/routing number for deep insights and recommended actions.
BankLOGIN+ - Use credentialed account and transaction information to uncover thousands of attributes and recommended actions.

All three INSIGHTS products can be used through the ValidiFI API.

	BankQUALIFY	BankVERIFY+	BankLOGIN+
Identify ownership, fraud risk, basic affordability	✔	✔	✔
Requires basic PII and account/routing number (non-credentialed)	✔	✔
Requires transaction data from bank login (credentialed)			✔
Instant results through REST API	✔	✔	✔
Can be used through the CONNECT user interface		✔	✔
Light weight, sub-second response time	✔
Advanced analytics with over 1000 calculated attributes		✔	✔
Custom decisioning rulesets	✔	✔	✔

INSIGHTS products comparison

You may consider using BankQUALIFY to catch the most blatant issues before running BankVERIFY+. You may also consider waterfalling some concerning leads from BankVERIFY+ into a bank login to gain transaction data and then into BankLOGIN+ for thousands of attributes and deep understanding of those transactions.

BankQUALIFY+ can be called through the ValidiFI INSIGHTS API.

Find more details about available scores and attributes in the Data Results section.

The use of BankQUALIFY requires you to submit payment data back to ValidiFI. Click here for information about submitting payment data.

Integration Overview

The test environment is a sandbox that enables you to interact with and integrate ValidiFI products without the need for real customer or account information. The test environment has its own web portal and its own subdomain for API calls.

	Web Portal	API Subdomain
Test	https://test.ribbit.ai	https://sandbox.ribbit.ai/{endpoint}
Production	https://portal.ribbit.ai	https://prod.ribbit.ai/{endpoint}

Follow this guide to integrate BankQUALIFY with the developent tools and shortcuts available in the test environment. Transitioning into production is very simple, and is covered later in this guide.

Integrate BankQUALIFY

This section is the technical guide to integrating BankQUALIFY, and is addressed to software developers. It contains details about the request and response formats, error codes, and suggestions for your integration.

Development times to integrate an INSIGHTS API will vary and there is a lot to cover. Continue following this guide, and we will walk through the process together.

BankQUALIFY is in version 1.3

You have selected integration through direct API. This can be changed later.

You are viewing documentation for API version 4.0.

Authentication

Before you can call an INSIGHTS product, you must get authentication for the request. ValidiFI API calls are authenticated using OAuth bearer tokens.

Please log into https://test.RIBBIT.ai to obtain your clientId and clientSecret.

To obtain a bearer token, make a POST request:

POST /v4/Token

Please see https://apidocs.ribbit.ai for API documentation.

You will receive a token that you can then cache and use until its expiration.

Each OAuth token can be used for about an hour. To ensure optimum performance, do not call the token endpoint before every call if you already have a valid token.

The token can then be passed into any API header as:
authentication: Bearer access_token

Exercise (5 minutes) - Getting Authenticated

Log in and select "API" from the left navigation menu.
Select Show API Credentials and copy the clientId and clientSecret.
Click here to download a sample Postman collection and import into Postman.
In the imported Postman collection, select the POST Token request from the "v4" folder and paste your clientId and clientSecret in the provided spaces.
Send the request.

You should get a HTTP 200 Ok response. You will use the access_token value in the request header of all other ValidiFI API requests.

Take note of the expires_on response field. You can use this token as many times as you want until the stated expiration time - usually about 60 minutes.

Request Schema

BankQUALIFY is a part of the INSIGHTS suite. In Version 4, BQ can be called from the POST /Insights endpoint by setting the productId to 1.

To use BankQUALIFY, set the productId field to 1.

Please see https://prod.ribbit.ai/docs/index.html for API documentation.

Request Fields

BankQUALIFY requires specific PII (personally-identifiable information) in order to run properly and provide the most accurate results.

Field Name	Type	Description
productId	int32	Declares the INSIGHTS product. This value must be `1` for BankQUALIFY
referenceId	string	Unique application or customer id from your system
inquiryId	string (GUID)	The ValidiFI InquiryId if you have previously run this customer & account through BankVERIFY+
consumer.firstName	string	The first/given name of the customer or signer on the application
consumer.lastName	string	The last/family name of the customer or signer on the application
consumer.phone	int32	Phone number of the customer or signer on the application. Must be in 10-digit format.
consumer.email	string	Email address of the customer or signer on the application
consumer.address	object	The physical address of the customer or signer on the application. `address`, `city`, `state`, and `zip` must be instantiated and not null.
account.routingNumber	int32	The 9-digit routing number of the customer's bank. Even when testing, you must use a real routing number
account.accountNumber	int32	The customer's account number, including any leading zero's. For testing, you must use realistic numbers
offerAmount	double	The total amount of the loan, the offer amount for a credit product, or the maximum amount of spending allowed.
paymentAmount	double	The median payment/spending amount of approved applications in your portfolio
terms	string	The terms of the repayment schedule. The value must be one of the following strings: `daily_oblig`, `weekly_oblig`, `biweekly_oblig`, `monthly_oblig`

Required for all requests

We recommend that you hard code your portfolio median or average for the offerAmount, paymentAmount, and terms fields.

Exercise (5 minutes) - My First BQ Inquiry

Complete the "Getting Authenticated" exercise.

Using the provided Postman collection, get an un-expired bearer token.
Open the POST INSIGHTS request from the "v4" folder and navigate to its "Headers" tab. Note that the "Authorization" header key references the bearer token which you just generated.
Navigate to the request's "Body" tab and take note of the sample payload. Ensure productId is set to "1".
Send the request.

You should get a HTTP 201 Created response.

Congratulations! You have now used [or at least simulated] BankQUALIFY! Keep reading to decipher the response.

Response Schema

If the request was properly sent and all goes well, a 201 Created response will be returned.

Expect the JSON response of a successful inquiry to be around 52 lines in length (1.9 kilobytes). Find the full response schema in the API documentation.

Find more in the Data Results section of this guide.

Error Codes & Edge Cases

Possible HTTP Responses

The BankVERIFY+ response will be one of the following response types:

201 Created - The inquiry and verification were successful or a known exception has occurred.
401 Unauthorized - There is a problem with your credentials. Ensure the request contains the Authorization header, and that your bearer token has not expired. Ensure that the clientId and clientSecret were sent to the same URL domain as this API call.
403 Forbidden - You do not have permission to make this call. Commonly caused by attempting to access the production environment from an unauthorized IP address. Please contact ValidiFI support to authorize new workstations and servers.
500 Error - A problem occurred which prevented the service from completing. ValidiFI monitors all 500-level errors. If you are receiving 500s or any other unexpected results, please open a ticket by messaging ValidiFI Support.

Status Codes

An error code is returned when the quality of the data you are providing is not high enough to run BankQUALIFY.

You will want to handle these errors because you may be able to obtain better information from your customer if the error is corrected.

Status Code 1 is a Success, and is always accompanied by account scores and attributes. Status Code 2 or higher is always accompanied by an Error Code and error description.

Status Code 2 - Account Validation Failure

1 - Invalid Routing Number
2 - Invalid Account Number
3 - Account Structure: The account number may be incorrect or malformed for the routing number submitted

Status Code 3 - Account Format Error

4 - Account number is invalid. Account number can only have numeric values.
5 - Account number cannot exceed 17 characters in length.
6 - Routing number is invalid. Routing number can only have numeric values.
7 - The account number length is invalid.
8 - Routing number can only be 9 characters long.
9 - Account number must be at least 5 characters long.
10 - The routing and account numbers cannot match

Status Code 4 - Account Validation Failure

11 - Business email cannot exceed 100 characters in length.
12 - Business email is not a valid email address.
13 - Business name is required.
14 - Business name length cannot be longer than 150 characters.
15 - Business phone number cannot exceed 12 characters in length.
16 - Business phone number length is invalid.
17 - First and last names are required.
18 - First name is required.
19 - Last name is required.
20 - Email cannot exceed 100 characters in length.
21 - ReferenceId cannot exceed 100 characters.
22 - First name must be at least 2 characters long.
23 - First name cannot exceed 100 characters long.
24 - Middle name cannot exceed 100 characters in length.
25 - Last name must be at least 2 characters in length.
26 - Last name cannot exceed 100 characters in length.
27 - Length of the first name: (FirstName returned) needs to be at least 2 characters in length.
28 - Length of the last name: (LastName returned) needs to be at least 2 characters in length.
29 - Phone number cannot exceed 12 characters in length.
30 - Email is not a valid email address.
31 - Phone number length is invalid.
35 - Signer is required for business
36 - You can only submit a business or consumer request not both.
37 - A business or consumer request is required.
38 - Terms can only be 'daily_oblig', 'weekly_oblig', 'biweekly_oblig', 'monthly_oblig'
39 - Payment amount cannot be less than zero.
40 - Offer amount cannot be less than zero.
41 - Consumer address cannot be null
42 - Consumer city cannot be null
43 - Consumer state cannot be null
44 - Consumer zip cannot be null
45 - Business address cannot be null
46 - Business city cannot be null
47 - Business state cannot be null
48 - Business zip cannot be null

Status Code 5 - Account Validation Failure

32 - There was a problem with connecting to our internal bank account network.
33 - There was a problem generating insights due to an analytics server issue.
34 - There count of identities may indicate potential fraud issues. Please request additional information.

The GET Endpoint

If you ever wish to retrieve the results of a prior inquiry, you do not need to re-submit the customer information in a new request. Instead, use the GET INSIGHTS endpoint.

GET /v4/insights/1/{inquiryId}

If you recorded the inquiryId from the original inquiry, submit that in the URL listed above: the results of the original inquiry will be returned again. There is no timeout or expiration, and no additional charge.

Moving to Production

From a software development standpoint, the following is involved in switching to production.

Whitelist your IP addresses

Our production API is IP address restricted. You must provide to us a list of public IP addresses that your back-end uses to call our API. Contact ValidiFI Support

Point your URL to our production server

Our production API server is https://prod.RIBBIT.ai.

Use production credentials (clientId and clientSecret)

Log into our production portal (https://portal.RIBBIT.ai), then click on "API" to see your production credentials.

In addition to the above changes, the following must also be complete:

Fully Executed Service Agreement

Underwriting Approval

Review of test environment transactions to ensure you are supplying the correct information and utilizing the service to its fullest capacity

Understanding BankQUALIFY Results

So your customer information has been processed and you have the INSIGHTS results! What are they?

This section is addressed to operations agents, data engineers, and anyone who wants to consume the information provided by BankQUALIFY.

Key Indicators

Along with 32 distinct attributes, BankQUALIFY contains aggregates to simplify decisions and categorize results. These values are calculated using the generated attributes.

Result Flag

Location: bqAccountAnalyticsResult.result

Perhaps the simplest way to consume BQ results, the result flag returns "Accept" or "Decline" recomendations. This result can be customized for your specific portfolio. Read more in the Custom Rulesets section below.

Stability Indices

Location: bqAccountAnalyticsResult.bqActionableIntelligence.bqBankStabilityIndex, .bqTransactionStability, .bqRiskStability, and .bqOwnershipStability

bqBankStabilityIndex is a 10-point scale (10 is highest stability) which ranks the stability of ownership, transactions, and risk associated with an applicant's bank account[s].

You spoke and we listened: INSIGHTS API version 4 adds three new fields to differentiate transaction, risk, and ownership stability.

Attributes

Location: bqAccountAnalyticsResult.attributes

BankQUALIFY contains 31 additional attributes, which include additional detials about risk, ownership, and transactions. Find more in the next section.

Data dictionary

Our data network identifies how often a bank account has been presented for payment and analyzes the bank/payment behavior to better predict financial outcomes.

ValidiFI's proprietary database of linkages between accounts and PII elements results in a set of verification and payment behavior attributes that can be used to identify risk, fraud, and ability to afford payment(s) for underwriting / onboarding of bank accounts.