Access levels

The Open Utilities API supports three read-only levels of access to a provider account: Quick Check, Full Check and Full Check + Ongoing.

The levels of access available vary from provider to provider. Please note that your client application may be limited in which access levels are available. You can determine what is supported using the getProviders() query and the Provider.capabilities data model.

Levels of access

The levels in more detail:

Quick Check

The purpose of this is to return meta data on the end users current provisions as rapidly as possible. It does not include download of documents. The exact data returned varies by sector.

Full Check

This will download the plan information as well as all visible documents. Depending on the provider it can take several minutes to the data to be fully ingested.

Full Check + Ongoing

This will do the same as Full Check but automatically syncs on an ongoing basis. New documents and meta data will be ingested as they become available from the provider.

A client application can either periodically query for new data or can be notified via webhook of new data being available.

Determining access levels available for a provider

You can determine what is supported using the getProviders() query and the Provider.capabilities data model.

The two fields are the automatedDataCollection and quickCheck booleans.

You can either query to see all providers:

query {
  getProviders {
    name
    code
    capabilities {
      automatedDataCollection
      quickCheck
    }
  }
}

Or for a particular provider:

query {
  getProvider(code: "sse_sse") {
    capabilities {
      automatedDataCollection
      quickCheck
    }
  }
}

These values should be interpreted as follows to determine the available access levels:

Level of access	Condition to check for
Quick Check	Available if quickCheck is true
Full Check	Available if automatedDataCollection is true
Full Check + Ongoing	Available if automatedDataCollection is true

Furthermore you can filter the getProviders() query to only return providers matching the desired capabilities using the quickCheckSupported and automatedDataCollectionSupported arguments.

For providers supporting Quick Check:

query {
  getProviders(quickCheckSupported: true) {
    name
    code
  }
}

Or providers supporting Full Check (+ Ongoing):

query {
  getProviders(automatedDataCollectionSupported: true) {
    name
    code
  }
}

Specifying access level

The method for specifying the level of access varies depending on which integration method you are using:

Level of access	Auth Link API	addAccount GraphQL mutation
Quick Check	Specify scope=plan on Authorization Request link	Specify scope: [plan] arg in addAccount() mutation
Full Check	Specify scope=plan documents on Authorization Request link	Specify scope: [plan, documents] arg in addAccount() mutation
Full Check + Ongoing	Specify scope=plan documents offline_access on Authorization Request link	Specify scope: [plan, documents, offline] arg in addAccount() mutation