NAV Navbar
  • Introduction
  • Authentication
  • Testing
  • Versioning
  • Errors
  • Users
  • Connections
  • Accounts
  • Transactions
  • Institutions
  • Jobs
  • Changelog

  • Looking for the older version of API Docs?
  • Introduction

    Base API

    https://au-api.basiq.io
    

    Authentication

    /token
    

    Connect Resources

    /users
    /users/:id
    /users/:id/connections
    /users/:id/connections/:id
    /users/:id/accounts
    /users/:id/accounts/:id
    /users/:id/transactions
    /users/:id/transactions/:id
    /institutions
    /institutions/:id
    /jobs
    /jobs/:id
    

    Basiq provides a collection of APIs to help you build powerful financial solutions for a wide range of use cases. The most common use cases are:

    Basiq API Services

    Basiq provides two core API services which you can use to develop innovative financial solutions:

    Getting Started

    Start Developing

    Before you can start using any of the available Basiq APIs there are a few things you will need to do first.

    1. Sign-up to the Basiq API service
    2. Grab your api key for your application (via the Developer Dashboard)

    Once you have successfully obtained an api key, you can start using any of the available Basiq APIs.

    Authentication

    Definition

    POST /token
    

    Example Request (to acquire token)

    POST /token HTTP/1.1
    Authorization: Basic YOUR_API_KEY
    Content-Type: application/x-www-form-urlencoded
    basiq-version: 1.0
    
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "access_token":"YOUR_ACCESS_TOKEN",
        "token_type":"Bearer",
        "expires_in":3600
    }
    

    Example Request (using token)

    GET /users/ea3a81/accounts HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    Content-Type: application/json
    

    When working with Basiq APIs your application will need to complete the authentication process first before you can access any of the available resources.

    The authentication process is fairly straight forward, and simply requires you to exchange your API key for a token. Once you obtain the token, you can call any of the available API services by simply including the token in the Authorization header of each request.

    Prerequisites

    Prior to authenticating your application you will need to complete the following steps:

    1. Sign-up to the Basiq API service
    2. Grab your api key for your application (via the Developer Dashboard)


    Steps to authenticate

    1. Call /token passing in the api key in the Authorization header of the request and Basiq API version you intent to use
    2. The server will validate the key and if everything is successful will issue an access token along with the following properties:
    Property Description
    access_token
    string, readonly
    The generated access token.
    token_type
    string, readonly
    This value will always be `Bearer`.
    expires_in
    number, readonly
    The number of seconds left before the token becomes invalid.

    This access token is the key to making successful requests to the Basiq API. From here on you will need to include this access token in the header when requesting any of the secured resources as follows:
    Authorization: Bearer [access_token]



    Possible Errors

    In the event that something goes wrong a valid HTTP status code and error object will be returned in the body of the response.

       
    invalid_request The request is missing a required parameter, includes an unsupported parameter value (other than grant type) or is otherwise malformed.
    Http 400 Bad Request
    invalid_client Application authentication failed (e.g., unknown application, no authentication included, or unsupported authentication method).
    Status 401 Unauthorized
    invalid_grant The provided Authorization grant (e.g. apiKey) or token is invalid, expired or has been revoked.
    Status 400 Bad Request
    unauthorized_client The authenticated application is not authorized to use this Authorization grant type.
    Status 400 Bad Request
    unsupported_grant_type The Authorization grant type is not supported.
    Status 400 Bad Request

    Testing

    There’s nothing worse than developing against an API with crappy test data. We get that! This is why we have put a lot of effort into ensuring that our test data mimics real production data that your app will consume.

    Connect API

    Create Connection (using test account)

    POST /users/ea3a81/connections HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    Content-Type: application/json
    
    {
      "loginId": "gavinBelson",
      "password": "hooli2016",   
      "institution":{
        "id":"AU00000"
      }
    }
    

    The test data that we provide for the Connect API service (below) has been designed to mimic a real life user. This means that just a like a real user would spend and receive funds throughout the day - our test accounts have been designed to do the same thing. Therefore you should expect to see new transaction records being created throughout the day, and the account balances adjusted accordingly.

    This should give you a good feel for the type of data that you should expect to see for your own customers. The transaction data is completely random, and even we are sometimes surprised by transactions that appear :-)

    L: gavinBelson
    P: hooli2016
    L: jared
    P: django
    L: richard
    P: tabsnotspaces

    Versioning

    Example Request

    POST /token HTTP/1.1
    Authorization: Basic YOUR_API_KEY
    Content-Type: application/x-www-form-urlencoded
    basiq-version: 1.0
    

    Your API version controls the API behaviour you see e.g. what properties you see in responses, what parameters you’re permitted to send in requests etc.

    In order to gain access to the API, you need to pass the appropriate version in HTTP header basiq-version, when exchanging your API key for a token.
    You don't need to pass basiq-version header in any subsequent requests.

    You can check the list of API changes via the API Changelog.

    Errors

    EXAMPLE ERROR OBJECT

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
      "type": "list",
      "correlationId": "bd1183d9-c9d8-11e7-909a-6789bfc80ac5",
      "data": [
        {
          "type": "error",
          "code": "parameter-not-supplied",
          "title": "Required parameter not supplied",
          "detail": "Institution ID  parameter is required.",
          "source": {
            "pointer": "connection/institution/id",
            "parameter": "id"
          }
        }
      ]
    }
    

    The Connect API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, user's credentials are invalid, etc.), and codes in the 5xx range indicate an error with the Connect API's servers (these are rare).

    In addition to returning an appropriate HTTP code the body will also include a JSON formatted error object that provides more details about the specifics of the error. The error object will return the error as an array to indicate multiple errors (where present).

    Attributes  
    correlationId
    string, read-only
    a unique identifier for this particular occurrence of the problem.
    code
    string, read-only
    an application-specific error code, expressed as a string value.
    title
    string, read-only
    a short, human-readable summary of the problem.
    detail
    string, read-only
    a human-readable explanation specific to this occurrence of the problem.
    source
    object, read-only
    an object containing references to the source of the error, optionally including any of the following members:
    • pointer the location to the object or attribute that the error relates to
    • parameter a string indicating which URI query parameter caused the error.

    Error codes

    Below you will find details for our various response codes.

    Code Description
    invalid-credentials Invalid Attribute
    Cannot login to target institution using supplied credentials. Please check credentials and try again.
    resource-not-found Invalid Attribute
    Requested resource is not found. Check details message.
    resource-already-exists Invalid Attribute
    Resource already exists. Check details message.
    unsupported-content-type Invalid Attribute
    Requested content type is not supported.
    unsupported-accept Invalid Attribute
    Accept type is not supported.
    invalid-content Invalid Attribute
    Invalid request content. Check details message.
    parameter-not-supplied Missing Attribute
    Required parameter not supplied. Check details and source message.
    parameter-not-valid Invalid Attribute
    Parameter value is not valid. Check details and source message.
    internal-server-error Server Error
    Internal server error. Please contact support.
    service-unavailable Service Unavailable
    Service is currently unavailable. Please try again later.
    too-many-requests Service Unavailable
    Request rate limit per connection reached. Follow detail message for futher instructions.
    method-not-allowed Not Allowed
    Requested method is not allowed.
    unauthorized-access Unauthorized
    Unauthorized access.
    invalid-authorization-token Unauthorized
    Invalid authorization token. Check details message.
    invalid-authorization-request Unauthorized
    Invalid authorization request. Check details message.

    Users

    Example User Object

    {
      "type": "user",
      "id": "ea3a81",
      "email": "gavin@hooli.com",
      "mobile": "+61410888666",
      "links": {
        "self": "https://au-api.basiq.io/users/ea3a81"
      }
    }
    

    The user object represents an end-user of your application. This object encapsulates all of the financial details of an individual (such as list of accounts and transactions) along with the relationships that they hold with each institution (i.e. connections).

    Use this object to keep your list of users in sync with the Basiq server. Once a user ceases to use your application, it is strongly recommended that the user object is deleted.

    Attributes  
    type
    readonly
    Value is "user".
    id
    readonly
    A string that uniquely identifies the user.
    email
    string, conditional
    The end-users email address.
    mobile
    string, conditional
    The end-users mobile number.

    Create a user

    Definition

    POST /users
    

    Example Request

    POST /users HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer YOUR_ACCESS_TOKEN
    
    {
      "email": "gavin@hooli.com",
      "mobile": "+61410888666"
    }
    

    Example Response

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "type": "user",
      "id": "ea3a81",
      "email": "gavin@hooli.com",
      "mobile": "+61410888666",
      "links": {
        "self": "https://au-api.basiq.io/users/ea3a81"
      }
    }
    

    Use this to create a new user object.

    Arguments  
    email
    conditional
    The end-users email address. Mandatory if mobile is not supplied.
    mobile
    conditional
    The end-users mobile number, supplied in international format +[country-code][mobileno] e.g. +61410888999 . Mandatory if email is not supplied

    Returns

    Returns the user object if the update succeeded. Returns an error if update parameters are invalid (e.g. supplying an empty email address).

    Retrieve a user

    Definition

    GET /users/{user.id}
    

    Example Request

    GET /users/ea3a81 HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "type": "user",
      "id": "ea3a81",
      "email": "gavin@hooli.com",
      "mobile": "+61410888666",
      "connections": {
        "type": "list",
        "data": [
          {
            "type": "connection",
            "id": "aaaf2c3b",
            "links": {
              "self": "https://au-api.basiq.io/users/ea3a81/connections/aaaf2c3b"
            }
          }
        ]
      },
      "links": {
        "self": "https://au-api.basiq.io/users/ea3a81",
        "connections": "https://au-api.basiq.io/users/ea3a81/connections"
      }
    }
    

    Retrieves the details of an existing user. You need only supply the unique user identifier that was returned upon user creation.

    Arguments  
    id
    required
    The identifier of the user to be retrieved.

    Returns

    Returns a user if a valid user ID was provided. Returns an error otherwise.

    Update a user

    Definition

    POST /users/{user.id}
    

    Example Request

    POST /users/ea3a81 HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer YOUR_ACCESS_TOKEN
    
    {
      "email": "gavin@hooli.xyz"
    }
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "type": "user",
      "id": "ea3a81",
      "email": "gavin@hooli.xyz",
      "mobile": "+61410888666",
      "links": {
        "self": "https://au-api.basiq.io/users/ea3a81",
        "connections": "https://au-api.basiq.io/users/ea3a81/connections"
      }
    }
    

    Updates the specified user by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

    Arguments  
    email
    optional
    The end-users email address.
    mobile
    optional
    The end-users mobile number.

    Returns

    Returns the user object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an email address).

    Delete a user

    DELETE /users/{user.id}
    

    Example Request

    DELETE /users/ea3a81 HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 204 No Content
    

    Permanently deletes a user along with all of their associated connection details. You need only supply the unique user identifier that was returned upon user creation.

    Returns

    Returns an empty body if the delete succeeded. Otherwise, this call returns an error in the event of a failure.

    Connections

    Example Connection Object

    {
      "type": "connection",
      "id": "8fce3b",
      "loginId": ...,
      "password": ...,
      "status": "active",
      "lastUsed": "2017-09-28T11:15:09Z",
      "institution": {
        "type": "institution",
        "id": "AU00000",
        "links": {
          "self": "https://au-api.basiq.io/institutions/AU00000"
        }
      },
      "accounts": {
        "type": "list",
        "data": [
          {
            "type": "account",
            "id": "s55bf3",
            "accountNo": "105148119695",
            "name": "Business account",
            "currency": "AUD",
            "balance": "10.00",
            "availableFunds": "0.00",
            "lastUpdated": "2017-09-28T11:15:09.756Z",
            "class": {
                "type": "savings",
                "product": "Saver"
            },
            "status": "available",
            "links": {
              "self": "https://au-api.basiq.io/users/ea3a81/accounts/s55bf3",
              "transactions": "https://au-api.basiq.io/users/ea3a81/transactions?filter=account.id.eq('s55bf3')'"
            }
          },
          {
            "type": "account",
            "id": "ar36y2",
            "accountNo": "533705985043",
            "name": "Choice Account",
            "currency": "AUD",
            "balance": "-10.09",
            "availableFunds": "0.00",
            "lastUpdated": "2017-09-28T11:15:09.756Z",
            "class": {
                "type": "savings",
                "product": "Saver"
            },
            "status": "available",
            "links": {
              "self": "https://au-api.basiq.io/users/ea3a81/accounts/ar36y2",
              "transactions": "https://au-api.basiq.io/users/ea3a81/transactions?filter=account.id.eq('ar36y2')"
            }
          }
        ]
      },
      "links": {
        "self": "https://au-api.basiq.io/users/ea3a81/connections/8fce3b",
        "accounts": "https://au-api.basiq.io/users/ea3a81/accounts?filter=connection.id.eq('8fce3b')",
        "transactions": "https://au-api.basiq.io/users/ea3a81/transactions?filter=connection.id.eq('8fce3b')"
      }
    }
    

    The connection object is created whenever a user links their financial institution with your app. Once a connection is successfully created - you can use it to obtain the user's latest financial data i.e. accounts and transactions - by refreshing the connection.

    Attributes  
    type
    string, read-only
    Value is "connection".
    id
    string, read-only
    A string that uniquely identifies the user connection.
    loginId
    string, required
    User's institution login ID. This value cannot be read.
    password
    string, required
    User's institution password. This value cannot be read.
    securityCode
    string, conditional
    User's institution security code. This value cannot be read.
    status
    enum, read-only
    Indicates the connection status. Possible values include:
    • active the connection is valid (is working!)
    • invalid the connection is no longer valid and requires the user to update their logon details
    lastUsed
    string, optional
    UTC Date and Time of when the connection was last used, in RFC 3339 format.
    institution
    object, read-only
    The institution the connection relates to.
    accounts
    list of objects, read-only
    User's accounts in this institution.
    links
    object, read-only
    A links object containing the following members:
    • self link to the requested connection
    • accounts link to the accounts associated with this connection
    • transactions link to the transactions associated with this connection

    Create a connection

    Definition

    POST /users/{user.id}/connections
    

    Example Request

    POST /users/ea3a81/connections HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    Content-Type: application/json
    
    {
      "loginId": "gavinBelson",
      "password": "hooli2016",
      "institution":{
        "id":"AU00000"
      }
    }
    

    Example Response

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
      "type": "job",
      "id": "61723",
      "links": {
        "self": "https://au-api.basiq.io/jobs/61723"
      }
    }
    

    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

    You can check the status of each step by querying the job resource (returned when the connection is created).

    Arguments  
    loginId
    string, required
    The users institution login ID
    password
    string, required
    The users institution password
    securityCode
    string, conditional
    User's institution security code. Mandatory if required by institution's login process
    institution
    object, required
    Only the id of the institution is required

    Returns

    Returns a created job resource, if the operation succeeded. Returns an error if the post failed (e.g. not supplying required properties).

    Refresh a connection

    Definition

    POST /users/{user.id}/connections/{connection.id}/refresh
    

    Example Request

    POST /users/ea3a81/connections/8fce3b/refresh HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
      "type": "job",
      "id": "61724",
      "links": {
        "self": "https://au-api.basiq.io/jobs/61724"
      }
    }
    

    Use this to retrieve the latest financial data. Similar to when a connection is first created, the refresh resource will initiate the following series of steps to retrieve the latest financial data from the target institution:

    # 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

    You can check the status of each step by querying the job resource (returned when the connection is created).

    Arguments  
    id
    string, required
    The identifier of the connection to be refreshed.

    Returns

    Returns a created job resource, if the operation succeeded. Returns an error if the post failed.

    Refresh all connections

    Definition

    POST /users/{user.id}/connections/refresh
    

    Example Request

    POST /users/ea3a81/connections/refresh HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 202 Accepted
    Content-Type: application/json
    
    {
      "type": "list",
      "data": [
        {
          "type": "job",
          "id": "61725",
          "self": "https://au-api.basiq.io/jobs/61725"
        },
        {
          "type": "job",
          "id": "61726",
          "self": "https://au-api.basiq.io/jobs/61726"
        }
      ]
    }
    

    Use this to refresh of all connections. Check how to refresh a connection for more details.

    Returns

    Returns a list of URLs of the created jobs. Returns an error if the post failed.

    Retrieve a connection

    Definition

    GET /user/{user.id}/connections/{connection.id}
    

    Example Request

    GET /users/ea3a81/connections/8fce3b HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "type": "connection",
      "id": "8fce3b",
      "status": "active",
      "lastUsed": "2017-09-28T11:15:09Z",
      "institution": {
        "type": "institution",
        "id": "AU00000",
        "links": {
          "self": "https://au-api.basiq.io/institutions/AU00000"
        }
      },
      "accounts": {
        "type": "list",
        "data": [
          {
            "type": "account",
            "id": "s55bf3",
            "accountNo": "105148119695",
            "name": "Business account",
            "currency": "AUD",
            "balance": "10.00",
            "availableFunds": "0.00",
            "lastUpdated": "2017-09-28T11:15:09.756Z",
            "class": {
                "type": "savings",
                "product": "Saver"
            },
            "status": "available",
            "links": {
              "self": "https://au-api.basiq.io/users/ea3a81/accounts/s55bf3",
              "transactions": "https://au-api.basiq.io/users/ea3a81/transactions?filter=account.id.eq('s55bf3')"
            }
          },
          {
            "type": "account",
            "id": "ar36y2",
            "accountNo": "533705985043",
            "name": "Choice Account",
            "currency": "AUD",
            "balance": "-10.09",
            "availableFunds": "0.00",
            "lastUpdated": "2017-09-28T11:15:09.756Z",
            "class": {
                "type": "savings",
                "product": "Saver"
            },
            "status": "available",
            "links": {
              "self": "https://au-api.basiq.io/users/ea3a81/accounts/ar36y2",
              "transactions": "https://au-api.basiq.io/users/ea3a81/transactions?filter=account.id.eq('ar36y2')"
            }
          }
        ]
      },
      "links": {
        "self": "https://au-api.basiq.io/users/ea3a81/connections/8fce3b",
        "accounts": "https://au-api.basiq.io/users/ea3a81/accounts?filter=connection.id.eq('8fce3b')",
        "transactions": "https://au-api.basiq.io/users/ea3a81/transactions?filter=connection.id.eq('8fce3b')"
      }
    }
    

    Use this to retrieve details of a specific connection. This request will return back a connection object with most of the fields that were submitted when the connection was first created. The connection object will also return a list of URLs to the associated account, transaction and institution objects.

    The status property of the connection object identifies the state of the connection. Use this to work out if the connection is still valid, or whether to take further action (e.g. if the connection credentials are no longer valid you may ask the user to re-submit their details).

    Arguments  
    id
    required
    The identifier of the connection to be retrieved.    

    Returns

    Returns a connection if a valid connection ID was provided. Returns an error otherwise.

    Update a connection

    Definition

    POST /users/{user.id}/connections/{connection.id}
    

    Example Request

    POST /users/ea3a81/connections/8fce3b HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer YOUR_ACCESS_TOKEN
    
    {
      "password": "Pied-Piper"
    }
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "type": "connection",
      "id": "8fce3b",
      "status": "active",
      "lastUsed": "2017-09-28T11:15:09Z",
      "institution": {
        "type": "institution",
        "id": "AU00000",
        "links": {
          "self": "https://au-api.basiq.io/institutions/AU00000"
        }
      },
      "links": {
        "self": "https://au-api.basiq.io/connections/8fce3b",
        "accounts": "https://au-api.basiq.io/users/ea3a81/accounts?filter=connection.id.eq('8fce3b')",
        "transactions": "https://au-api.basiq.io/users/ea3a81/transactions?filter=connection.id.eq('8fce3b')"
      }
    }
    

    Use this to update the details of a specific connection.

    Attributes  
    id
    string, required
    The identifier of the connection to be updated.
    password
    string, required
    User's (new or old) institution password.
    securityCode
    string, conditional
    User's institution security code.

    Returns

    Returns a connection object if the request succeeded. The returned object will have links to the acquired account and transaction data.

    Otherwise, this call returns an error.

    Delete a connection

    Definition

    DELETE /users/ea3a81/connections/{connection.id}
    

    Example Request

    DELETE /users/ea3a81/connections/8fce3b HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 204 No Content
    

    Permanently deletes a connection. Once the connection has been deleted, all of the associated financial data e.g. accounts and transactions will no longer be accessible.

    Attributes  
    id
    string, required
    The identifier of the connection to be retrieved.

    Returns

    Returns an empty body if the delete succeeded. Otherwise, this call returns an error in the event of a failure.

    List all connections

    Definition

    GET /users/{user.id}/connections
    

    Example Request

    GET users/ea3a81/connections HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "type": "list",
      "data": [
        {
          "type": "connection",
          "id": "8fce3b",
          "status": "active",
          "lastUsed": "2017-09-28T11:15:09Z",
          "institution": {
            "type": "institution",
            "id": "AU00000",
            "links": {
              "self": "https://au-api.basiq.io/institutions/AU00000"
            }
          },
          "links": {
            "self": "https://au-api.basiq.io/connections/8fce3b",
            "accounts": "https://au-api.basiq.io/users/ea3a81/accounts?filter=connection.id.eq('8fce3b')",
            "transactions": "https://au-api.basiq.io/users/ea3a81/transactions?filter=connection.id.eq('8fce3b')"
          }
        }
      ],
      "links": {
        "self": "/users/ea3a81/connections"
      }
    }
    

    Use this collection to retrieve a list of connections. The connections are returned sorted by creation date, with the most recent appearing first.

    Arguments  
    offset
    optional
    Used for paginating results. This represents the offset from the first item in the dataset.
    limit
    optional
    This represents the maximum number of items that may be included in the response (maximum of 100). Note that by default 50 items are returned if this value is not specified.
    sort
    optional
    This list can be sorted by the following properties: created , updated .
    filter
    optional
    This list can be filtered by the following properties: id , status , institution.id.

    Returns

    Returns a paginated list with a data property that contains an array of connections. Each entry in the array is a separate object. If no data is returned, the resulting array will be empty. Otherwise, this call returns an error in the event of a failure.

    Accounts

    Example Account Object

    {
      "type": "account",
      "id": "s55bf3",
      "accountNo": "600000-157441965",
      "name": "Master Savings",
      "currency": "AUD",
      "balance": "356.50",
      "availableFunds": "420.28",
      "lastUpdated": "2017-09-28T13:39:33.144Z",
      "class": {
        "type": "savings",
        "product": "Saver"
      },
      "status": "available",
      "institution": {
        "type": "institution",
        "id": "AU0000",
        "links": {
          "self": "https://au-api.basiq.io/institutions/AU00000"
        }
      },
      "connection": {
        "type": "connection",
        "id": "ea3a81",
        "links": {
          "self": "https://au-api.basiq.io/users/ea3a81/connections/8fce3b"
        }
      },
      "links": {
        "self": "https://au-api.basiq.io/users/ea3a81/accounts/s55bf3",
        "transactions": "https://au-api.basiq.io/users/ea3a81/transactions?filter=account.id.eq('s55bf3')"
      }
    }
    

    The account object represents an account held with a financial institution (e.g. a savings account). You can use this object to retrieve specific account details such as the account number, balance and available funds.

    Attributes  
    type
    string, readonly
    Value is "account".
    id
    string, readonly
    Uniquely identifies the account.
    accountNo
    string, readonly
    Full account number.
    name
    string, readonly
    Account name as defined by institution or user.
    currency
    string, readonly
    The currency the funds are stored in, using ISO 4217 standard.
    balance
    string, readonly
    How much funds are in the account right now - excluding any pending transactions.
    availableFunds
    string, readonly
    Funds that are available to an account holder for withdrawal or other use. This may include funds from an overdraft facility or line of credit, as well as funds classified as the available balance, such as from cleared and existing deposits.
    lastUpdated
    string, readonly
    Timestamp of last update, UTC, RFC 3339 format.
    class
    object, readonly
    Identifies the account type and product as defined by institution.

    Possible values for account type are:
    • credit-card - a credit card account.
    • foreign - a foreign cash account e.g. travelcard.
    • insurance - an insurance account.
    • investment - a investment account.
    • loan - a loan (e.g. personal or business loan).
    • mortgage - a home loan.
    • savings - savings account.
    • term-deposit - a term deposit account.
    • transaction - a keycard or chequing account.
    • unknown
    product
    string, readonly
    A property of class object. Product name as defined by institution.
    status
    enum, readonly
    Indicates the account status. Possible values include:
    • available newest account data is available.
    • unavailable account information is no longer available.
    institution
    object, readonly
    Institution resource the account originated from.
    connection
    object, readonly
    Connection resource that was used to retrieve the account.
    links
    object, read-only
    A links object containing the following members:
    • self link to the requested account
    • transactions link to the transactions associated with this connection

    Retrieve an account

    Definition

    GET /users/{user.id}/accounts/{account.id}
    

    Example Request

    GET /users/ea3a81/accounts/s55bf3 HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "type": "account",
      "id": "s55bf3",
      "accountNo": "600000-157441965",
      "name": "Master Savings",
      "currency": "AUD",
      "balance": "356.50",
      "availableFunds": "420.28",
      "lastUpdated": "2017-09-28T13:39:33.144Z",
      "class": {
          "type": "savings",
          "product": "Saver"
      },
      "status": "available",
      "institution": {
        "type": "institution",
        "id": "AU0000",
        "links": {
          "self": "https://au-api.basiq.io/institutions/AU00000"
        }
      },
      "connection": {
        "type": "connection",
        "id": "ea3a81",
        "links": {
          "self": "/users/ea3a81/connections/8fce3b"
        }
      },
      "links": {
        "self": "https://au-api.basiq.io/users/ea3a81/accounts/s55bf3",
        "transactions": "https://au-api.basiq.io/users/ea3a81/transactions?filter=account.id.eq('s55bf3')"
      }
    }
    

    Use this to retrieve the details of a specific account. This request will return back an account object with the latest data since the last refresh. If you require the latest account details you will need to call the connection refresh resource.

    Arguments  
    id
    string, required
    The identifier of the account to be retrieved.

    Returns

    Returns an account if a valid account ID was provided. Returns an error otherwise.

    List all accounts

    Definition

    GET /users/{user.id}/accounts
    

    Example Request

    GET /users/s55bf3/accounts HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "type": "list",
      "data": [
        {
          "type": "account",
          "id": "s55bf3",
          "accountNo": "600000-157441965",
          "name": "Master Savings",
          "currency": "AUD",
          "balance": "356.50",
          "availableFunds": "420.28",
          "lastUpdated": "2017-09-28T13:39:33.144Z",
          "class": {
              "type": "savings",
              "product": "Saver"
          },
          "status": "available",
          "institution": {
            "type": "institution",
            "id": "AU00000",
            "links": {
              "self": "https://au-api.basiq.io/institutions/AU00000"
            }
          },
          "connection": {
            "type": "connection",
            "id": "ea3a811",
            "links": {
              "self": "https://au-api.basiq.io/users/ea3a81/connections/8fce3b"
            }
          },
          "links": {
            "self": "https://au-api.basiq.io/users/ea3a81/accounts/s55bf3",
            "transactions": "https://au-api.basiq.io/users/ea3a81/transactions?filter=account.id.eq('s55bf3')"
          }
        },
        {
    
        }
      ],
      "links": {
        "self": "https://au-api.basiq.io/users/s55bf3/accounts"
      }
    }
    

    Use this collection to retrieve a list of accounts. Each entry in the array is a separate account object.

    Returns

    Returns a list with a data property that contains an array of accounts. Each entry in the array is a separate object. If no data is returned, the resulting array will be empty. Otherwise, this call returns an error in the event of a failure.

    Transactions

    Example Transaction Object

    {
      "type": "transaction",
      "id": "fx789e",
      "status": "posted",
      "description": "FLIGHT CENTRE CO    BRISB    QL",
      "postDate": "2016-01-01",
      "transactionDate": "",
      "amount": "-139.98",
      "balance": "356.50",
      "bankCategory": "",
      "class": {
        "type": "debit",
        "subclass": [
          {
            "type": "payment",
            "merchant": {
              "type": "merchant",
              "id": "88ab27",
              "created": "2015-09-27T16:23:02Z",
              "updated": "2015-09-27T16:23:02Z",
              "identity": {
                "entityName": "FLIGHT CENTRE TRAVEL GROUP LIMITED",
                "businessName": "FLIGHT CENTRE",
                "businessNumber": "25003377188",
                "status": "active",
                "phoneNumber": {
                  "local": "(07) 3221 4821",
                  "international": "+61 7 3221 4821"
                },
                "website": "https://www.flightcentre.com.au/",
                "operatingHours": {
                  "monday": [
                    {
                      "begin": "09:00",
                      "end": "17:30"
                    }
                  ],
                  "tuesday": [
                    {
                      "begin": "09:00",
                      "end": "17:30"
                    }
                  ],
                  "wednesday": [
                    {
                      "begin": "09:00",
                      "end": "17:30"
                    }
                  ],
                  "thursday": [
                    {
                      "begin": "09:00",
                      "end": "17:30"
                    }
                  ],
                  "friday": [
                    {
                      "begin": "09:00",
                      "end": "12:00"
                    },
                    {
                      "begin": "12:30",
                      "end": "17:30"
                    }
                  ],
                  "saturday": [                
                  ],
                  "sunday": [              
                  ]
                }
              },
              "location": {
                "routeNo": "327",
                "route": "George Street",
                "postalCode": "4000",
                "locality": {
                  "longName": "Brisbane City",
                  "shortName": "Brisbane"
                },
                "administrativeArea2": {
                  "longName": "Brisbane City",
                  "shortName": "Brisbane City"
                },
                "administrativeArea1": {
                  "longName": "Queensland",
                  "shortName": "QLD"
                },
                "country": {
                  "name": "Australia",
                  "code": "AU"
                },
                "formattedAddress": "327 George St Brisbane City QLD 4000 Australia",
                "geometry": {
                  "lat": "-27.4687768",
                  "lng": "153.0216079"
                }
              },
              "classification": {
                "mcc": {
                  "code": "4722",
                  "title": "Travel Agencies and Tour Operations"
                },
                "anzsic": {
                  "division": {
                    "code": "N",
                    "title": "Administrative and Support Services"
                  },
                  "subdivision": {
                    "code": "72",
                    "title": "Administrative Services"
                  },
                  "group": {
                    "code": "722",
                    "title": "Travel Agency and Tour Arrangement Services"
                  },
                  "class": {
                    "code": "7220",
                    "title": "Travel Agency and Tour Arrangement Services"
                  }
                }
              }
            }
          }
        ]
      },
      "institution": {
        "type": "institution",
        "id": "AU00101",
        "links": {
          "self": "https://au-api.basiq.io/institutions/AU00101"
        }
      },
      "connection": {
        "type": "connection",
        "id": "8fce3b",
        "links": {
          "self": "https://au-api.basiq.io/users/ea3a81/connections/8fce3b"
        }
      },
      "account": {
        "type": "account",
        "id": "s55bf3",
        "links": {
          "self": "https://au-api.basiq.io/users/ea3a81/accounts/s55bf3"
        }
      },
      "links": {
        "self": "https://au-api.basiq.io/users/ea3a81/transactions/fx789e"
      }
    }
    

    A transaction object is created whenever money is debited or credited from a particular account.

    Attributes  
    type
    string, readonly
    Value is "transaction".
    id
    string, readonly
    Uniquely identifies the transaction for this connection.
    status
    enum, readonly
    Identifies if a transaction is pending or posted. A pending transaction is an approved debit or credit transaction that has not been fully processed yet (i.e. has not been posted). Find out more about pending transaction and how to deal with them within your app.
    description
    string, readonly
    The transaction description as submitted by the institution.
    postDate
    string, readonly
    Date the transaction was posted (this is the same date that appears on a bank statement). This value is null if the record is pending.
    transactionDate
    string, readonly
    Date that the user executed the transaction. Note that not all transactions provide this value (varies by institution).
    amount
    string, readonly
    Transaction amount. Outgoing funds are expressed as negative values.
    balance
    string, readonly
    Value of the account balance at time the transaction was completed.
    bankCategory
    string, readonly
    Category as defined by the institution itself. Note that not all institutions define this category.
    class
    object, readonly
    Identifies if the transaction is of debit or credit type. This object contains a list of the following types of subclasses:

    Debit Subclasses:
    • bank-fee - a fee incurred by the user from their bank e.g. ATM withdrawal fee.
    • direct-debit - funds directly debited from the user’s bank account.
    • payment - payment made to a merchant.
    • cash-withdrawal - funds withdrawn via atm facility.
    • internal-transfer - funds transferred to an account (within the same connection).
    • external-transfer - funds transferred to an account (outside of the connection).

    Credit Subclasses:
    • refund - funds returned due to refund.
    • direct-credit - funds deposited into an account.
    • interest - interest earned.
    • internal-transfer - funds received from an account (within the same connection)
    • external-transfer - funds received from an account (outside of the same connection)

    Notes:
    • Note that some transactions may be classified into multiple subclasses of the same class, for e.g. when a customer pays a merchant and withdraws cash from the same facility.
    • Debit transactions with a subclass of type payment may also include details of the merchant through which the payment took place. Merchant details may change over time (e.g. businesses may change address) - Basiq retains copies of these changes, and will ensure that the correct details are returned with each transaction record to indicate the validity at the date the payment took place.
    institution
    object, read-only
    The institution this transaction relates to.
    connection
    object, read-only
    The connection this transaction relates to.
    account
    object, read-only
    User's accounts in this institution.
    links
    object, read-only
    A links object containing the following members:
    • self link to the requested transaction

    Retrieve a transaction

    Definition

    GET /users/{user.id}/transactions/{transaction.id}
    

    Example Request

    GET /users/ea3a81/transactions/fx789e HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "type": "transaction",
      "id": "fx789e",
      "status": "posted",
      "description": "FLIGHT CENTRE CO    BRISB    QL",
      "postDate": "2016-01-01",
      "transactionDate": "",
      "amount": "-139.98",
      "balance": "356.50",
      "bankCategory": "",
      "class": {
        "type": "debit",
        "subclass": [
          {
            "type": "payment",
            "merchant": {
              "type": "merchant",
              "id": "88ab27",
              "created": "2015-09-27T16:23:02Z",
              "updated": "2015-09-27T16:23:02Z",
              "identity": {
                "entityName": "FLIGHT CENTRE TRAVEL GROUP LIMITED",
                "businessName": "FLIGHT CENTRE",
                "businessNumber": "25003377188",
                "status": "active",
                "phoneNumber": {
                  "local": "(07) 3221 4821",
                  "international": "+61 7 3221 4821"
                },
                "website": "https://www.flightcentre.com.au/",
                "operatingHours": {
                  "monday": [
                    {
                      "begin": "09:00",
                      "end": "17:30"
                    }
                  ],
                  "tuesday": [
                    {
                      "begin": "09:00",
                      "end": "17:30"
                    }
                  ],
                  "wednesday": [
                    {
                      "begin": "09:00",
                      "end": "17:30"
                    }
                  ],
                  "thursday": [
                    {
                      "begin": "09:00",
                      "end": "17:30"
                    }
                  ],
                  "friday": [
                    {
                      "begin": "09:00",
                      "end": "12:00"
                    },
                    {
                      "begin": "12:30",
                      "end": "17:30"
                    }
                  ],
                  "saturday": [],
                  "sunday": []
                }
              },
              "location": {
                "routeNo": "327",
                "route": "George Street",
                "postalCode": "4000",
                "locality": {
                  "longName": "Brisbane City",
                  "shortName": "Brisbane"
                },
                "administrativeArea2": {
                  "longName": "Brisbane City",
                  "shortName": "Brisbane City"
                },
                "administrativeArea1": {
                  "longName": "Queensland",
                  "shortName": "QLD"
                },
                "country": {
                  "name": "Australia",
                  "code": "AU"
                },
                "formattedAddress": "327 George St Brisbane City QLD 4000 Australia",
                "geometry": {
                  "lat": "-27.4687768",
                  "lng": "153.0216079"
                }
              },
              "classification": {
                "mcc": {
                  "code": "4722",
                  "title": "Travel Agencies and Tour Operations"
                },
                "anzsic": {
                  "division": {
                    "code": "N",
                    "title": "Administrative and Support Services"
                  },
                  "subdivision": {
                    "code": "72",
                    "title": "Administrative Services"
                  },
                  "group": {
                    "code": "722",
                    "title": "Travel Agency and Tour Arrangement Services"
                  },
                  "class": {
                    "code": "7220",
                    "title": "Travel Agency and Tour Arrangement Services"
                  }
                }
              }
            }
          }
        ]
      },
      "institution": {
        "type": "institution",
        "id": "AU00101",
        "links": {
          "self": "https://au-api.basiq.io/institutions/AU00101"
        }
      },
      "connection": {
        "type": "connection",
        "id": "8fce3b",
        "links": {
          "self": "https://au-api.basiq.io/users/ea3a81/connections/8fce3b"
        }
      },
      "account": {
        "type": "account",
        "id": "s55bf3",
        "links": {
          "self": "https://au-api.basiq.io/users/ea3a81/accounts/s55bf3"
        }
      },
      "links": {
        "self": "https://au-api.basiq.io/users/ea3a81/transactions/fx789e"
      }
    }
    

    Retrieves the details of an existing transaction. You need only supply the unique transaction identifier.

    Arguments  
    id
    string, required
    The identifier of the transaction to be retrieved.

    Returns

    Returns a transaction if a valid transaction ID was provided. Returns an error otherwise.

    List all transactions

    Definition

    GET /users/{user.id}/transactions
    

    Example Request

    GET /users/ea3a81/transactions HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "type": "list",
      "data": [
        {
          "type": "transaction",
          "id": "fx789e",
          "status": "posted",
          "description": "FLIGHT CENTRE CO    BRISB    QL",
          "postDate": "2016-01-01",
          "transactionDate": "",
          "amount": "-139.98",
          "balance": "356.50",
          "bankCategory": "",
          "class": {
            "type": "debit",
            "subclass": [
              {
                "type": "payment",
                "merchant": {
                  "type": "merchant",
                  "id": "88ab27",
                  "created": "2015-09-27T16:23:02Z",
                  "updated": "2015-09-27T16:23:02Z",
                  "identity": {
                    "entityName": "FLIGHT CENTRE TRAVEL GROUP LIMITED",
                    "businessName": "FLIGHT CENTRE",
                    "businessNumber": "25003377188",
                    "status": "active",
                    "phoneNumber": {
                      "local": "(07) 3221 4821",
                      "international": "+61 7 3221 4821"
                    },
                    "website": "https://www.flightcentre.com.au/",
                    "operatingHours": {
                      "monday": [
                        {
                          "begin": "09:00",
                          "end": "17:30"
                        }
                      ],
                      "tuesday": [
                        {
                          "begin": "09:00",
                          "end": "17:30"
                        }
                      ],
                      "wednesday": [
                        {
                          "begin": "09:00",
                          "end": "17:30"
                        }
                      ],
                      "thursday": [
                        {
                          "begin": "09:00",
                          "end": "17:30"
                        }
                      ],
                      "friday": [
                        {
                          "begin": "09:00",
                          "end": "12:00"
                        },
                        {
                          "begin": "12:30",
                          "end": "17:30"
                        }
                      ],
                      "saturday": [],
                      "sunday": []
                    }
                  },
                  "location": {
                    "routeNo": "327",
                    "route": "George Street",
                    "postalCode": "4000",
                    "locality": {
                      "longName": "Brisbane City",
                      "shortName": "Brisbane"
                    },
                    "administrativeArea2": {
                      "longName": "Brisbane City",
                      "shortName": "Brisbane City"
                    },
                    "administrativeArea1": {
                      "longName": "Queensland",
                      "shortName": "QLD"
                    },
                    "country": {
                      "name": "Australia",
                      "code": "AU"
                    },
                    "formattedAddress": "327 George St Brisbane City QLD 4000 Australia",
                    "geometry": {
                      "lat": "-27.4687768",
                      "lng": "153.0216079"
                    }
                  },
                  "classification": {
                    "mcc": {
                      "code": "4722",
                      "title": "Travel Agencies and Tour Operations"
                    },
                    "anzsic": {
                      "division": {
                        "code": "N",
                        "title": "Administrative and Support Services"
                      },
                      "subdivision": {
                        "code": "72",
                        "title": "Administrative Services"
                      },
                      "group": {
                        "code": "722",
                        "title": "Travel Agency and Tour Arrangement Services"
                      },
                      "class": {
                        "code": "7220",
                        "title": "Travel Agency and Tour Arrangement Services"
                      }
                    }
                  }
                }
              }
            ]
          },
          "institution": {
            "type": "institution",
            "id": "AU00101",
            "links": {
              "self": "https://au-api.basiq.io/institutions/AU00101"
            }
          },
          "connection": {
            "type": "connection",
            "id": "8fce3b",
            "links": {
              "self": "https://au-api.basiq.io/users/ea3a81/connections/8fce3b"
            }
          },
          "account": {
            "type": "account",
            "id": "s55bf3",
            "links": {
              "self": "https://au-api.basiq.io/users/ea3a81/accounts/s55bf3"
            }
          },
          "links": {
            "self": "https://au-api.basiq.io/users/ea3a81/transactions/fx789e"
          }
        }
      ],
      "links": {
        "self": "https://au-api.basiq.io/users/ea3a81/transactions",
        "next": "https://au-api.basiq.io/users/ea3a81/transactions?next=049fdef3-261d-4587-87e3-a0033e1637a5"
      }
    }
    

    Use this collection to retrieve a paginated list of transactions. The transactions are returned sorted by posted date descending order - with pending transactions appearing first. Transactions are paginated in chunks of 500. Absence of next link means that there are no more pages to retrieve.

    Returns

    Returns a paginated list with a data property that contains an array of transactions. Each entry in the array is a separate object. If no data is returned, the resulting array will be empty. Otherwise, this call returns an error in the event of a failure.

    Institutions

    Example Institution Object

    {
      "type": "institution",
      "id": "AU00000",
      "name": "Hooli Bank",
      "shortName": "Hooli",
      "institutionType": "Test Bank",
      "country": "Australia",
      "serviceName": "Personal Online Banking",
      "serviceType": "Test",
      "loginIdCaption": "Login",
      "passwordCaption": "Password",
      "logo": {
        "type": "image",
        "links": {
          "self": "https://s3-ap-southeast-2.amazonaws.com/basiq-institutions/AU00000.png"
        }
      },
      "links": {
        "self": "https://au-api.basiq.io/institutions/AU00000"
      }
    }
    

    The institution object represents a financial institution (such as a bank, credit union etc). You can use this object to obtain a list of supported institutions or to get general information about each institution.

    Attributes  
    type
    string, readonly
    Value is "institution".
    id
    string, readonly
    A string that uniquely identifies the institution.
    name
    string, readonly
    The full name of the institution.
    shortName
    string, readonly
    Short name of institution.
    institutionType
    enum, readonly
    An enum identifying the institution type. Possible values include:
    • Bank
    • Bank (Foreign)
    • Test Bank
    • Credit Union
    • Financial Services
    country
    string, readonly
    Country in which this institution operates. English short name used by ISO 3166/MA.
    serviceName
    string, readonly
    Name of the supported service (as defined by the institution).
    serviceType
    enum, readonly
    An enum identifying the service type. Possible values include:
    • Personal Banking
    • Business Banking
    • Card Access
    • Test
    loginIdCaption
    string, readonly
    Caption used by institution to request login id.
    passwordCaption
    string, readonly
    Caption used by institution to request password.
    securityCodeCaption
    string, readonly
    Caption used by institution to request security code.
    logo
    object, readonly
    Object that contains URL of institution logo image, returned in PNG format.
    links
    object, read-only
    A links object containing the following members:
    • self link to the requested institution

    Retrieve an institution

    Definition

    GET /institutions/{institution.id}
    

    Example Request

    GET /institutions/AU00000 HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "type": "institution",
      "id": "AU00000",
      "name": "Basiq Test Bank",
      "shortName": "Basiq Test Bank",
      "institutionType": "Test Bank",
      "country": "Australia",
      "serviceName": "Personal Online Banking",
      "serviceType": "Test",
      "loginIdCaption": "Login",
      "passwordCaption": "Password",
      "logo": {
        "type": "image",
        "links": {
          "self": "https://s3-ap-southeast-2.amazonaws.com/basiq-institutions/AU00000.png"
        }
      },
      "links": {
        "self": "https://au-api.basiq.io/institutions/AU00000"
      }
    }
    

    Retrieves the details of an existing institution. You need only supply the institutions unique identifier.

    Arguments  
    id
    string, required
    The identifier of the institution to be retrieved.

    Returns

    Returns an institution if a valid ID was provided. Returns an error otherwise.

    List all institutions

    Definition

    GET /institutions
    

    Example Request

    GET /institutions HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "type": "list",
      "size": 89,
      "data": [
        {
          "type": "institution",
          "id": "AU00000",
          "name": "Basiq Test Bank",
          "shortName": "Basiq Test Bank",
          "institutionType": "Test Bank",
          "country": "Australia",
          "serviceName": "Personal Online Banking",
          "serviceType": "Test",
          "loginIdCaption": "Login",
          "passwordCaption": "Password",
          "logo": {
            "type": "image",
            "links": {
              "self": "https://s3-ap-southeast-2.amazonaws.com/basiq-institutions/AU00000.png"
            }
          },
          "links": {
            "self": "https://au-api.basiq.io/institutions/AU00000"
          }
        },
        null
      ],
      "links": {
        "self": "https://au-api.basiq.io/institutions"
      }
    }
    

    Use this collection to retrieve a list of institutions. Each entry in the array is a separate institution object.

    Jobs

     

    Example Job Object

    {
      "type": "job",
      "id": "61723",
      "created": "2016-06-08T09:10:32.000Z",
      "updated": "2016-06-08T09:14:28.000Z",
      "steps": [
        {
          "title": "verify-credentials",
          "status": "success",
          "result": [
            {
              "type": "link",
              "url": "/users/ea3a81/connections/8fce3b"
            }
          ]
        },
        {
          "title": "retrieve-accounts",
          "status": "success",
          "result": [
            {
              "type": "link",
              "url": "/users/ea3a81/accounts?filter=connection.id.eq(8fce3b)"
            }
          ]
        },
        {
          "title": "retrieve-transactions",
          "status": "in-progress",
          "result": null
        }
      ],
      "links": {
        "self": "/jobs/61723",
        "source": "/users/ea3a81/connections/8fce3b"
      }
    }
    

    Some of the services provided by Basiq are quite resource intensive, and may take a little time to process. To ensure that we provide a pleasant experience to you and your end-users, and that we avoid timeouts of long running connections to our server - we will handle these processes (jobs) asynchronously.

    Asynchronous operations are great as they enable us to return an immediate result when an endpoint is queried, and also enable us to scale the requests optimally behind the scenes.

    When an asynchronous operation is initiated (e.g. refreshing a connection) the Basiq server will create a job resource and return a status code of 202 - Accepted along with the job details (in the body). You can then query the job url to track its progress.


    Tracking the status of a job

    Every step of the job has a status property that depicts its current state. The possible status values for each step are as follows:


    Find out what steps have been completed

    Depending on the job being executed, some jobs will have multiple steps which need to be executed, for e.g. refreshing a connection requires the following steps to be completed:

    1. Establish successful authentication with institution
    2. Fetch latest list of accounts
    3. Fetch latest list of transactions

    You can keep track of the steps that have been completed by observing the results array property. As each step is successfully completed, its status will be updated and a result object with the link to the affected resource will be present. In the event that a step has failed, the result object will contain an embedded error object.

    Attributes  
    type
    readonly
    Value is "job".
    id
    readonly
    A string that uniquely identifies the job.
    created
    readonly
    The date time when the job was created.
    updated
    readonly
    The date time when the job was last updated.
    steps
    readonly
    List of steps that need to be completed. With the following properties:
    • title - Name of the step the job needs to complete.
    • status - Step status: pending, in-progress, success, failed.
    • result - List of URLs of the updated (or created) resources. Otherwise if a step failed contains an error response
    links
    readonly
    Links to the following resources:
    • self - URL of job resource
    • souce - Resource that initiated creation of this Job. For example, for operations on Connection, this is a Connection URL

    Retrieve a job

    Definition

    GET /jobs/{job.id}
    

    Example Request

    GET /jobs/61723 HTTP/1.1
    Authorization: Bearer YOUR_ACCESS_TOKEN
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "type": "job",
      "id": "61723",
      "created": "2016-06-08T09:10:32.000Z",
      "updated": "2016-06-08T09:14:28.000Z",
      "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": "/jobs/61723",
        "source": "/users/ea3a81/connections/8fce3b"
      }
    }
    

    Retrieves the details of an existing job. You need only supply the unique job identifier that was returned upon job creation.

    Arguments  
    id
    required
    The identifier of the job to be retrieved.

    Returns

    Returns a job if a valid job ID was provided. Returns an error otherwise.

    Changelog

    We improve the Basiq platform every day by releasing new features, squashing bugs, and delivering fresh documentation. Here's an account of what's recently happened.

    2018-01-22

    2018-01-18

    2017-12-12