---
title: "Start a new bank connection"
method: POST
path: "/v1/banks/connections/start"
tags: ["Banks"]
---

# Start a new bank connection

`POST /v1/banks/connections/start`

## Request

- Base URL: `https://api.banksync.io`
- URL: `https://api.banksync.io/v1/banks/connections/start`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Initiates a provider-specific connection flow. Returns a `ConnectionStart` payload the client renders — a Plaid Link token, a portal popup URL, or an OAuth redirect URL depending on the provider.

## Request body

- object
  - `providerInstanceId` string, required
  - `email` string, email, required
  - `mobile` string
  - `institutionId` string
  - `brandId` string
  - `countryCodes` string[]
  - `redirectUri` string
  - `brokerageSlug` string
  - `saltedgeConsentScopes` string[]
  - `connectionType` 'read' | 'trade'
  - `forceNewConnection` boolean

## Response `200`

Connection flow initiated

- object
  - `success` true, required
  - `data` union, required
    - object
      - `flow` 'plaid_link', required
      - `linkToken` string, required
      - `expectedPayloadKind` 'plaid_public_token', required
      - `attemptId` string
    - object
      - `flow` 'fiskil_link', required
      - `authSessionId` string, required
      - `expectedPayloadKind` 'provider_connection_id', required
      - `attemptId` string
    - object
      - `flow` 'quiltt_connector', required
      - `sessionToken` string, required
      - `connectorId` string, required
      - `institutionId` string
      - `institutionTargeting` 'id' | 'name'
      - `connectionId` string
      - `expectedPayloadKind` 'provider_connection_id', required
      - `attemptId` string
    - object
      - `flow` 'portal_popup', required
      - `url` string, required
      - `expiresAt` string, date-time
      - `expectedPayloadKind` 'provider_connection_id', required
      - `attemptId` string
    - object
      - `flow` 'oauth_redirect', required
      - `url` string, required
      - `expiresAt` string, date-time
      - `expectedPayloadKind` 'provider_connection_id', required
      - `attemptId` string
    - object
      - `flow` 'existing_connection', required
      - `existingBanks` object[], required
        - `id` string, required
        - `name` string, required
        - `requiresReauth` boolean, required
      - `canCreateAdditional` boolean, required

## Other responses

- `400`: Invalid request
- `401`: Unauthorized
- `403`: Forbidden or plan limit reached
- `501`: Provider not available in this environment

---

[API](https://skmtc.dev/banksync/apis/banksync-api.md) · [All operations](https://skmtc.dev/banksync/apis/banksync-api/llms.txt) · [OpenAPI document](https://skmtc.dev/banksync/apis/banksync-api/revisions/94465f5ee922?raw)