NAV Navbar
Logo

Introduction

Quovo Connect is a valuable, easy-to-use JavaScript widget that you can embed into your web and mobile apps to help your users link their financial accounts. Connect integrates with the rest of Quovo’s API suite, providing a seamless and user-friendly sync process. Setting up Connect takes just a few minutes, and is described in the documentation below. To see the different screens of Connect on web and mobile, take a look at our guide here.

Access Tokens

Getting a Connect Access Token

curl -X POST -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" "https://api.quovo.com/v2/users/523479/iframe_token"
{
  "iframe_token": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvbmVfdGltZV91c2UiOnRydWUsImlwX3Jlc3RyaWN0ZWQiOmZhbHNlLCJzdWIiOiI1MjM0NzkiLCJleHAiOjE0ODQ5NTIzNjQsImlwIjoiMTI3LjAuMC4xIiwiaWF0IjoxNDg0OTQ4NzY0LCJ0eXBlIjoiaWZyYW1lIiwiaWQiOiIzZWI1ZjJjNTIxMjdiODU2NDUzMDM1NTU1MGRhMTM5MTczODE0MGQ4IiwidXNlciI6NTIzNDc5fQ.XT-lOL5GBTASXAX8CFOaNO_fOr2W6BhrPe1Pfa695SE",
    "user": 523479
  }
}

Connect authenticates on a per-user basis, requiring a single-use access token every time the app is loaded. The process is similar to the Quovo iframe workflow.

After creating a Quovo user, make a POST request to https://api.quovo.com/v2/users/{user_id}/iframe_token, where {user_id} is the id of the Quovo user.

You can then use this token to authenticate to Connect, which is detailed in the integration sections. Any Quovo Account synced within Connect will be tied to the user passed in the /iframe_token call.

Simple Integrations

<div id="quovo-widget"></div>
<!-- {token} is generated by a backend process every time the page is loaded. -->
<script
  type="text/javascript"
  src="https://connect.quovo.com/connect.js"
  data-connect-id="quovo-widget"
  data-token="{token}">
</script>

With a simple integration, you can integrate Connect in just a few lines of code.

Add the connect.js script to your page, passing in the ID of an HTML element and a user-specific access token through data- attributes. This will automatically create a “Connect Your Accounts” button, which opens Connect when clicked. (In the example to the right, {token} is generated by a backend process every time the page is loaded.)

The available attributes on the <script> element are:

Attribute Description
data-connect-id The id of an HTML element. This element will be replaced with a button, used to open Connect.
data-token A user-specific access token. This is used to authenticate the user and gain access to Connect.

Custom Integrations

Customizing Your Integration

<script type="text/javascript" src="https://connect.quovo.com/connect.js"></script>
<button id="quovo-connect">Add Your Accounts</button>

<script>
  function setupConnect(token) {
    var handler = Quovo.create({
      token: token,
      // optional function parameters
      onLoad: function() {
        console.log('loaded');
      },
      onAdd: function(err, event) {
        if (!err) {
          console.log('Account', event.connection.id, 'added!');
        }
      },
      // optional string parameter
      topInstitutions: 'banks',
    });

    var connect = document.getElementById('quovo-connect');
    connect.addEventListener('click', function(event) {
      handler.open();
      event.preventDefault();
    });
  }

  // getConnectToken is an asynchronous function that fetches a user-specific
  // Connect access token. Since this function depends on the structure of
  // your server-side code, it is not defined here.
  getConnectToken(setupConnect);
</script>

With a custom integration, you can have more fine-tuned control over Connect, deciding when and how it opens, what should happen after it closes, and more.

After loading the connect.js script, the Quovo Connect library will be available as the Javascript variable Quovo. Call Quovo.create to create a handler for Connect, allowing you to open or close the app as necessary. (In the example to the right, getConnectToken is an asynchronous function that fetches a user-specific Connect access token. Since this function depends on the structure of your server-side code, it is not defined here.)

The available parameters to Quovo.create are:

