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.

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/{userId}/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. 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.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

OAuth 2.0

Authorization Code

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Authorize URL: https://api.synci.io/oauth/authorize

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

Body Params application/jsonRequired

Examples

curl --location 'https://api.synci.io/api/v1/finance/connections' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "institution_id": 0, "max_historical_days": 0, "access_valid_for_days": 1, "sync_balances": true, "integrator": "UNKNOWN", "reference": "string" }'

{ "message": "A connection for this institution already exists.", "data": { "already_connected": true, "financial_connection": { "id": 0, "institution_id": 0, "institution": { "id": 0, "integrator": "UNKNOWN", "country": "string", "name": "string", "bic": "string", "external_id": "string", "logo": "string", "supported": true, "supports_pending_transactions": true, "supports_card_accounts": true, "max_historical_days": 0, "max_access_valid_for_days": 0, "category": "string", "updated_at": "2019-08-24T14:15:22.123Z" }, "enabled": true, "health": { "status": "string", "integrator_message": "string", "failure_count": "string", "transient_message": "string", "transient_failure_count": "string", "last_attempt_at": "string" }, "status": "string", "status_message": "string", "sync_balances": true, "supports_reauthorization": true, "supports_manage": true, "max_historical_days": 0, "access_valid_for_days": 0, "consent_expires_at": "2019-08-24T14:15:22.123Z", "reference": "string", "accounts_last_synced_at": "2019-08-24T14:15:22.123Z", "financial_accounts": [ { "id": 0, "financial_connection_id": 0, "financial_connection": {}, "config": { "map_fields": { "payee": "AUTO", "description": "AUTO", "date": "AUTO" }, "enrichment": { "enabled": "string", "provider": "string", "country": "string" }, "sync_start_date": "2025-01-01", "sync_auto": true, "sync_pending_transactions": true, "pending_settlement_matching": true, "pending_settlement_max_days": 0, "sync_balances": true, "sync_frequency_in_minutes": 0, "fields_for_duplicate_filtering": [ "string" ] }, "health": { "status": "string", "integrator_message": "string", "failure_count": "string", "transient_message": "string", "transient_failure_count": "string", "last_attempt_at": "string" }, "enabled": true, "integrator": "UNKNOWN", "account_category": "string", "raw_type": "string", "cash_balance": { "amount": "string", "currency": "string" }, "meta": [ null ], "account_number_masked": "string", "name": "string", "custom_name": "string", "display_name": "string", "bban": "string", "scan": "string", "iban": "string", "bic": "string", "owner_name": "string", "owner_address": "string", "currency": "string", "product_name": "string", "cash_account_type": "string", "account_usage": "string", "linked_accounts": "string", "details": "string", "msisdn": "string", "integrator_id": "string", "institution_id": "string", "details_last_synced_at": "2019-08-24T14:15:22.123Z", "transactions_last_synced_at": "2019-08-24T14:15:22.123Z", "balances_last_synced_at": "2019-08-24T14:15:22.123Z", "balance": { "available": 0, "cleared": 0 }, "rules": [ { "order": "string", "rule": [ null ] } ], "transfer_links": [ { "id": 0, "financial_account_id": 0, "financial_account": {}, "destination_type": "YNAB", "destination_id": 0, "destination": { "id": 0, "budget_id": 0, "budget": { "id": 0, "connection_id": 0, "connection": { "id": 0, "name": "string", "health": { "status": "string", "integrator_message": "string", "failure_count": "string", "transient_message": "string", "transient_failure_count": "string", "last_attempt_at": "string" }, "enabled": true, "auth_url": "string", "sync_balances": true, "ynab_user_id": "string", "budgets": [ {} ], "last_synced_at": "2019-08-24T14:15:22.123Z", "created_at": "2019-08-24T14:15:22.123Z", "updated_at": "2019-08-24T14:15:22.123Z" }, "ynab_id": "string", "enabled": true, "name": "string", "currency": "string", "first_month": "string", "last_month": "string", "accounts": [ {} ], "last_synced_at": "2019-08-24T14:15:22.123Z", "created_at": "2019-08-24T14:15:22.123Z", "updated_at": "2019-08-24T14:15:22.123Z" }, "ynab_id": "string", "health": { "status": "string", "integrator_message": "string", "failure_count": "string", "transient_message": "string", "transient_failure_count": "string", "last_attempt_at": "string" }, "name": "string", "type": "checking", "on_budget": true, "closed": true, "note": "string", "balance": "string", "cleared_balance": "string", "uncleared_balance": "string", "transfer_payee_id": "string", "direct_import_linked": true, "last_reconciled_at": "string", "transfer_links": [ {} ], "created_at": "2019-08-24T14:15:22.123Z", "updated_at": "2019-08-24T14:15:22.123Z" }, "transfer_start_date": "2025-01-01", "active": true, "sync_mode": "TRANSACTIONS", "on_booked_change": { "update_status": true, "update_payee": true, "update_description": true, "update_amount": true }, "rules": [ { "order": "string", "rule": [ null ] } ], "created_at": "2019-08-24T14:15:22.123Z", "updated_at": "2019-08-24T14:15:22.123Z" } ], "transfer_links_count": "string", "created_at": "2019-08-24T14:15:22.123Z", "updated_at": "2019-08-24T14:15:22.123Z" } ], "financial_accounts_count": "string", "created_at": "2019-08-24T14:15:22.123Z", "updated_at": "2019-08-24T14:15:22.123Z" } } }

Create a new financial connection

Request

Responses