Connections

Create a new financial connection

When creating a new financial connection, Synci will generate an authorization URL (auth_url). You should follow the authorization URL to activate the connection. Once the connection is authorized, Synci automatically fetches the available financial accounts. On an end user's own connection, a first balance and transaction sync then starts as soon as each account is discovered, which is before anything could have configured it: that first sync's depth therefore comes from this connection's max_historical_days (any value up to the institution's maximum is accepted here), not from an account's config.sync_start_date.

POST

/finance/connections

curl --request POST \
  --url https://api.synci.io/api/v1/finance/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "institution_id": 123
}
'

{
  "data": {
    "already_connected": true,
    "financial_connection": {
      "access_valid_for_days": "<string>",
      "accounts_last_synced_at": "<string>",
      "activated_at": "<string>",
      "consent_expires_at": "<string>",
      "created_at": "<string>",
      "enabled": "<string>",
      "financial_accounts": [
        {
          "account_category": "<string>",
          "account_number_masked": "<string>",
          "account_usage": "<string>",
          "balance": {
            "available": "<string>",
            "cleared": "<string>"
          },
          "balances_last_synced_at": "<string>",
          "bban": "<string>",
          "bic": "<string>",
          "cash_account_type": "<string>",
          "cash_balance": {
            "amount": "<string>",
            "currency": "<string>"
          },
          "config": {
            "enrichment": {
              "country": "<string>",
              "enabled": "<string>",
              "provider": "<string>"
            },
            "fields_for_duplicate_filtering": [
              "<string>"
            ],
            "fuzzy_counterparty_matching": "<string>",
            "fuzzy_counterparty_min_chars": "<string>",
            "map_fields": {
              "date": "<string>",
              "description": "<string>",
              "payee": "<string>"
            },
            "pending_settlement_matching": "<string>",
            "pending_settlement_max_days": "<string>",
            "sync_auto": "<string>",
            "sync_balances": "<string>",
            "sync_frequency_in_minutes": "<string>",
            "sync_pending_transactions": "<string>",
            "sync_start_date": "2025-01-01"
          },
          "created_at": "<string>",
          "currency": "<string>",
          "custom_name": "<string>",
          "details": "<string>",
          "details_last_synced_at": "<string>",
          "display_name": "<string>",
          "enabled": "<string>",
          "financial_connection": {},
          "financial_connection_id": "<string>",
          "health": {
            "failure_count": "<string>",
            "integrator_message": "<string>",
            "last_attempt_at": "<string>",
            "status": "<string>",
            "transient_failure_count": "<string>",
            "transient_message": "<string>"
          },
          "iban": "<string>",
          "id": "<string>",
          "institution_id": "<string>",
          "integrator": "<string>",
          "integrator_id": "<string>",
          "linked_accounts": "<string>",
          "meta": "<string>",
          "msisdn": "<string>",
          "name": "<string>",
          "owner_address": "<string>",
          "owner_name": "<string>",
          "product_name": "<string>",

US banks (Array) cannot be connected through the API. Array's consent flow runs as a JavaScript SDK embedded in the page, so there is no authorization URL to send anyone to. This endpoint answers 403 with code: "provider_requires_synci_surface" for any application-authenticated caller, and the connection must be created from the Synci Dashboard or the connection portal instead. Every other provider is unaffected.

Platform partners. Accounts discovered on your connections are created with sync_auto off and nothing is fetched until you ask, because you configure each account after it appears. Send your account config (sync_start_date plus sync_auto: true), or call POST /finance/accounts/{id}/sync, and the first sync runs on your terms. Note that sync_start_date is the depth the backfill works toward rather than a filter on what you receive, so set it to the oldest date you want: history before it is never fetched.

Managed apps. New connections for your users are created in the connection portal, not through this endpoint: called with a managed user's access token it answers 403 with code: "managed_connection_requires_portal". Mint a portal session (POST /managed/v1/users/{id}/portal-sessions) instead. If your app has its own bank picker, pass the chosen institution_id there and the portal starts that institution's consent flow for the user after a short interlude, then returns them to your return URL with connection and status query parameters. That return also works when the bank finishes in its own app and opens it in a different browser tab. To learn of a new connection without relying on the browser coming back at all, subscribe to the connection.activated webhook. To renew a connection the user already has, pass its connection_id instead of institution_id: that keeps the same connection rather than creating a second one.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

access_valid_for_daysinteger | null

Also known as consent lifetime. The number of days Synci should be able to access accounts belonging to this connection. E.g. if this is set to 180 days, you will have to re-authenticate the connection every 180 days. Synci will email you when the expiry date is approaching. <br><br> Use the institutions endpoint (GET /finance/institutions) to find out the maximum access valid for days for an institution.

Required range: 1 <= x

institution_idintegerrequired

The ID of the institution you want to establish a connection with. You can find available institutions under the institutions endpoint (GET /finance/institutions).

integratorenum<string>

The provider a financial connection or account is sourced from: GOCARDLESS (EU/UK banks), AKAHU (NZ banks), ARRAY (US banks, via Array/Array), or SNAPTRADE (brokerages and crypto exchanges). UNKNOWN is used for accounts created manually via the API.


`UNKNOWN` <br/>
`GOCARDLESS` <br/>
`AKAHU` <br/>
`ARRAY` <br/> US banks. Serves depository, liability and investment accounts on one connection, and its transactions arrive already enriched. Connections cannot be created through the API: the consent flow runs as a JavaScript SDK embedded in the page, so there is no authorization URL to send anyone to, and they must be started from the Synci Dashboard or the connection portal.
`SNAPTRADE` <br/>
`DEMO` <br/> Synthetic provider backing Synci's demo banks. No upstream API: consent, accounts, balances and transactions are all generated locally, but they travel the same ProviderHandler / SyncHandler seams as a real provider so a demo connection exercises the real sync jobs, health accounting, expiry ladder, webhooks and transfer links.

Available options: UNKNOWN, GOCARDLESS, AKAHU, ARRAY, SNAPTRADE, DEMO

max_historical_daysinteger | null

The maximum number of days of historical data Synci should be able to fetch. Applies to all accounts belonging to this connection. <br><br> Use the institutions endpoint (GET /finance/institutions) to find out the maximum historical days for an institution.

Required range: 0 <= x

referencestring | null

Optional correlation id stored on the connection — e.g. your own end-user id. Filter connections later with ?filter[reference]=.

Maximum string length: 255

sync_balancesboolean | null

Response

Show child attributes

string

Still need help? Ask the team