Basiq.io Node.js SDK

This is the documentation for the Node.js SDK for Basiq.io API

Introduction

To view the API docs, click here.

The SDK is organized to mirror the HTTP API's functionality and hierarchy. The top level object needed for SDKs functionality is the Session object which requires your API key and may require API version to be instantiated. You can create a new API key on the dashboard.

Changelog

1.1.0 - Addeed secondaryLoginId parameter to connection API

1.0.1 - Documentation updated

1.0.0 - SDK updated to version 2.0

0.9.0beta - Initial release

Getting started

Install the SDK using:

npm i -s basiq-sdk-nodejs

Import the package:

const BasiqSDK = require("basiq-sdk-nodejs");

Common usage examples

Fetching a list of institutions

const BasiqSDK = require("basiq-sdk-nodejs");

(async function() {
        const session = await BasiqSDK.Session("YOUR_API_KEY");

        const institutions = await session.getInstitutions();
})();

You can specify the version of API when instantiating Session object. When the version is not specified, default version is 1.0.

const BasiqSDK = require("basiq-sdk-nodejs");

(async function() {
        const session = await BasiqSDK.Session("YOUR_API_KEY", "2.0");

        const institutions = await session.getInstitutions();
})();

Creating a new connection

const BasiqSDK = require("basiq-sdk-nodejs");

(async function() {
        const session = await BasiqSDK.Session("YOUR_API_KEY");

        const user = session.forUser(userId)

        const job = await user.createConnection(institutionId, loginId, password[, securityCode, secondaryLoginId]);

        const connection = await job.waitForCredentials(1000, 60);
})();

Fetching and iterating through transactions

const BasiqSDK = require("basiq-sdk-nodejs"),
    FilterBuilder = BasiqSDK.FilterBuilder;

(async function() {
        const session = await BasiqSDK.Session("YOUR_API_KEY");

        const user = session.forUser(userId);

        try {
                const fb = new FilterBuilder();
                fb.eq("connection.id", connId);
                const transactions = await user.getTransactions(fb);

                while (await transactions.next()) {
                        console.log("Number of records: ", transactions.data.length);
                }
        } catch (e) {
                console.error(typeof e, e);
        }
})();

API

The API of the SDK is manipulated using Services and Entities. Different services return different entities, but the mapping is not one to one. All http functions return promises. In case of a failed http resolution the promise rejection will return an error object.

Errors

If an action encounters an error, you will receive an APIError instance. The object contains all available data which you can use to act accordingly.

APIError properties

Error.statusCode
Error.response
Error.message

Check the docs for more information about relevant fields in the error object.

Filtering

Some of the methods support adding filters to them. The filters are created using the FilterBuilder function. After instantiating the object, you can invoke methods in the form of comparison(field, value).

Example:

const fb = new FilterBuilder();
fb.eq("connection.id", "conn-id-213-id").gt("transaction.date", "2018-01-01");
const transactions = user.getTransactions(fb)

This example filter for transactions will match all transactions for the connection with the id of "conn-id-213-id" and that are newer than "2018-01-01". All you have to do is pass the filter to the method when you want to use it.

Session

Creating a new Session object

(possible API versions: "1.0" and "2.0", default version: "1.0")

const session = await BasiqSDK.Session("YOUR_API_KEY");

const session = await BasiqSDK.Session("YOUR_API_KEY", "API_VERSION");

UserService

The following are APIs available for the User service

Creating a new UserService

const userService = BasiqSDK.User(session);

Referencing a user

Note: The following action will not send an HTTP request, and can be used to perform additional actions for the instantiated user.

const user = userService.for(userId);

Creating a new User

const user = await userService.new({
        email: "",
        mobile: ""
})

Getting a User

const user = await userService.get(userId);

Update a User

const user = await userService.update(user, {
    email: "",
    mobile: ""
});

Delete a User

const result = await userService.delete(user);

Refresh connections

const result = await userService.refreshAllConnections(user);

List all connections

const conns = await userService.getAllConnections(userId, filter);

Get account

const acc = await userService.getAccount(userId, accountId);

Get accounts

const accs = await userService.getAccounts(userId, filter);

Get transaction

const transaction = await userService.getTransaction(userId, transactionId)

Get transactions

const transactions = await userService.getTransactions(userId, filter)

ConnectionService

The following are APIs available for the Connection service

Creating a new ConnectionService

const connService = new BasiqSDK.Connection(session, user);

Get connection

const connection = await connService.get(connectionId)

Get connection entity with ID without performing an http request

const connection = connService.for(connection)

Create a new connection

const job = await connService.new(institutionId, loginId, password[, securityCode, secondaryLoginId])

Update connection

const job = await connService.update(connection, password[, securityCode, secondaryLoginId]);

Delete connection

const result = await connService.delete(connection);

JobService

The following are APIs available for the Job service

Creating a new JobService

jobService = new BasiqSDK.Job(session, connectionService)

Get a job

const job = await jobService.get(jobId);

Get a job entity with ID without performing an http request

const job = jobService.for(jobId);

Get the related connection for the job

const connection = await jobService.getConnection(job);

Wait for the credential step to be resolved

(interval is in milliseconds, timeout is in seconds)

const connection = await jobService.waitForCredentials(job, interval, timeout);

Updating a user instance

const user = await user.Update({
        email: "",
        mobile: ""
});

Deleting a user

const result = await user.delete();

Get all of the user's accounts

const accounts = await user.getAccounts();

Get a user's single account

const account = await user.getAccount(accountId);

Get all of the user's transactions

transactions = await user.getTransactions();

Get a user's single transaction

transaction = await user.getTransaction(transactionId);

Create a new connection

job = await user.createConnection();

Refresh all connections

result = await user.refreshAllConnections();

Connection

Refresh a connection

job = await connection.refresh();

Update a connection

job = await connection.update(password[, securityCode, secondaryLoginId]);

Delete a connection

err = await connection.delete();

Job

Get the connection id (if available)

connectionId = job.getConnectionId();

Get the connection

connection = await job.getConnection();

Get the connection after waiting for credentials step resolution

(interval is in milliseconds, timeout is in seconds)

connection = await job.waitForCredentials(interval, timeout);

Get the connection after waiting for transactions step resolution

(interval is in milliseconds, timeout is in seconds)

connection = await job.waitForTransactions(interval, timeout);

Transaction list

Getting the next set of transactions [mut]

await transactions.next();