Tips, Tricks and Best Practices

1. Be aware of paging

Each end-point that returns multiple records in the SISS REST APIs use pagination to return results.

Query Parameters

The pagination requirements are stipulated on a request using query parameters. For end-points that support paging the following query parameters MAY be provided:

  • page – the page number being requested (with the first page being 1)

  • page-size – the number of records to return in each page

If the query parameters are not provided the following defaults will be assumed:

  • page – a default of 1 (the first page) will be assumed

  • page-size – a default of 25 will be assumed

Response Fields

In addition to the data requested, the responses include following additional information:

  • In the links object, in addition to the self field the following fields are to provided:

    • first - A URI to request the first page. Only returned if this response is not the first page.

    • last - A URI to request the last page. Only returned if this response is not the last page.

    • prev - A URI to the previous page. Only returned if this response is not the first page.

    • next - A URI to the next page. Only returned if this response is not the last page.

  • In the meta object the following fields are to be provided:

    • totalRecords - The total number of records in the set.

    • currentpage - The current page of the set.

    • totalPages - The total number of pages in the set.

Additional Info

  • A maximum page size of 1000 records is set for all end points. If a page size greater than this maximum is requested then a HTTP status of 422 Unprocessable Entity WILL be returned.

2. Cater for Rate Limiting (Throttling)

Rate Limits are in place for all tiers (even the unlimited tier has an upper maximum TPS).  You should control the number of calls you make to the SISS REST APIs to match the TPS and monthly limits of your subscribed products.

If you make more than your allowed calls within 1 second, or exceed your total calls for the month, you will receive a 429 Too Many Requests response.  This response includes a retry-after field, which states the number of seconds you need to wait.

You DO NOT need to request a new JWT token upon receiving this error, and making a call with a new token (assuming you could retrieve a new JWT token within the retry-after value) will return the same error code.

3. Use a Unique ID that represents your client when adding Accounts

To make it easy for you to manage your data within the SISS API, and to assist you with matching data within your systems, when creating Accounts, we strongly recommend providing an (obfuscated) identifier that represents your client which you pass to either:

  • /sds/account-access-consents/consumerconsent as a clientId body parameter

  • /sds/account-access-consents/consumerconsent as the clientIdentifier body parameter

4. Track the last transaction date received for each account

Any time you retrieve transactions, you SHOULD store the most recent transaction date received for the account against the account record in your system.

The reason to do this, is to make your calls as efficient as possible, so you are only collecting only new transactions.  As all data provided to SISS is POSTED transactions up until midnight of the previous day, no transactions are ever inserted for prior days.

5. Collect data in an efficient manner

The SISS REST API's allow you to collect data in bulk for all your customers, or collect in a more targeted manner.  Choose the method that is effective for you.

Bulk Collection

This allows you to collect data in paged data sets, and then match data up within your systems.

The typical set of calls would be:

  1. Get a List of All Clients - /sds/clients
    Check that you know all the clients you need to be matching data against.

  2. Get a List of All Accounts - /banking/accounts
    A list of all accounts available to you.  This account list includes, for each account, any clientId you provided in Tip 3 above. Note, this also includes a field high

  3. Get a List of All Balances - /banking/accounts/balances?x-v=2
    A list of all balances available to you.  This balance list includes, for each balance, the accountId the balance relates to. We recommend providing the x-v=2 parameter to get a list which has a format aligned to CDR version 1.

  4. For each account in the List of All Accounts - Get a List of Transactions for an Account -  /banking/accounts/{accountId}/transactions?{oldest-time}
    A list of transactions for a specific account.   If you have followed Tip 4 above, you SHOULD also only request transactions for accounts where you know there are new transactions (by checking the value stored in your system against the lastTransactionPostedDate field in the account record)

On-demand/Targeted

This relies on getting the data for clients based on the clientId, assuming you have followed Tip 3 above

  1. (Optional) Get a List of All Clients - /sds/clients
    Used to check in case any clients have been disabled or added that you have not tracked.  Also you can do this if you dont have the clientId in your systems.

  2. Get a List of Accounts for a Client - /sds/clients/{clientId}/accounts
    Used to check in case any accounts have been disabled or added that you have not tracked.  If you supplied your clientId as per Tip 3, then you can get a list of accounts for just that client.

  3. For each account in the List of Accounts for a Client - Get Balances for an Account - /banking/accounts/{accountId}/balances?x-v=2
    A list of balances for the account.  We recommend providing the x-v=2 parameter to get a list which has a format aligned to CDR version 1.

  4. For each account in the List of Accounts for a Client - Get a List of Transactions for an Account -  /banking/accounts/{accountId}/transactions?{oldest-time}
    A list of transactions for a specific account.   If you have followed Tip 4 above, you SHOULD also only request transactions for accounts where you know there are new transactions (by checking the value stored in your system against the lastTransactionPostedDate field in the account record)

6. Valid BSB and Account numbers

Before submitting requests to register bank data feeds, please use local validation to validate the BSB and Account Numbers entered by clients. These are the same rules that are enforced by the SDS system. All valid BSB are 6 digits in length, the 3rd digit must be in range [2-7], each of which represents a unique ‘State Code’ (i.e. NSW, QLD, VIC)

ANZ - Australia New Zealand Bank

BSB length = 6, Starts with 01

Account Number length 9

Bank of Melbourne

BSB length = 6 Starts with '19' OR '55'

Account Number length 9

Bank SA

BSB length = 6 Starts with '10'

Account Number length 9

CBA - Commonwealth Bank of Australia

BSB length = 6 Starts with '06' OR '76'

Account Number length 8

Not available if starts with 5 = term deposit

Macquarie Bank

BSB length = 6 Starts with '18'

Account Number length 9

NAB - National Australia Bank

BSB length = 6 Starts with '08' OR '78'

Account Number length 9

St George

BSB length = 6 Starts with '11' OR ‘33’

Account Number length 9

Westpac

BSB length = 6 Starts with '03' OR '73'

Account Number length 6

Bank of Queensland

BSB length = 6 Starts with ‘12’

Account Number length 7-10

Adelaide Bank

BSB length = 6 Always ‘610101’

Account Number length 9

Copyright © SISS Data Services 2021.