Introduction
Changelog
Authentication
Headers
Errors
Rate Limiting
Webhooks
CDR
OAuth 2.0
User
Devices
Addresses
Affordability
Aggregation
Bills
Budgets
Cards
Challenges
CDR
Configuration
Contacts
Events
Goals
KYC
Managed Products
Messages
Pay Day
PayID
Payments
Reports
Statements
Surveys
Calculators
Images
Users
Accounts
Transactions
Financial Passport
Status
Outages
Banking
Common

CDR API

Frollo provide an Australian Consumer Data Right (CDR) compatible API to access aggregated data. This API adheres to a subset of the CDR Data Holder API endpoints to allow retrieval of data in a familiar, industry standard format.

Usage of the API does not mean losing access to Frollo’s data enrichment features. By adhering the CDR extensibility guidelines data enrichment such as categorisation and merchant identification can also be provided using the CDR compatible API.

If you intend to use the full range of Frollo features now or in the future we recommend using our Client API for maximum compatibility and feature availability.

Usage

Using the Frollo CDR compatible API means utilising the CDR endpoint and supplying the correct request headers.

Authenticating requests is done using OAuth2 access tokens.

Headers

A subset of the CDR headers are required to use the CDR compatible API.

Supported Request Headers

A sample set of headers requesting version 3 to 5:

Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8
x-v: 5
x-min-v: 3
x-frollo-v: 2.13
x-fapi-interaction-id: 6ba7b814-9dad-11d1-80b4-00c04fd430c8
Header Field Description Mandatory?
Content-Type Standard HTTP Header. Represents the format of the payload provided in the request. The media type must be set to application/json. Mandatory for PUT and POST calls. Conditional
Accept If specified, the media type must be set to application/json, unless otherwise specified in the resource end point standard. \n\n If set to an unacceptable value the holder must respond with a 406 Not Acceptable. If not specified, or a wildcard (/) is provided, the default media type is application/json. Optional
x-v Version of the API end point requested by the client. Must be set to a positive integer. The holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent.
If all versions requested are not supported then the holder must respond with a 406 Not Acceptable.
Mandatory
x-min-v Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent.
If all versions requested are not supported then the holder must respond with a 406 Not Acceptable.
Optional
x-frollo-v Frollo specific version of extension fields. Should not be used in conjunction with x-min-v. Optional
x-fapi-interaction-id An optional [RFC4122] UUID used as a correlation id. If provided, the data holder must “play back” this value in the x-fapi-interaction-id response header. Optional

Response headers

Header Field Description Mandatory?
Content-Type Standard HTTP Header. Represents the format of the payload returned in the response.
Must be application/json unless otherwise specified in the resource end point standard.
Mandatory
Retry-After Header indicating the time (in seconds) that the client should wait before retrying an operation. The holder should include this header along with responses with the HTTP status code of 429 Too many requests. Optional
x-v The version of the API end point that the holder has responded with. Mandatory
x-fapi-interaction-id An [RFC4122] UUID used as a correlation id. The data holder must set the response header x-fapi-interaction-id to the value received from the corresponding request header or to a new [RFC4122] UUID value if the request header was not provided. Mandatory

See CDR HTTP Headers for more details.

Authentication

Frollo uses the standard OAuth 2.0 bearer token to authenticate individual API requests. All requests requiring authentication should provide the Authorization header.

Authorization header format:

Bearer <ACCESS_TOKEN>

Example:

Authorization: Bearer xxxxx.yyyyy.zzzzz

Requests can be made from a M2M context or using a client token. All APIs are scoped to a user level. See Authentication for details on using APIs from both contexts.

Data Enrichment

To request data enrichment fields be included in the response an additional header must be specified. The format of the data enrichment is based off our Client API versioning scheme. To request the enrichment fields to returned in the response you must specify the Client API version you would like the response formatted in using the x-frollo-v header. See Headers for details on version formats.

Example Request

x-frollo-v: 2.13

Data enrichment fields will then be formatted according to the Get Transaction response for that API version within the frollo-data object.

Example Response

{
	"transactionId": "txn12345",
	...
	"frollo-data": {
		"category": {
			"id": 123,
			"name": "Restaurants",
			"image_url": "https://example.com/image.png"
		},
		"merchant": {
			"id": 456,
			"name": "Hurricanes Bar & Grill",
			"image_url": "https://example.com/image.png"
			...
		}
	}
	...
}

See CDR Extensibility for more details.