Developer hub
← Back HomeNPMDeveloper HubAPIBlog

Quickstart: API

Make your first call to the Basiq API.

Suggest Edits
1037

Quickstart

 

STEP 1: Register



To begin, register your application via our dashboard and configure it accordingly. Before proceeding to create a new API key, ensure your application settings are in order.

📘

API Keys

You can create as many API keys as you want, which allows you to use keys across different applications and environments. It’s a good idea to give each API key a meaningful name in order to differentiate between them.

🚧

Keep your key secret

Make sure you copy and save the key we give you straight away, as it will only be exposed it in full once. Your API keys carry many privileges, so be sure to keep them secret!

Do not share your API keys in publicly accessible areas such GitHub, client-side code, etc

STEP 2: Authenticate

Exchange your newly acquired API key for an access token. This token enables secure interactions with the Basiq API and expires every 60 minutes. We recommend storing it globally and refreshing it 2-3 times per hour.

📘

Scope

The scope you supply will depend on the action you are performing, see the authentication section for further detail. For this quick start we will be using SERVER_ACCESS.

var axios = require('axios');
var qs = require('qs');
var data = qs.stringify({
  'scope': 'SERVER_ACCESS' 
})

var config = {
  method: 'post',
  url: 'https://au-api.basiq.io/token',
  headers: { 
    'Authorization': `Basic ${YOUR_API_KEY}`, 
    'Content-Type': 'application/x-www-form-urlencoded', 
    'basiq-version': '3.0'
  },
  data : data
};

axios(config)
  .then((response) => {
  console.log(response.data)
})
  .catch((error) => {
  console.log(error)
})

curl --location --request POST 'https://au-api.basiq.io/token' \
  --header 'Authorization: Basic $YOUR_API_KEY' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'basiq-version: 3.0' \
  --data-urlencode 'scope=SERVER_ACCESS'

STEP 3: Create a user

Creating a user establishes a repository for all financial data. Upon successful creation, you'll receive a userId. With this and the previously acquired access token, you possess all the necessary components to commence creating and fetching financial data.

var axios = require('axios');
var data = JSON.stringify({
  "email": "[email protected]",
  "mobile": "+614xxxxxxxx"
});

var config = {
  method: 'post',
  url: 'https://au-api.basiq.io/users',
  headers: { 
    'Authorization': 'Bearer $YOUR_ACCESS_TOKEN', 
    'Accept': 'application/json', 
    'Content-Type': 'application/json'
  },
  data: data
};

axios(config)
.then(function (response) {
  console.log(response.data);
})
.catch(function (error) {
  console.log(error);
});

curl --location --request POST 'https://au-api.basiq.io/users' \
  --header 'Authorization: Bearer $YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email": "[email protected]",
    "mobile": "+614xxxxxxxx"
  }'

Congratulations! You have registered your application, and made your first, authenticated call to Basiq to create a user!

STEP 4: Consent & Connect via the Consent UI

Before you can retrieve a users financial data, you first need to link to their financial institutions by creating a connection. This can only be done once a user has explicitly consented to share their data. This can be done via the Basiq Consent UI. While you are starting out in sandbox mode, use the institutions and credentials provided here.

// STEP 4: Consent & Create a connection 

window.location = `https://consent.basiq.io/home?token={{client_token_bound_to_userId}}`;

curl --location --request POST 'https://au-api.basiq.io/token' \
--header 'Authorization: Basic [YOUR-API-KEY]' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'basiq-version: 3.0' \
--data-urlencode 'scope=CLIENT_ACCESS' \
--data-urlencode 'userId=1234567-1234-1234-1234-123456781234'

STEP 5: Fetch Job History

After completing the consent journey and creating a connection, the consent UI will return a jobID or multiple jobIds if there are multiple connections in the consent UI.

Use the following cURL command to fetch job history:

curl --request GET \
     --url https://au-api.basiq.io/jobs/jobId \
     --header 'accept: application/json'

The job response will contain three steps associated if this is a data connector job.

{
  "type": "job",
  "id": "e9132638",
  "created": "2020-06-10T09:59:00Z",
  "updated": "2020-06-10T09:59:00Z",
  "steps": [
    {
      "title": "verify-credentials",
      "status": "success",
      "result": {
        "type": "link",
        "url": "/users/ea3a81/connections/8fce3b"
      }
    },
    {
      "title": "retrieve-accounts",
      "status": "in-progress",
      "result": null
    },
    {
      "title": "retrieve-transactions",
      "status": "pending",
      "result": null
    }
  ],
  "links": {
    "self": "https://au-api.basiq.io/jobs/61723",
    "source": "https://au-api.basiq.io/users/ea3a81/connections/8fce3b"
  }
}

Upon successful completion of all three steps, the job moves to the fetch stage to retrieve the data.

To ensure you receive the data once it's available, continue polling this jobs endpoint until you receive a success status for all three steps. Once all steps are successfully completed, you can proceed to fetch the data.

STEP 6: Fetch your aggregated data

Once you have successfully created a connection, you can go ahead and retrieve the data belonging to it. Let’s retrieve a list of all the accounts this user has connected through Basiq. 

// STEP 5: Fetch your aggregated data 

var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://au-api.basiq.io/users/{user.id}/accounts',
  headers: { 
    'Authorization': 'Bearer $YOUR_ACCESS_TOKEN', 
    'Accept': 'application/json'
  }
};

axios(config)
.then(function (response) {
  console.log(response.data);
})
.catch(function (error) {
  console.log(error);
});

curl --location --request GET 'https://au-api.basiq.io/users/a920c00f-df79-4a12-b711-2ac461c8090b/accounts' \
--header 'Authorization: Bearer $YOUR_ACCESS_TOKEN' \
--header 'Accept: application/json'

The response will contain an array of Account objects, containing specific account details such as the account number, balance and available funds.

Congratulations! You have now created a user consent, connected a financial institution, and retrieved their financial data.

 

Feel free to deep dive into our full API reference to see what else is possible with Basiq.

Updated 5 months ago