Getting Started

Step 1: Sign Up

To browse the SISS REST API's and their documentation, you need to:

  • Sign up for an account

  • Wait for the activation email from us, it should be nearly instantaneous.

  • Click the email link to complete the process.

If you don't receive an email, please check your spam or junk email folder 

Once you have completed the registration flow, Sign in to the portal and browse the documentation for the SISS REST API's

Step 2: Obtain your Credentials

To build against the SISS REST API's, or to make calls via a tool like Postman, you need an Ocp-Apim-Subscription-Key, a Client ID and a Client Secret.

Your Ocp-Apim-Subscription-Key is obtained by Subscribing to a Product.   

  • The Ocp-Apim-Subscription-Key is a used to identify you to the API for the subscription you have chosen.

  • The Client ID and Client Secret are required for generating your Authorisation to use the API, and are essential to protecting yourself and your customers.

Keep these pieces of information in a very safe place.

Subscribing to a Product

  • Go to the Products Page.

  • Select the product you wish to subscribe to.

    • Sandbox Product (can only be used against the SISS REST API Sandbox)

      • Sandbox - 200 calls/minute up to a maximum of 20,000 calls/week.

    • Production Products (can only be used once you have been approved for access to Production)

      • Tier 1 - 5 calls/second up to a maximum of 250,000 calls a month.

      • Tier 2 - 10 calls/second up to a maximum of 750,000 calls a month.

      • Tier 3 - 20 calls/second up to a maximum of 2,000,000 calls a month.

      • Unlimited - There are no throttling restrictions on calls to the API.

  • Confirm the details. You can provide your own name for the subscription.

Picture
  • Creating this product subscription will spur our team into action.  We will approve your subscription, and securely provide you with your Client ID and Client Secret.  If you have not been contacted by one of our API Team within 2 working days, please send an email to apiteam@sissdata.com.au.

Step 3: Try the API

SISS recommends using Postman to understand how the API works. 

We have created a Postman collection of a simple set of API calls to demonstrate the API. 

  • You can download the collection on this link.  You should save it as SISS REST API Starter.postman_collection.json

  • The environment is available on this link. You should have it as SISS REST API Starter.postman_environment.json

Authorise

To make calls to the API, your application will first need to obtain an access token from the SISS Authorisation server. For the SISS REST API's, an OAuth 2.0 Client Credentials Grant flow is used.

To obtain the required authorisation token, you will need to call https://auth.sissdata.com.au/oauth/token and exchange your Client ID and Client Secret for a JWT token. 

In the provided Postman collection, this is shown in 1. Call this for Authorisation -> Obtain JWT Token

Picture

E.g. the call to the Authorisation API would be:

curl -X POST \ https://auth.sissdata.com.au/oauth/token \
-H 'cache-control: no-cache' \
-d 'grant_type=client_credentials
&client_id=[your client id]
&client_secret=[your client secret]
&audience=https%3A%2F%2Fauth.sissdata.com.au'

The result of this call is a JWT access token.

{ "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJodHRwczovL3Npc3NkYXRhLmNvbS5hdS9iYWNrZW5kIjoic2FuZGJveCIsImlzcyI6Imh0dHBzOi8vYXV0aC5zaXNzZGF0YS5jb20uYXUvIiwic3ViIjoiMTlkYmM5NzQxNGE3NGIyZWE1OGFhYmZhOGExNWQ1MjdAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vYXV0aC5zaXNzZGF0YS5jb20uYXUiLCJpYXQiOjE1NTQwOTE4NzUsImV4cCI6MTU1NDA5NzYwOSwiYXpwIjoiMTlkYmM5NzQxNGE3NGIyZWE1OGFhYmZhOGExNWQ1MjciLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMiLCJqdGkiOiJmZjU2ZGU0OC1jMmVlLTRkZWQtODU5Mi04YWUzYmM0M2E1NzUifQ.6Q5e0Ak6kC-MIHq4mDRC7kbbT8hujzFO2BQUrnt3_zY", "expires_in": 600, "token_type": "Bearer" }

Call SISS REST API end-points

Once you have obtained your JWT token, you can call any end-point which requires authorisation.

To make a call to the API, simply ensure that you provide the :

  • Authorization: bearer [JWT Token]

  • Ocp-Apim-Subscription-Key: [Ocp-Apim-Subscription-Key]

In the provided Postman collection, this is shown in 2. Test Authorisation is Working -> Get a List of SISS Institutions

Picture

E.g. the following call structure gets a list of SISS Institutions.

curl -X GET \ 'https://api.sissdata.com.au/cdr-au/v1/sds/institutions?page-size=3' \
-H 'Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJodHRwczovL3Npc3NkYXRhLmNvbS5hdS9iYWNrZW5kIjoic2FuZGJveCIsImlzcyI6Imh0dHBzOi8vYXV0aC5zaXNzZGF0YS5jb20uYXUvIiwic3ViIjoiMTlkYmM5NzQxNGE3NGIyZWE1OGFhYmZhOGExNWQ1MjdAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vYXV0aC5zaXNzZGF0YS5jb20uYXUiLCJpYXQiOjE1NTQwOTE4NzUsImV4cCI6MTU1NDA5NzYwOSwiYXpwIjoiMTlkYmM5NzQxNGE3NGIyZWE1OGFhYmZhOGExNWQ1MjciLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMiLCJqdGkiOiJmZjU2ZGU0OC1jMmVlLTRkZWQtODU5Mi04YWUzYmM0M2E1NzUifQ.6Q5e0Ak6kC-MIHq4mDRC7kbbT8hujzFO2BQUrnt3_zY' \
-H 'Ocp-Apim-Subscription-Key: 8ddc3462ce724975868e9cadc42a5dee'

The above call would return a list of Institutions

{
    "data": {
        "institutions": [
            {
                "institutionId": "ANZ",
                "institutionType": "BNKA",
                "name": "Australia and New Zealand Bank",
                "email": "CustomerService@anz.com.au",
                "creationDateTime": "2011-08-31T11:30:08+10:00",
                "updateDateTime": "2020-02-20T17:13:13+11:00",
                "country": "AUS",
                "authorisationtypes": [
                    "CAF"
                ]
            },
            {
                "institutionId": "BEN",
                "institutionType": "BNKA",
                "name": "Bendigo Bank",
                "email": "sissdataforms@siss.com.au",
                "creationDateTime": "2017-08-10T16:43:48+10:00",
                "updateDateTime": "2020-02-20T17:17:47+11:00",
                "country": "AUS",
                "authorisationtypes": [
                    "CAF"
                ]
            },
            {
                "institutionId": "CBA",
                "institutionType": "BNKA",
                "name": "Commonwealth Bank Australia",
                "email": "info@cba.com.au",
                "creationDateTime": "2011-09-19T15:45:59+10:00",
                "updateDateTime": "2020-02-20T17:14:37+11:00",
                "country": "AUS",
                "authorisationtypes": [
                    "CAF"
                ]
            }
        ]
    },
    "links": {
        "self": "https://api.sissdata.com.au/cdr-au/v1/sds/institutions?page-size=3",
        "first": "https://api.sissdata.com.au/cdr-au/v1/sds/institutions?page-size=3&page=1",
        "next": "https://api.sissdata.com.au/cdr-au/v1/sds/institutions?page-size=3&page=2",
        "last": "https://api.sissdata.com.au/cdr-au/v1/sds/institutions?page-size=3&page=4"
    },
    "meta": {
        "totalRecords": 12,
        "currentPage": 1,
        "totalPages": 4
    }
}

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)

Copyright © 2019 SISS Data Services.  All Rights Reserved.