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