Developer hub
← Back HomeNPMAPI StatusGet API KeysBlogHelp Center
Start typing to search…

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:

#

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

📘

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

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"
  }
}

🚧

This response does not contain connection ID

Instead it will return a link to the job which has been created. You can use this to obtain the connection ID and track the status of the job. See here for more on handling jobs.

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

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