Developer Guide

This guide is for programmers who want to create an application that can access a user's financial data. Your application never sees the user's bank account credentials. In summary, this is the flow:

1. A user gets a Setup Token from this server.
2. The user gives the Setup Token to your application.
3. Your application sends the Setup Token to this server and receives an Access URL in return.
4. Your application uses the Access URL to get the user's transaction data from this server.
5. At any point, the user can disable the Access URL.

This server implements the SimpleFIN protocol, versions 1 and 2, so existing SimpleFIN clients work with it. The root URL is https://bridge.familyloop.net/simplefin.

Bash/cURL example

1. Generate a Setup Token

Send your users to https://bridge.familyloop.net/simplefin/create to sign up and generate a token. For testing, here is a ready-to-use demo token (refresh this page to generate another one):

aHR0cHM6Ly9icmlkZ2UuZmFtaWx5bG9vcC5uZXQvc2ltcGxlZmluL2NsYWltL3NiYU1oM1pVY2JtR2JINGhyLTdFNExscQ==

2. Exchange the Setup Token for an Access URL

Base64-decode the token to get a URL, then POST to it. You can only do this once per token; save the Access URL, because the Setup Token will no longer work.

3. Use the Access URL to get data

Make an HTTP GET request to {ACCESS_URL}/accounts. The Access URL carries Basic Auth credentials.

SETUP_TOKEN='aHR0cHM6Ly9icmlkZ2UuZmFtaWx5bG9vcC5uZXQvc2ltcGxlZmluL2NsYWltL3NiYU1oM1pVY2JtR2JINGhyLTdFNExscQ=='
CLAIM_URL="$(echo "$SETUP_TOKEN" | base64 --decode)"
ACCESS_URL=$(curl -H "Content-Length: 0" -X POST "$CLAIM_URL")

curl -L "${ACCESS_URL}/accounts?version=2"

Query parameters

Errors

Responses from /accounts include an array of structured errors in the errlist property (version 2). Always show those errors to your end users. A 403 means access was revoked or the credentials are wrong.

Limits

This service provides daily updates to transaction data. You are expected to make 24 requests or fewer per day, with a little leeway for initial setup. Requests for all accounts have one quota; requests for individual accounts (?account=...) have their own. Going over the limit adds warnings to the errlist array; going far over it disables the Access URL.

The date range of a request (end-date minus start-date) is limited to 90 days. Overlap your date window by about 5 days so you never miss a late-posting transaction.

Python example

import requests
import base64

# 1. Get a Setup Token
setup_token = input('Setup Token? ')

# 2. Claim an Access URL
claim_url = base64.b64decode(setup_token)
response = requests.post(claim_url)
access_url = response.text

# 3. Get some data
scheme, rest = access_url.split('//', 1)
auth, rest = rest.split('@', 1)
url = scheme + '//' + rest + '/accounts'
username, password = auth.split(':', 1)

response = requests.get(url, auth=(username, password), params={'version': '2'})
data = response.json()

for account in data['accounts']:
    print(account['name'], account['balance'])
    for t in account['transactions']:
        print('  ', t['posted'], t['amount'], t['description'])