SimpleFIN
Note: SimpleFIN is only supported for self-hosted instances of monetr, and is not available on the hosted version.
Note: The SimpleFIN integration is currently considered a "beta" integration. There may be bugs and issues with the data connection that lead to unexpected or undesired behaviors. Please report any bugs you have to monetr, though please understand that some bugs may need to be escalated to the SimpleFIN team if the issue is upstream.
SimpleFIN Bridge allows you to connect your self hosted budgeting applications to your bank directly. This way you can automatically get transaction and balance updates directly in your budgeting app. monetr talks to SimpleFIN Bridge directly using a setup token that you create there.
The benefit of SimpleFIN is that it is a low cost way to connect to institutions in the United States and Canada, and one subscription can be used with multiple apps.
You can see if your specific institution is supported here.
Setup Instructions
Sign up for SimpleFIN Bridge
Navigate to https://bridge.simplefin.org and click Get started.
Enter your email address, complete the Verify you are human check and click Send sign-in email. There isn't a separate sign up form, this same form will create your account if you don't have one yet.
Open the sign-in email
After you send the sign-in email you should see the following screen. If this is your first time signing in, it might take a few minutes for the email to arrive.
You'll receive an email from SimpleFIN that looks like this:
Click the link in that email, then click Finish signing in on the page that opens. The link can only be used once, so if you get an error you will need to start the sign in process again.
Start your subscription
SimpleFIN Bridge is a paid service. A subscription lets you connect up to 25 institutions and 25 apps for 15.00 + tax per year. Select the plan you want to proceed. SimpleFIN does not offer refunds and recommends starting with the monthly plan until you are sure that everything works.
Add a connection
After you have signed in you'll need to add a connection in order for SimpleFIN to pull data from your financial institution. Keep in mind that a connection is a single login to an institution and that one connection can include multiple accounts. Click New connection under Financial Institutions on the My Account page to proceed.
Search for your institution and select it, you will be guided through an authentication flow for your specific institution.
Once you have completed the connection you should see it within SimpleFIN Bridge:
Create a setup token
In order for monetr to read the data from SimpleFIN you'll need to create a setup token. Click New app connection under Apps on the My Account page, or you can create one here: https://bridge.simplefin.org/simplefin/create
Enter a name that will help you identify this connection later, like monetr, and click Create Setup Token.
You should now see your setup token:
Click Copy to clipboard to copy the setup token, you will need it for monetr in the next step. This is the only time SimpleFIN will show you this token.
Note: This setup token is sensitive and should be handled carefully. It can only be used once, and whoever uses it first gets access to your account and transaction data. Do not store it in plain text or share it, paste it directly into monetr. If it has already been used, or if monetr fails to finish creating your link, you will need to create a new setup token.
Add SimpleFIN to monetr
SimpleFIN should be enabled by default for all self-hosted instances of monetr, but just in case you don't see it as an option when you go to the setup page you can enable it here: Configure SimpleFIN.
If this is your first link in monetr then you should see the following screen:
Select SimpleFIN and click Continue.
Enter a Budget Name, this will be the name of the link in the monetr sidebar after you have completed your setup. Then paste the setup token that you created earlier into Setup Token. If you skipped ahead, the Get A Setup Token link above that field will take you to SimpleFIN Bridge to create one. monetr will exchange the token for access to SimpleFIN and store that securely in order to periodically sync your data.
Click Next once you are ready to continue.
Select accounts to sync
monetr will take a few seconds to pull some basic account information, after which you should see the following screen:
You can now decide which accounts in SimpleFIN should be pulled into monetr on this link. By default all accounts are enabled. You can disable accounts you do not want to sync with monetr here.
If SimpleFIN had a problem with any of your connections, the messages from SimpleFIN will be shown on this screen.
To complete the setup process, click Continue.
Finish setup
monetr will take a few moments to pull in the account data. You can safely navigate away from this page while it is loading, however it will tell you when it is finished pulling in your data.
You can click Continue here to be automatically redirected to one of your new accounts.
Use monetr
That's it! You now have your institutions data syncing with monetr automatically!
Syncing
monetr checks for SimpleFIN links that need to be synced every hour, and will fetch data for each link about every 6 to
7 hours. The exact cron schedule that monetr uses is 0 47 * * * *. SimpleFIN Bridge is intended to provide daily
updates, so new transactions will usually show up about once a day.
You can also trigger a sync yourself with Manually Resync in the sidebar or Sync Now on the link's page, but only once every 2 hours. SimpleFIN allows about 24 requests per day, and going over that limit can get your access disabled. Manual syncs and setup both count towards that limit.
Each sync asks SimpleFIN for the last 90 days of transactions, so the first sync will import up to 90 days of history. monetr will only append transactions, once a transaction has been created in monetr it will not be modified again. At the moment pending transactions will not be imported at all.
Errors
If SimpleFIN reports a problem with one of your connections, the message from SimpleFIN will be shown on the link's page.
If SimpleFIN stops accepting monetr's requests then the link will show as Needs Attention and monetr will stop syncing it automatically.
- If your SimpleFIN subscription needs payment, fix that in SimpleFIN Bridge and then click Sync Now on the link's page.
- If access was revoked or disabled, you will need to remove the link in monetr and set it up again with a new setup token.
Removing a SimpleFIN link
Note: Removing a SimpleFIN link in monetr does not disable monetr's access in SimpleFIN Bridge, SimpleFIN doesn't provide a way for monetr to do that for you. After you remove the link, disable monetr's access in your SimpleFIN Bridge account as well.
To do that, go to the My Account page in SimpleFIN Bridge and click Delete on the app that monetr is setup to use.
Nuances
Currently there are a few nuances of the SimpleFIN integration while it is still in beta.
- Credit and loan accounts have balances that show as negative at the moment.
- Pending transactions are not currently synced with monetr.
- All accounts default to a "checking account" once they are imported into monetr. You can change the account type from the account's settings page.
- Only the last 90 days of transactions are available when you first connect an account.
- Accounts that use a custom currency instead of a standard currency code, such as points, are skipped.
Future Work
- Show credit and loan account balances correctly.
- Add support for adding another SimpleFIN account after a connection is already setup.
- Add support for pending transactions.
- Add support for using a new setup token on an existing link.
Doing this over the API
SimpleFIN connections can be set up and synced over the REST API. See the SimpleFIN API.