API
← Back HomeNPMDeveloper HubAPIBlog

Create a connection

Use this to create a new connection. When a new connection request is made the server will create a job that will process the following steps if no MFA challenge is met:

Step

Description

1

verify-credentials

The server will attempt to authenticate with the target institution using the supplied credentials

2

retrieve-accounts

The server will retrieve the complete list of accounts and their details e.g. account number, name and balances

3

retrieve-transactions

The server will fetch the associated transactions for each of the accounts

and these steps if an MFA challenge is met:

Step

Description

1

verify-credentials

The server will attempt to authenticate with the target institution using the supplied credentials

2

mfa-challenge

The server has been met with an MFA challenge and is processing/verifying this

3

retrieve-accounts

The server will retrieve the complete list of accounts and their details e.g. account number, name and balances

4

retrieve-transactions

The server will fetch the associated transactions for each of the accounts

📘

Check institution authorization type

To create a connection you need to check the authorization type for the institution.

  • If Institutions authorization = user then loginId and password are mandatory, and user token is not required
  • If Institutions authorization = token then userToken is mandatory and login credentials are not required
  • If Institutions authorization = user-mfa then the user will always be met with an MFA challenge step immediately after their credentials have been verified
  • If Institutions authorization = user-mfa-intermittent then the user will sometimes be met with an MFA challenge step immediately after their credentials have been verified

You can check the status of each step by querying the job resource (returned when the connection is created).

Arguments

loginId
string, conditional

The users institution login ID. Mandatory if Institutions authorization = user.

password
string, conditional

The users institution password. Mandatory if Institutions authorization = user.

userToken
string, conditional

The userToken. Mandatory if Institutions authorization = token.

securityCode
string, conditional

User's institution security code. Mandatory if required by institution's login process

secondaryLoginId
string, conditional

User's institution secondary login id. Mandatory if required by institution's login process

institution
object, required

Only the id of the institution is required

🚧

Note that the time it takes to complete the processes above will vary depending on the volume of data along with the general latency between our servers and the financial institution. As a rough guide this entire process could take anywhere between 3 - 30 secs.

Returns

Returns a created job resource, if the operation succeeded. Returns an error if the post failed (e.g. not supplying required properties).

📘

In order to avoid duplicate jobs

If you attempt to create or refresh a connection while a job is either queued or still in progress, the API will return a 200 status with the original job instead of a newly created job.

POST /users/{user.id}/connections

POST /users/ea3a81/connections HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "loginId": "gavinBelson",
  "password": "hooli2016",
  "institution":{
    "id":"AU00000"
  }
}

POST /users/ea3a81/connections HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
  "userToken": "token:PTln18RhwL",
  "institution":{
    "id":"AU19301"
  }
}

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "type": "job",
  "id": "61723",
  "links": {
    "self": "https://au-api.basiq.io/jobs/61723"
  }
}