How it works
SimpleFIN uses a setup token system to establish secure access to your bank accounts:- Obtain a setup token from SimpleFIN
- Sure claims the setup token to get an access URL with embedded credentials
- The access URL is used to fetch account data, balances, and transactions
- Data syncs automatically to keep your information current
Setting up SimpleFIN
To connect your US bank accounts:- Sign up for a SimpleFIN account at simplefin.org
- Generate a setup token from your SimpleFIN dashboard
- In Sure, provide the setup token
- Sure will claim the token and establish access to your accounts
Setup token claiming
The setup token is a base64-encoded claim URL. When you provide it to Sure:- Sure decodes the token to get the claim URL
- Makes a POST request to claim the access URL
- Receives an access URL with HTTP Basic Auth credentials embedded
- Uses this access URL for all subsequent API requests
Features
Account syncing
- Account listing: View all connected accounts with current balances
- Transaction history: Import transactions with date range filtering
- Pending transactions: Optional support for pending transactions (varies by institution)
- Multiple accounts: Connect multiple bank accounts from different institutions
Date range filtering
When syncing transactions, you can specify:- Start date: Fetch transactions from this date forward
- End date: Fetch transactions up to this date
- Pending flag: Include or exclude pending transactions
Reliability features
Sure’s SimpleFIN integration includes automatic retry logic:- Exponential backoff for transient network failures
- Up to 3 retry attempts for network errors
- Handles temporary connection issues gracefully
- Prevents sync failures from intermittent network problems
API structure
SimpleFIN uses a simple REST API with embedded authentication:- POST /claim: Exchange setup token for access URL
- GET /accounts: Fetch all accounts with balances and transactions
- GET /info: Get server information
API reference
For detailed protocol documentation, see the SimpleFIN Protocol.Pricing
SimpleFIN is a paid service, but typically more affordable than alternatives like Plaid. Check simplefin.org for current pricing.Limitations
- US-focused: Primarily supports US financial institutions
- Setup token security: Setup tokens can only be claimed once and may expire
- Pending transactions: Not all institutions return pending transactions, even when requested
- Rate limits: Subject to SimpleFIN API rate limits
- Access URL validity: Access URLs can be revoked or expire (returns 403 error)
Troubleshooting
Duplicate accounts with the same name
If you have two accounts at the same institution with identical display names (for example, two accounts both named “CHECKING (0001)”), Sure’s sync logic previously could confuse them — the unlinked account would silently steal the linked account’s connection, merge in its transactions, and overwrite its balance on every sync. This has been fixed. Sure now tracks each account by its upstream account ID rather than by display name alone. Ambiguous same-name matches are skipped rather than resolved incorrectly. If you were affected, re-syncing after upgrading to the fixed version will restore the correct linkage.Setup token issues
If you receive a 403 error when claiming a setup token:- The token may have already been used
- The token may have expired
- The token may have been compromised
Missing pending transactions
Some institutions don’t return pending transactions even when thepending=1 parameter is set. This is a limitation of the institution’s data feed, not a bug in SimpleFIN or Sure.
Network errors
If you experience intermittent sync failures:- Sure automatically retries failed requests up to 3 times
- Network errors are logged for troubleshooting
- Manual sync attempts may succeed where automatic syncs fail