vConnect Online

100% hosted interface for all of our verification products

Articles > vConnect > vConnect Online API

vConnect Online API

by Greg L. Senne, AAP

Updated February 4, 2025

vConnect Online brings the ability to use vConnect without any integration. The vConnect experience is hosted on ValidiFI's servers with an interactive web portal to manage sessions. It includes the ability to send customized e-mail and SMS links to your customer and send them to a customized landing page with your logo, language, and colors where they can connect their bank account. From our web portal, you can send requests directly to your customer's phone or e-mail, retrieve the results upon completion, and even download a report of the results.

If you would like to automate some or all of this process, you can pick-and-choose which pieces are hosted by ValidiFI and which parts you handle yourself by utilizing our API.

Step 1: Request a vConnect Session
The process starts by creating a new vConnect session. During session creation, you will send us details of the customer and transaction, and we will create a session.

To use our website to create a session, first log in to https://portal.RIBBIT.ai (production) or https://test.RIBBIT.ai (test).
To create a new session, click Create a New Connect Session after clicking on vInsightSync from the left menu.
Alternately, you can click the Customers menu from the left side menu, select your customer, and then initiate a new session. Doing this method will prevent you from needing to re-type the customer's information if it is already in our system

To create a new session using our API, first obtain a bearer token using API Credentials.
POST /v4/CONNECT/Session
```
{
    "token" : {
       "clientId" : "Your ValidiFI Client ID",
       "clientSecret" : "Your ValidiFI Client Secret"
    },
    "customer" : {
       "customerId" : "The unique Customer ID from your system",
       "firstName" : "John",
       "lastName" : "Smith",
       "emailAddress" : "test@noemail.com",
       "phoneNumber" : "1112223333",
       "address" : {
          "addressLine1" : "123 Main St",
          "city" : "Oxford",
          "state" : "OH",
          "zip" : "12345"
        }
    },
    "terms" : {
       "fullAmount" : 500,
       "amount" : 100,
       "loanTerms" : "biweekly_oblig"
    },
    "settings" : {
       "webhookURL" : "https://your.webhook.url/api (optional)",
       "bankId" : "1234567",
       "transactionHistoryDays" : 93
    },
    "notificationType" : 0
}
```
ValidiFI can send an e-mail or SMS link to the user when creating a session.
notificationType

   0 - No Notification Sent (default)

   1 - E-mail Notification - emailAddress propery is required

   2 - SMS (Text Message) - phoneNumber propery is required

Once the session is created, you have several options:
1. We can send your customer a link to our website, where your customer will consent to account access.
  - When using our website to create the vConnect session, make sure you select the option to send the request to the customer
  - If using our API, you must specify a notificationType of 1 (email) or 2 (sms). For email, a valid emailAddress is required. For SMS, a valid 10 digit phoneNumber is required.
2. You can use the custom URL provided after creating a session and send it to your customer using your platform. Your customer will then visit our platform to consent to account access.
  - If you are using our API, the URL is provided in the endpoint response
  - If you are using our website to create the session, you must use webhooks to be notified of the session creation.
    In the vConnect settings, make sure you have a Webhook URL specified. For more details about webhooks, see the section on vConnect Events.
3. You can integrate the vConnect widget into your website or app and handle the delivery through your own platform
  - For an API-based approach, see our vConnect Integration Instructions.
  - If you are using our website to create the session, you must use webhooks to capture the new sessionId, and then provide this to vConnect on launch. See the vConnect Integration Center for details on integrating vConnect into your platform.
Step 2: Your customer completes vConnect

Once a session has been created, your customer can complete vConnect.

If you would like to know when your customer completes vConnect, you can subscribe to webhooks and capture the complete event.
Learn how to capture events using webhooks
Step 3: See the Results

Once vConnect has completed, you can see the details of the session on our website. These details will tell you what accounts were enrolled and the result of any verifications.

Insights / Account Verification Results
To retrieve these results through our API, capture the inquiryId and inquiryTypereturned from the vConnect session's onRiskInquirySuccess or onFailedRiskInquiry events. You can obtain this data from the webhook response (or from the events if you have fully integrated vConnect into your platform).

If the inquiryType is BankVerify+, call this endpoint:
GET /v4/INSIGHTS/2/{inquiryId}

Details on the BankVERIFY+ response

If the inquiryType is BankLogin+, call this endpoint:
GET /v4/INSIGHTS/3/{inquiryId}

NOTE: BankLOGIN+ has been renamed to vInsightSync, but the inquiryType returned from vConnect will still say BankLogin+

Details on the vInsightSync response

Afford AI Report

For accounts that were connected using bank login credentials, you can obtain an Afford AI Report from our website in the same area where you would see the rest of the session information.

See endpoint details for Afford AI

Developer Docs

vConnect Online

100% hosted interface for all of our verification products

vConnect Online API

Step 1: Request a vConnect Session

Step 2: Your customer completes vConnect

Step 3: See the Results