Overview

To pull business information from your customers connected apps you need to

  1. Provision an account to store your customers data 

  2. Display a menu of applications or data types to connect to and then get your customers permission to access data. 

  3. Use the API to pull the business information you need

All of this functionality is contained within our Link SDK.

Example Integration Flow:

Provision an Account

Before a customer can begin to share information a customer account needs to be provisioned to hold data synchronized for that specific business customer. To create a new account you need to make a POST request to the account administration API.

As part of the account creation you will specify a secret password/key which you will need to store and reference in subsequent steps. You will also need to specify a subdomain, which should be generated with a reasonable degree of uniqueness because the account creation request will fail if the provided subdomain is already in use. The response from successfully creating an account will contain account_domain, subdomain and account_key fields that you should store for subsequent reference.

Getting Permission

To connect a customers business application software you first need to get their permission to access their account by connecting the App. Once the App is connected you can make subsequent API calls to gather data.

Using the Link widget

The Link widget will list all supported Apps (by name or data type) and handle credential validation, multi-factor authentication, and error handling for each app that we support. The Link widget works across all modern browsers and platforms including mobile (iOS, Android) and web) and automatically handles many implementation details.

To embed the Link widget in to your web application you need to include a reference to a javascript file and create an HTML DIV tag within your page to render the widget within. This DIV tag will contain the application listing.

The container DIV tag:

<div class="DockLink_AppList"></div>
HTML

In order to access data you need to decide what type of data you want your user to provide and then display to them a list of app connection options that deliver the data. Platform types and example data sets include:

  • Accounting (tag: accounting)

    • Financial ratios and probabilities

    • Financial statements

    • AR/AP

  • Commerce (tag: commerce)

    • Subscriptions (inc recurring payments)

    • Purchases

    • Payment methods

    • Customers

    • Shipments

    • Sales

When embedding the link connection widget a set of platforms can be provided to limit the list to the types of information required.

The widget embed script:

<script type="text/javascript" src="https://example.myintranetapps.com/dock/link/2021-01-15/link.js"></script>
<script>
      var widget = new DockLink({
        container: document.getElementsByClassName('DockLink_AppList')[0],
        name: "Example Financial Institution",
        brand: {accent:'#FF0000'},
        domain: "{{ ACCOUNT_DOMAIN }}",
        cancel: "https://example.com/user-cancelled.html",
        redirect: "https://example.com/connection-complete.html",
        platforms: ['accounting','commerce'],
        auth: {basic: '{{ AUTH_BASIC }}'}
      });

      widget.render();
    </script>
JS
  • The domain of the src="https://example.myintranetapps.com/dock/link/2021-01-15/link.js" attribute should be changed to your domain. (Replace example.myintranetapps.com with your domain).

  • When you provision an account, the Administration API response contains an account_domain value that should used here for the domain parameter. (Replace {{ ACCOUNT_DOMAIN }} with the newly provisioned account’s account_domain value.)

  • When you provision an account, you must create a password for the new account and keep track of it. For the auth parameter here, you should replace {{ AUTH_BASIC }} with the result of calling base64Encode("admin:password") in whichever programming language you use - JSPythonPHPJava. For example, if the password created when provisioning an account was β€œhello123”, you would replace {{ AUTH_BASIC }} with the result of base64Encode("admin:hello123").

The following configuration values can be set when initializing the widget:

parameter

required

type

definition

container

yes

htmlElement

The HTMLElement that the widget should render within

name

no

string

The name of your company that you want displayed within the widget

brand

no

Object

An object containing accent color and logo

domain

yes

string

The account domain of the business account to gather and share data with.

cancel

no

string

The URL a user is redirected to if they cancel the connection process

redirect

yes

string

The URL a user is redirected to once a connection is complete

platforms

no

array

An array of platforms that will be displayed in the widget, accounting and commerce are supported

auth

yes

Object

Authentication/Access information to allow an account connection to be made.

search

no

bool

Whether to show an app search

dataSecurity

no

string

URL to a security policy

terms

no

string

URL to a terms and privacy policy

Pull business information

After a connection has been established you can make API calls to the common data model and call upon different business data objects as shown in our examples