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.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);
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.
Services
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])
Update connection
const job = await connService.update(connection, password);
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);
Entities
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);
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();