Field Type Description
token string [required] A user-specific access token. This is used to authenticate the user and gain access to Connect.
onLoad function A callback function triggered after Connect is done loading.
onOpen function A callback function triggered every time Connect is opened.
onClose function A callback function triggered every time Connect is closed.
onAdd function A callback function triggered anytime a Quovo Account is created within Connect.
onSync function A callback function triggered when an Account is synced through Connect.
testInstitutions boolean If true, Quovo test institutions will be searchable within Connect.
topInstitutions string Choose what type of institutions, if any, will be displayed in the Top Institutions portion of the institution select screen. Possible values are banks, brokerages, all, or none. This parameter is optional and will default to all.
singleSync boolean If true, the “Connect Another Account” button will be hidden. This button appears once an Account has been successfully synced to prompt the User to add any additional Accounts they may have. This parameter is optional and will default to false.
enableAuthDeposits boolean If true, the Auth Deposits workflow will be enabled within Connect. This lets end users verify their bank accounts on any institution not covered by instant account verification. Note: This workflow is not available by default. Contact us if you would like access to Auth Deposits within Connect.
function setupConnect(token) {
  var handler = Quovo.create({
    token: token,
    onLoad: function() {
      // Connect will open immediately after it is done loading.
      handler.open();
    },
  });
}

getConnectToken(setupConnect);

onAdd and onSync

While callbacks like onLoad or onClose are triggered by the Connect widget itself, onAdd and onSync are triggered by user actions inside of Connect. Using these callbacks, you can trigger actions anytime a user adds or syncs an Account, providing a more responsive integration with Connect.

Both onAdd and onSync will either be passed an err argument, alerting developers to issues that Connect may have encountered; or an event argument, containing the results for the appropriate event.

{
  "connection": {
    "id": 2135634,
    "institution": 34,
    "user": 1123
  },
  "timeStamp": 1496879583157
}

onAdd

onAdd(err, event) will be triggered anytime a Quovo Account is created within Connect. event is an object containing:

event Object

Name Type Description
connection object The details of the Quovo Account that was just added. See below for fields in the connection object.
timeStamp integer A timestamp of when the event was generated. This is given in Unix epoch time in milliseconds.

connection Object

Name Type Description
id integer The new Account’s Quovo ID.
institution integer The institution ID of the new Account.
user integer The ID of the Quovo user that added the Account.
{
  "connection": {
    "id": 2135634,
    "institution": 34,
    "user": 1123
  },
  "sync": {
    "authenticated": false,
    "status": "questions"
  },
  "timeStamp": 1496879583157
}

onSync

onSync(err, event) will be triggered every time an Account is synced through Connect. event is an object containing:

event Object

Name Type Description
connection object The details of the Quovo Account that was just synced. See below for fields in the connection object.
sync object The results of the sync that just completed. See below for fields in the sync object.
timeStamp integer A timestamp of when the event was generated. This is given in Unix epoch time in milliseconds.

connection Object

Name Type Description
id integer The new Account’s Quovo ID.
institution integer The Quovo institution ID of the new Account.
user integer The ID of the Quovo user that added the Account.

sync Object

Name Type Description
authenticated bool This field indicates whether the Account has been successfully authenticated by the target institution. If it is true, then the credentials and MFA answers on the Account were entered correctly.
status string The final sync status of an attempted sync. If an Account has been successfully authenticated, this value may be null.

Preselect an Institution

handler.open({
  // Connect will bypass the search page and open directly to the page to
  // add a "Fidelity NetBenefits" Account (which has a Brokerage ID of 23).
  institution: 23,
});

You may want to direct users to add Accounts onto specific institutions. With Connect, you can preselect an institution for users and bypass the search page entirely.

Pass an object to the open method on the Connect handler. institution should be an available field, with the desired Brokerage ID as the value.

Update or Resolve Issues on an Existing Connection

handler.open({
  // Account 813981 has a status of "questions", so Connect will open to a
  // page where the user can answer any outstanding MFA questions and resync
  // the Account accordingly.
  connection: 813981,
});

You may want users to update or resolve issues on existing connections. They may need to supply additional MFA answers or update recently changed login credentials. With Connect, you can simply pass an Account ID to direct users to fix these issues, allowing their Accounts to continue syncing. Connections with a “login” status will be taken to a screen where users can update their credentials, while connections with a “questions” status will be taken to a screen where users are prompted to answer additional MFA questions.

