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.

Definition

POST /users/{user.id}/connections

Example Request LoginId/Password

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

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

Example Request User Token

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.

Example Response

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

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