SIP Integration Guide - Management API

This guide will show how to integrate the Frollo Software Integration Platform (SIP) Management API to your platform and load users, accounts and transaction data in and optionally retrieve enriched data back.

  1. Setup Platform
  2. User Management
    1. Create User
  3. Adding Historical Financial Data
    1. Create an Account
    2. Create Bulk Transactions
  4. Adding & Updating Realtime Financial Data
    1. Create a Transaction
    2. Update Transactions
  5. Retrieving Enriched Data
    1. Receive Webhook Events
    2. Fetch Transactions

Setup Platform

The first step is to make sure you have a set of credentials to access the Management API. We recommend using the Client Credential OAuth2 grant type but API key can also be used. See Authentication for more details.

  • Client ID - Client ID to be used by your platform to request an access token
  • Client Secret - Client Secret to be used by your platform to request an access token

User Management

Next we need to create a user in the Frollo platform to associate user’s financial data. All data within the Frollo system will be tied back to this User object allowing you to then fetch data based on an internal or external identifier.

Create User

The Create User endpoint on the Management API should be used to create the user. Make sure a suitable unique external identifier is used to aid lookup of the user later.

Optionally fields such as email and phone number can be sent to aid customer service lookup in the future.

Example request:

{
	"external_id": "D28D21C2-E607-46E4-9431-73EF9F4D608B",
	"first_name": "John",
	"last_name": "Smith",
	"email": "john.smith@example.com",
	"mobile_number": "0400111222",
	"primary_currency": "AUD"
}

Once the user has been created successfully you will receive a payload including the Frollo User ID - this should be saved as it will be needed to reference other APIs in a User context.

Example response:

{
    "id": 22788,
    "external_id": "D28D21C2-E607-46E4-9431-73EF9F4D608B",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "primary_currency": "AUD"
}

Adding Historical Financial Data

To give the users the best experience and allow them to start gaining the full advantage of the Frollo platform’s features we recommend loading in at least 90 days of historical transactions. More will allow a user a richer experience however so up to 2 years or more of historical transaction data can be loaded into the Frollo platform.

Transactions loaded into the Frollo platform need to be associated with an Account object so the first step is to create accounts to represent the user’s bank, credit card, investment and other types of accounts.

Create an Account

The Create Account endpoint on the Management API should be used to create the user’s financial accounts. An external identifier can be used to reference this account once created. In the case of Joint Accounts see the Create Account endpoint documentation for more information on how to link multiple users to one account.

The balance, available balance and any other balances/amounts should be provided and updated regularly to Frollo. The fields container and account_type are also important to ensure theses are accurate as certain functionality will behave differently depending on the account, e.g. and account_type of savings will have different insights to a regular transaction (or bank) account_type. Usage of the account_number and account_name fields can aid a customer in identifying their account but are not required.

Example request:

{
	"users": [
        {
            "user_id": 22788,
            "role": "owner"
        }
    ],
    "external_id": "224F30BB-9BF8-4D5F-9AE0-8C7714FB4AD8",
	  "bsb": "100200",
    "account_number": "12345678",
    "account_name": "Transaction Account",
    "container": "bank",
    "account_type": "bank",
    "current_balance": {
        "amount": "1000.00",
        "currency": "AUD"
    },
    "available_balance": {
        "amount": "950.00",
        "currency": "AUD"
    }
}

Once the Account has been created the id should be retained so transactions can then be associated with this Account.

Example response:

{
	"id": 393466,
	"users": [
        {
            "user_id": 22788,
            "role": "owner"
        }
    ],
    "external_id": "224F30BB-9BF8-4D5F-9AE0-8C7714FB4AD8",
	  "bsb": "100200",
    "account_number": "12345678",
    "account_name": "Transaction Account",
    "container": "bank",
    "account_type": "bank",
    "current_balance": {
        "amount": "1000.00",
        "currency": "AUD"
    },
    "available_balance": {
        "amount": "950.00",
        "currency": "AUD"
    }
}

Create Bulk Transactions

Now we have User and Account objects created on the Frollo platform bulk loading of transaction data can occur. Using the Bulk Create Transactions endpoint we can load in batches of transactions up to 500 at a time.

Transactions created using this endpoint are created immediately and will have IDs returned. Enrichment then occurs asynchronously and an event will be sent to the Webhook Events API indicating enrichment has been completed and the updated transaction can be fetched.

To get the best enrichment and experience for the end user it is important to provide as many of the individual data fields as possible. Fields and objects such as type, merchant, and biller are important to populate with as much detail as possible.

Please note that any duplicate transactions sent to this API (identified by conflicting external_id properties) will result in all transactions in that payload being rejected.

Example request:

