Partner integration guide

Synci lets your application offer bank connections to your own end users without those users ever creating a Synci account. Your backend talks to the Synci API server-to-server; your users authorize their bank through a hosted consent flow; the resulting accounts, balances, and transactions are available to your application through the API.

This guide covers everything specific to the partner (client credentials) integration. For full endpoint schemas, request/response shapes, and the rest of the API surface, see the API Reference.

Base URL   https://api.synci.io/api/v1
Token URL  https://api.synci.io/oauth/token

How it works

Role	Who	Responsibility
Your application	You	Owns the end-user relationship, stores their consent to your terms, correlates Synci connections to your users
Synci	Us	Open banking layer: consent orchestration, data retrieval, normalization, storage, API
Provider (GoCardless)	Bank data provider	Hosts the bank consent session and supplies the raw bank data

Every bank connection your integration creates lives in your Synci partner account. Synci does not model your end users: you correlate connections to your users with the reference field (see below). One connection represents one authorization at one bank; a single end user can have several.

Getting access

Partner apps are provisioned by Synci; there is no self-serve signup. When onboarding completes you receive:

a Client ID (public identifier),

a Client Secret, shown once. Store it in your secret manager; it cannot be retrieved again.

your end-user callback URL registered with us: where users land after bank consent (changeable on request).

Keep the secret server-side only. It must never reach a browser or mobile app. If it leaks, rotate it from your Synci dashboard (Developers → your app → Rotate secret) or contact us. The old secret stops working immediately.

Authentication

Exchange your credentials for an access token using the OAuth 2.0 client_credentials grant:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1..."
}

Then send the token on every API call:

Things to know:

Tokens live for 1 hour and there is no refresh token: request a new one with your credentials when the old one expires (or shortly before). Cache the token; do not mint one per request.

The token has full access to your partner account's data. There are no scopes to request.

A 401 means the token is missing, expired, or revoked. Mint a fresh one and retry.

Connecting a bank account

1. Pick an institution

Browse the institution catalogue (public endpoint) and present a picker to your user:

Partner integrations currently support GoCardless institutions (EU + UK banks). Requesting an institution from another provider returns 403 provider_not_allowed_for_platform.

2. Create the connection

Field	Required	Description
`institution_id`	yes	From the institutions endpoint
`integrator`	no	Defaults to `GOCARDLESS`
`reference`	no	Your correlation id for this connection, typically your own user id. Echoed back on the callback and filterable later. Max 255 characters.
`max_historical_days`	no	How much transaction history to request (institution-capped)
`access_valid_for_days`	no	Consent lifetime (institution-capped, typically up to 180 days)

The response contains the connection and an auth_url:

{
  "data": {
    "auth_url": "https://api.synci.io/connect/aBcD...",
    "financial_connection": {
      "id": "945400000000001",
      "status": "PENDING_AUTHORIZATION",
      "reference": "your-user-123"
    }
  }
}

3. Send your user to `auth_url`

Redirect (or open a browser for) the end user. They see a brief Synci-branded page ("{Your app} uses Synci as its open banking layer; bank connections are provided by GoCardless") and are forwarded to the GoCardless consent flow, where they pick their bank credentials and approve access.

The auth_url is valid for 60 minutes and single-flow: create a fresh connection if the user abandons and retries later.

Create one connection per authorization attempt. Don't reuse links across users or sessions.

4. Receive the user on your callback URL

After consent (or failure), Synci redirects the user to your registered callback URL with query parameters:

https://yourapp.example/banking/callback?status=SUCCESS&connection=945400000000001&reference=your-user-123

Parameter	Present	Description
`status`	always	`SUCCESS`, or an error code (table below)
`connection`	on success	The Synci connection id
`reference`	when set at creation	Your correlation id, echoed back
`message`	on most errors	Human-readable detail

Treat status=SUCCESS as the signal to fetch the connection's accounts and continue your onboarding. Any other value is terminal for that attempt: create a new connection to retry.

