Synci as a SimpleFIN provider

Synci is a SimpleFIN data source. It implements the SimpleFIN protocol, so any SimpleFIN-compatible app can read a user's financial data (accounts, balances, and transactions) from Synci directly. The connection is read-only and scoped to the accounts the user chooses.

If you build or run a finance app

If your app already speaks SimpleFIN, it already works with Synci. There is nothing Synci-specific to build: no partnership, no API keys to request, no Synci SDK. A user creates a Synci destination, copies a standard setup token, and pastes it into the same SimpleFIN screen your app already has. From your side it is an ordinary SimpleFIN source.

If SimpleFIN support is on your roadmap, implementing the spec is all it takes: Synci then becomes a data source your users can pick, for free, the day you ship it.

What Synci brings to your users:

Bank coverage beyond North America. European banks (via GoCardless) and New Zealand banks (via Akahu), so users in those regions can connect the accounts they actually have.

More than checking and savings. Investment/brokerage and crypto-exchange accounts are exposed as SimpleFIN accounts too.

Data users can shape. Transactions reflect the user's Synci bank-account rules (payee cleanup, renaming), so what your app imports is already tidy.

Actual Budget is the officially supported and tested consumer (see the Actual Budget setup guide). Other SimpleFIN-compatible apps (Buckets, Sparky Budget, ZapYeti, EnvelopeBudget, and others) work through the same flow via the generic SimpleFIN destination; see Apps powered by SimpleFIN.

The rest of this page covers the Synci-specific details a consumer needs. For the protocol itself (the request/response format), see the SimpleFIN spec.

Getting a setup token

Open the destination in Synci

Go to Destinations then SimpleFIN (or an app-specific page such as Actual Budget). The page is presentation only; the token it produces works with any SimpleFIN consumer.

Choose which accounts to expose

Share all of them, or a specific selection.

Copy the setup token

Copy the one-time setup token.

The setup token is a Base64-encoded claim URL. It can be claimed once, expires after about 7 days if unused, and can be regenerated from the destination's page (regenerating invalidates the previous token). Treat it as a secret.

Claiming the token

The token exchange follows the standard SimpleFIN flow:

Decode the setup token

Base64-decode the setup token to get a claim URL.

Claim it once

POST the claim URL once. On success you receive an access URL as text/plain:

https://{username}:{password}@api.synci.io/simplefin

The credentials are embedded in the URL. Store the access URL; the setup token is now spent.

Request accounts from then on

Request {access URL}/accounts using HTTP Basic auth built from the embedded username:password.

The host and path come from the token and the access URL, so a consumer never hardcodes them. A claim that has already been used, expired, or been revoked returns a 403 whose body begins with Forbidden.

Access credentials are revocable at any time from the destination's page in Synci. Once revoked, requests return 403.

Fetching accounts

GET {access URL}/accounts returns a SimpleFIN Account Set. It is called in two shapes:

Balances only (account discovery, no transactions):

GET /accounts?balances-only=1

Returns every exposed account with its balances and an empty transactions array.

With transactions:

GET /accounts?start-date={epoch}&end-date={epoch}&pending=1&account={id}&account={id}

start-date / end-date are Unix timestamps in seconds. end-date is exclusive.

pending=1 includes not-yet-posted transactions.

Repeat account={id} to limit the response to specific accounts. Ids not exposed by this connection are ignored.

If start-date is omitted, the response is capped to roughly the last 90 days.

There is no pagination; each call returns a single JSON document.

Response shape

{
    "errors": [],
    "accounts": [
        {
            "org": {
                "domain": "inst-916407839591829.synci.io",
                "sfin-url": "https://api.synci.io/simplefin",
                "name": "DNB"
            },
            "id": "916407839591829",
            "name": "DNB Brukskonto",
            "currency": "NOK",
            "balance": "12345.67",
            "available-balance": "12000.00",
            "balance-date": 1767225600,
            "transactions": [
                {
                    "id": "935986745228429",
                    "posted": 1767139200,
                    "transacted_at": 1767052800,
                    "amount": "-129.00",
                    "description": "REMA 1000 OSLO",
                    "payee": "REMA 1000",
                    "pending": false
                }
            ]
        }
    ]
}

Synci-specific guarantees, beyond the base spec:

Amounts (balance, available-balance, transaction amount) are signed decimal strings with exactly two decimal places. A negative amount is an outflow.

Timestamps (posted, transacted_at, balance-date) are Unix seconds at noon UTC of the relevant calendar date.

Ids (account id, transaction id) are stable across requests, so consumers can safely deduplicate on them.

payee is always present and non-empty.

A pending transaction always carries a transacted_at.

org identifies the underlying institution, not Synci: org.name is the institution's name (for example "DNB") and org.domain is stable and unique per institution. Consumers that group accounts into "banks" by org.domain therefore get one bank per institution, and multiple accounts from the same institution are grouped together.

available-balance is included only when Synci has one for the account.

Limits and behavior

History: roughly 90 days when no start-date is given.

Rate limit: approximately 60 requests per hour per access credential.

Freshness: responses are served from Synci's most recent provider sync, not live from the bank, so balances in particular can lag behind. There is no real-time fetch on request.

Only bank-style account data is exposed (accounts, balances, transactions). No other part of the user's Synci account is reachable through these credentials.

Versioning and stability

Synci advertises SimpleFIN version 1.0, which the protocol's info endpoint reports as {"versions":["1.0"]}. An issued access URL is permanent for the life of the credential. Any breaking change would ship as a new protocol version and new credentials rather than altering an existing access URL, so a working integration keeps working.

Security

All requests are over HTTPS.

Credentials are read-only and scoped to exactly the accounts the destination exposes. If the user shared all accounts, that scope includes accounts they connect to Synci later.

Setup tokens are single-use with an expiry; access credentials are revocable at any time from Synci.

Treat both the setup token and the access URL as secrets.

Synci as a SimpleFIN provider

If you build or run a finance app#

Getting a setup token#

Claiming the token#

Fetching accounts#

Response shape#

Limits and behavior#

Versioning and stability#

Security#