[
	{
		"external_id": "AAA4C899-B1F8-48F4-A7C5-1A65FCCE1BC6",
		"account_id": 393466,
	  "container": "bank",
	  "base_type": "credit",
	  "transaction_status": "posted",
	  "transaction_date": "2021-04-20",
		"posted_date": "2021-04-20",
	  "currency": "AUD",
	  "amount": "5000.00",
	  "original_description": "Transfer from ACME Inc. - Payroll",
		"reference": "Payroll",
		"payer": "ACME Inc",
		"payee": "Mr John Smith",
		"type": "transfer_incoming"
	},
	{
		"external_id": "CBFCA4C8-34D6-441E-91FE-AA7F2743CF77",
		"account_id": 393466,
	  "container": "bank",
	  "base_type": "debit",
	  "transaction_status": "pending",
	  "transaction_date": "2021-04-22",
	  "currency": "AUD",
	  "amount": "-43.12",
	  "original_description": "Visa Purchase - Receipt 123456 - Coles 0710",
		"merchant": {
			"name": "Coles 0710",
			"category_code": 5411,
			"country_code": "AU",
			"mid": 652,
			"tid": 762
		},
		"type": "payment"
	},
	{
		"external_id": "E6B2F72F-B536-4968-9AAF-DFB605637DEE",
		"account_id": 393466,
	  "container": "bank",
	  "base_type": "debit",
	  "transaction_status": "posted",
	  "transaction_date": "2021-04-21",
		"posted_date": "2021-04-22",
	  "currency": "AUD",
	  "amount": "-313.28",
	  "original_description": "BPAY Bill Payment - Receipt 123456 - To AGL 9723646737373",
		"reference": "Gas Bill",
		"biller": {
			"code": "9723646737373",
			"name": "AGL",
			"crn": "83574785843858345"
		},
		"type": "payment"
	}
]

You will then receive the created transaction IDs and enrichment will start asynchronously.

Example response:

[
	{
		"id": 728822,
		"external_id": "AAA4C899-B1F8-48F4-A7C5-1A65FCCE1BC6",
		"account_id": 393466,
	  "container": "bank",
	  "base_type": "credit",
	  "transaction_status": "posted",
	  "transaction_date": "2021-04-20",
		"posted_date": "2021-04-20",
		"amount": {
			"currency": "AUD",
			"amount": "5000.00"
		},
		"description": {
			"original": "Transfer from ACME Inc. - Payroll"
		},
		"category_name": "Uncategorised",
		"merchant_name": "Unknown",
		"reference": "Payroll",
		"payer": "ACME Inc",
		"payee": "Mr John Smith",
		"type": "transfer_incoming",
		"included": true
	},
	{
		"id": 728823,
		"external_id": "CBFCA4C8-34D6-441E-91FE-AA7F2743CF77",
		"account_id": 393466,
	  "container": "bank",
	  "base_type": "debit",
	  "transaction_status": "pending",
	  "transaction_date": "2021-04-22",
		"amount": {
			"currency": "AUD",
			"amount": "-43.12"
		},
		"description": {
			"original": "Visa Purchase - Receipt 123456 - Coles 0710"
		},
		"category_name": "Uncategorised",
		"merchant_name": "Unknown",
		"type": "payment",
		"included": true
	},
	{
		"id": 728824,
		"external_id": "E6B2F72F-B536-4968-9AAF-DFB605637DEE",
		"account_id": 393466,
	  "container": "bank",
	  "base_type": "debit",
	  "transaction_status": "posted",
	  "transaction_date": "2021-04-21",
		"posted_date": "2021-04-22",
		"amount": {
			"currency": "AUD",
			"amount": "-313.28"
		},
		"category_name": "Uncategorised",
		"merchant_name": "Unknown",
		"description": {
			"original": "BPAY Bill Payment - Receipt 123456 - To AGL 9723646737373"
		},
		"reference": "Gas Bill",
		"type": "payment",
		"included": true
	}
]

Adding & Updating Realtime Financial Data

After a user’s historical financial data has been loaded into the Frollo platform realtime data should be added to ensure features work with the latest data. This involves adding new transactions as they occur and updating existing transactions as they transition from pending to posted.

Create a Transaction

Using the Create Transaction endpoint on the Management API a transaction can be created and enriched in realtime on the Frollo platform. Additionally running available_balance and current_balance fields can be used to update the balances on the Account object at the same time.

Example request:

{
	"external_id": "CBFCA4C8-34D6-441E-91FE-AA7F2743CF77",
	"account_id": 393466,
	"container": "bank",
	"base_type": "debit",
	"transaction_status": "pending",
	"transaction_date": "2021-04-22",
	"currency": "AUD",
	"amount": "-43.12",
	"original_description": "Visa Purchase - Receipt 123456 - Coles 0710",
	"merchant": {
		"name": "Coles 0710",
		"category_code": 5411,
		"country_code": "AU",
		"mid": 652,
		"tid": 762
	},
	"type": "payment"
}