`status`	Meaning
`SUCCESS`	Connection authorized; accounts are syncing
`USER_CANCELLED_SESSION`	The user abandoned the consent flow
`USER_SESSION_REJECTED`	The user rejected the consent
`NO_ACCOUNTS_CONNECTED`	Consent completed but no accounts were shared
`INSTITUTION_UNAVAILABLE`	The bank is temporarily unavailable
`INSTITUTION_TIMEOUT_ERROR`	The bank timed out during consent
`INSTITUTION_TECHNICAL_ERROR`	The bank reported a technical failure
`GOCARDLESS_TECHNICAL_ERROR`	The provider reported a technical failure
`CONSENT_LINK_REUSED` / `REQUISITION_LINK_REUSED`	An old `auth_url` was opened again; create a fresh connection
`SSN_VERIFICATION_FAILED`	The bank's identity verification failed
`SYNCI_ERROR` / `UNKNOWN_ERROR`	Something failed on our side. Retry with a new connection, or contact us

Working with the data

Accounts (with balances) sync automatically once a connection is authorized. Transactions for an account are fetched once you request them:

After the first sync, connected accounts are kept up to date on Synci's sync schedule.

Filters you'll use most (see the API Reference for the full set):

Endpoint	Filter	Behavior
`GET /finance/connections`	`filter[reference]=a,b`	Exact match, comma-separated for multiple
`GET /finance/connections`	`filter[search]=dnb`	Partial, case-insensitive, over institution name + reference
`GET /finance/connections`	`filter[status]=CONNECTED`	Lifecycle status
`GET /finance/transactions`	`filter[reference]=a,b`	Transactions whose connection carries the reference
`GET /finance/transactions`	`filter[booking_date_after]=2026-01-01`	Date bounds (`_before` too)

Webhooks save you from polling: register an endpoint with POST /v1/webhooks and subscribe to bank-data events (new transactions, connection health changes, and more; GET /v1/webhooks/events lists the catalogue). See the webhooks guide for signatures and retries.

Connection lifecycle

State	Meaning
`PENDING_AUTHORIZATION`	Created, waiting for the user to complete consent
`CONNECTED`	Live and syncing
`DISABLED`	Syncing stopped (by you, or after repeated failures)
`EXPIRED`	The bank consent lapsed; reauthorize to resume
`REVOKED`	Access was withdrawn at the bank/provider side
`ERROR`	Consent failed or the connection broke (see `status_message`)

Bank consents expire under PSD2, typically after 90 to 180 days (see access_valid_for_days on the connection). Before expiry, re-run consent with PUT /finance/connections/{id}/reauthorize: it returns a fresh auth_url for the same connection, and the same callback contract applies. Synci also emails the account holder ahead of expiring consents.

To stop syncing a connection, PUT /finance/connections/{id}/disable; to remove it and its data, DELETE /finance/connections/{id}.

Rate limits

Partner tokens have their own budget of 300 requests per minute (higher limits on request). Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; a 429 means back off until the window resets. Per-account sync triggers are additionally rate-limited per account.

Errors

Synci uses conventional HTTP status codes with a JSON body:

{ "message": "This provider is not available to platform clients.", "code": "provider_not_allowed_for_platform" }

Status	When
`401`	Missing/expired/revoked token; mint a new one
`403` + `provider_not_allowed_for_platform`	Institution outside the supported provider set
`403`	Your app has been suspended; contact us
`404`	Resource doesn't exist or isn't yours
`422`	Validation failed; the body lists per-field errors
`429`	Rate limit exceeded

Billing

Partner usage is invoiced monthly per your agreement, metered on:

active connections: connections enabled at any point during the month,

enriched transactions: transactions enriched with counterparty and category data during the month (if enrichment is part of your agreement).

Your invoice reflects the unit prices in your agreement; usage questions or statements are available from your account contact.

Support

API reference: docs.synci.io

Status page: status.synci.io

Your account contact, or help.synci.io

Partner integration guide

How it works#

Getting access#

Authentication#

Connecting a bank account#

1. Pick an institution#

2. Create the connection#

3. Send your user to auth_url#

4. Receive the user on your callback URL#

Working with the data#

Connection lifecycle#

Rate limits#

Errors#

Billing#

Support#