If both connection and institution arguments are supplied to handler.open, the connection workflow will take priority.

Fetching Accounts

Getting Data for the Added Accounts

curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" "https://api.quovo.com/v2/users/523479/accounts"
{
  "accounts": [
    {
      "brokerage": 21534,
      "brokerage_name": "Test Investment Institution",
      "config_instructions": null,
      "failures": 0,
      "id": 877247,
      "is_inactive": false,
      "last_good_sync": "2017-03-28T14:00:40.533",
      "nickname": null,
      "opened": "2017-03-26T13:45:00.813",
      "status": "good",
      "update_count": 3,
      "updated": "2017-03-28T14:00:40.533",
      "user": 523479,
      "username": "quovo_test_user",
      "value": 73479.096133
    },
    {
      "brokerage": 21700,
      "brokerage_name": "Test Bank Institution",
      "config_instructions": null,
      "failures": 0,
      "id": 877504,
      "is_inactive": false,
      "last_good_sync": "2017-03-28T16:58:30.980",
      "nickname": null,
      "opened": "2017-03-28T16:58:30.980",
      "status": "good",
      "update_count": 1,
      "updated": "2017-03-28T16:58:30.980",
      "user": 523479,
      "username": "quovo_test_user",
      "value": 1744.14
    }
  ]
}

Once the user is done connecting their financial accounts (which will trigger the onClose function), you can fetch the added Accounts through the Quovo Aggregation API.

To view all of the user’s Accounts, make a GET request to https://api.quovo.com/v2/users/{user_id}/accounts, where {user_id} is the id of the Quovo user. Once you have the Accounts, you can use their opened field to tell if they have been added recently or not.

Using Webhooks

{
    "account": {
        "brokerage": 21700,
        "brokerage_name": "Test Bank Institution",
        "config_instructions": null,
        "failures": 0,
        "id": 2981126,
        "is_inactive": false,
        "last_good_sync": null,
        "nickname": null,
        "opened": "2017-04-17T18:54:45.550",
        "status": null,
        "update_count": 0,
        "updated": "2017-04-17T18:54:45.550",
        "user": 523479,
        "username": "quovo_test_user",
        "value": null
    },
    "action": "created",
    "event": "account",
    "user": {
        "email": "test.user@example.com",
        "id": 523479,
        "name": "Test User",
        "phone": null,
        "username": "quovo_test_user",
        "value": 582016.97
    }
}

In addition to calling the Quovo API, you can also register webhooks prior to users adding their Accounts. Your registered endpoints will then be notified any time a user adds a Quovo Account or when that Account finishes syncing. See here for steps on adding and verifying incoming webhooks.

Errors

try {
  handler.open({
    institution: 'bank of america',
  });
} catch (err) {
  if (err instanceof Quovo.InputError) {
    console.error('Invalid input type given to handler.open().');
  }
}
try {
  handler.open({
    institution: 'bank of america',
  });
} catch (err) {
  if (err instanceof Quovo.ConnectError) {
    console.error('A Connect-related exception has been raised.');
  } else {
    console.error('A non-Connect-related exception has been raised.');
  }
}

The Connect library provides a suite of detailed exceptions to help identify possible implementation issues. All of these custom error classes are bound to the top level of the Quovo object. These custom errors include:

Error Description
ConnectError The generic error type thrown by Connect. This exact exception will never be raised directly, but the rest of the errors listed here are subclasses of ConnectError. You can check for ConnectError to have a catch-all for any exceptions raised by Connect.
EventOriginError Raised when Connect detects a mismatch between the current host and the host that called Quovo.create.
InputError Raised when arguments given to any of Connect’s methods aren’t valid. More details on the invalid parameter will be provided in the error message when thrown.
TimingError Raised when Connect receives a request to open before it finishes loading. We suggest utilizing the onLoad callback argument taken by Quovo.create() to ensure Connect has finished loading before attempting to open it.
TokenError Raised when the access token provided to Connect is missing or invalid.
ElementNotFoundError Raised when the element ID given to Connect can not be located.