You will then receive the immediately enriched transaction response.

Example response:

{
	"external_id": "CBFCA4C8-34D6-441E-91FE-AA7F2743CF77",
	"account_id": 393466,
	"container": "bank",
	"base_type": "debit",
	"transaction_status": "pending",
	"transaction_date": "2021-04-22",
	"currency": "AUD",
	"amount": {
			"currency": "AUD",
			"amount": "-43.12"
		},
	"running_balance": "5000.00",
	"available_balance": "4956.88",
	"original_description": "Visa Purchase - Receipt 123456 - Coles 0710",
	"category_name": "Groceries",
	"merchant_name": "Coles",
	"type": "payment",
	"included": true
}

Updating Transactions

In some cases transactions may need to be updated or deleted. This could occur when a transaction moves from pending to posted status or a hold is removed from a card. The Update Transaction, Bulk Update Transactions, and Delete Transaction endpoints on the Management API can be used to manage this.

When updating the transaction you will most likely need to provide the transaction_status, posted_date and amount to ensure the new data is provided for the transacion.

Example request:

{
	"transaction_status": "posted",
	"posted_date": "2021-04-23",
	"amount": "-43.12",
	"running_balance": "4956.88"
}

Retrieving Enriched Data

Finally once data is loaded into Frollo you can optionally retrieve the enriched transaction data once it has been categorised or respond to other changes to the transaction such as a user recategorising. To do this you will need to observe events on your Events endpoint on the Webhooks API and then fetch the transactions using List Transactions.

Receive Webhook Events

When a transaction is updated an event will be sent to your webhook Events endpoint indicating which transaction IDs have been changed. See Webhooks for more details on implementing the webhooks API and authentication.

The event T_UPDATED will be sent to your endpoint with the Transaction IDs modified. After receiving this you can use the array of IDs to then fetch just those updated events.

Example payload:

{
  "common": {
    "eventKey": "T_UPDATED",
    "state": "triggered",
    "userId": 22788,
    "accountId": 45456,
    "externalUserId": "D28D21C2-E607-46E4-9431-73EF9F4D608B",
    "userEventId": 9112789,
    "firstName": "John"
  },
  "payload": {
		"TRANSACTION_IDS": [
      728822,
      728823,
      728824
    ]
  }
}

Fetch Transactions

The final step is to fetch the updated transaction data. The List Transactions endpoint on the Management API can be filtered by Transaction IDs to return transactions for that user. Transactions are paginated and will be returned in batches of up to 500 at a time.

Example request:

GET /api/admin/transactions?transaction_ids=728822,728823,728824

Example response:

{
  "data": [
    {
      "id": 1,
      "account_id": 1,
      "base_type": "credit",
      "status": "posted",
      "transaction_date": "2016-10-09",
      "post_date": "2016-10-10",
      "amount": {
        "amount": "1635.44",
        "currency": "AUD"
      },
      "description": {
        "original": "0150 Amazon  Santa Ana CA 55.73USD",
        "user": "New Toy",
        "simple": "Amazon Purcahse"
      },
      "budget_category": "income",
      "category_id": 1,
      "category_name": "Groceries",
      "category_image_url": "https://logo.png",
      "merchant": {
        "id": 1,
        "name": "Woolworths",
        "phone": "(02) 5689 3423",
        "website": "https://www.woolworths.com.au",
        "mage_url": "https://woolworths.png",
        "location": {
          "formatted_address": "10 Falcon St, Crows Nest NSW 2065, Australia",
          "line_1": "10 Falcon St",
          "line_2": "Suite 2 Level 3",
          "line_3": "Building 2 MLC",
          "suburb": "Crows Nest",
          "state": "NSW",
          "postcode": 2065,
          "country": "Australia",
          "latitude": -33.827499,
          "longitude": 151.201699
        }
      },
      "memo": "test",
      "included": true,
      "bill_id": 1,
      "goal_id": 1,
      "bill_payment_id": 1,
      "user_tags": [],
      "biller": {
        "code": "BPAY code",
        "name": "BPAY Biller name",
        "crn": "Customer Reference Number",
        "apca_number": "Sender APCA Number"
      },
      "payee": "Receiver of funds",
      "payer": "Sender of funds",
      "type": "The type of the transaction e.g. interest_charged"
    }
  ],
  "paging": {
    "cursors": {
      "before": "1577647183_278049",
      "after": "1577647183_278048"
    },
    "previous": "api/v2/aggregation/transactions/?before=1577647183_278049",
    "next": "api/v2/aggregation/transactions/?after=1577647183_278048",
    "total": 60
  }
}