---
title: "Get connections by user"
method: GET
path: "/connections"
---

# Get connections by user

`GET /connections`

## Request

- Base URL: `https://api.open-finance.ai/v2`
- URL: `https://api.open-finance.ai/v2/connections`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://api.open-finance.ai/oauth/token` scopes: `read:connections`

## Query parameters

- `customerId` string
- `contactId` string
- `limit` number
- `sort` 1 | -1
- `nextPage` string
- `status` 'ACTIVE'

## Response `200`

Response

- object
  - `nextPage` string, nullable: Pagination cursor for the next page; null when there are no more pages
  - `count` number: Number of connection documents returned in items for this response (before optional status filter)
  - `items` Connection[]
    - `id` string: A unique identifier for the connection
    - `userId` string: A unique identifier for the user
    - `customerId` string, nullable: Customer identifier for extended journeys (e.g. loans)
    - `psuId` string, nullable: The national id or passport number of the user
    - `psuIdType` string, nullable: The type of the PSU ID
    - `psuCorporateId` string, nullable: The ID of a customer (business ID / national ID)
    - `providerId` string, nullable: A unique identifier for the provider
    - `status` 'ACTIVE' | 'CONNECTED' | 'FETCHING' | 'ERROR' | 'FETCHING_ERROR' | 'INACTIVE' | 'COMPLETED' | 'CREDENTIALS_ERROR' | 'REJECTED' | 'PARTIALLY_AUTHORIZED' | 'UNKNOWN' | 'TERMINATED_BY_USER' | 'EXPIRED' | 'REVOKED' | 'REPLACED' | 'SUSPENDED_BY_PROVIDER': The connection status
    - `mode` 'PSD2' | 'PLAID': The connection mode (open banking vs Plaid)
    - `expiryDate` string, date: The date at which the connection/consent expires
    - `accounts` number, nullable: Number of checking accounts associated with the connection
    - `cards` number, nullable: Number of credit-cards associated with the connection
    - `savings` number, nullable: Number of savings accounts associated with the connection
    - `loans` number, nullable: Number of loans accounts associated with the connection
    - `securities` number, nullable: Number of security accounts associated with the connection
    - `transactions` number, nullable: Number of transactions associated with the connection
    - `providerIds` string[]: Allowed provider IDs for this connection. Enum must match PROVIDERS_IDS_LIST in src/consts.ts (see tests/data/connection-openapi.spec.ts).
    - `includeFakeProviders` boolean, nullable: If true, allow usage of dummy bank
    - `excludeCreditCardProviders` boolean, nullable: If true, credit-card providers are excluded from this connection
    - `callbackInformation` CallbackInformation: Webhook and callback configuration stored on the connection (mirrors organization callback shape where applicable)
      - `webhooks` object, nullable
        - `enabled` boolean, nullable: If true, enable webhooks
        - `successUrl` string, nullable: The url endpoint for success events
        - `failUrl` string, nullable: The url endpoint for fail events
        - `abortUrl` string, nullable: The url endpoint for abort events
        - `oauth` object, nullable
          - `enabled` boolean, nullable: Whether OAuth is used to authenticate webhook calls
          - `clientId` string, nullable
          - `clientSecret` string, nullable
          - `audience` string, nullable
          - `scope` string, nullable
          - `tokenUrl` string, nullable
        - `basic` object, nullable: Optional basic-auth configuration for webhooks
          - `enabled` boolean, nullable
          - `username` string, nullable
          - `password` string, nullable
          - `tokenUrl` string, nullable
        - `customHeaders` object, nullable: Extra HTTP headers sent with webhook requests
        - `products` string[], nullable: Which products emit webhooks for this configuration
    - `refreshSettings` object: Background refresh configuration for transaction data
      - `refreshData` boolean: If true, the connection will refresh TX data in the background
      - `frequencyPerDay` number, nullable: Max refresh operations per day when configured
      - `lastFetchedDataDate` string, date, nullable: Last date at which transactions have been fetched (from refresh settings)
    - `error` ConnectionError: Error details when the connection is in an error state
      - `message` string, nullable: Error message
      - `type` string, nullable: Error type
    - `organization` ConnectionOrganization: Organization metadata stamped on the connection when created
      - `name` string: Organization display name
    - `isFake` boolean, nullable: If true, the connection targets sandbox / fake providers. Sample responses use JSON boolean true/false, not the string "true".
    - `restrictedTo` string[]: Product types this connection is restricted to
    - `iframe` boolean, nullable: Whether the consent journey should display as an iframe
    - `access` ConnectionAccess: Permissions / account scope for the connection
      - `accounts` ConnectionAccessAccountSelector[]
        - `iban` string, nullable: The account IBAN
        - `bban` string, nullable: The account BBAN
      - `balances` ConnectionAccessAccountSelector[]
        - `iban` string, nullable: The account IBAN
        - `bban` string, nullable: The account BBAN
      - `transactions` ConnectionAccessAccountSelector[]
        - `iban` string, nullable: The account IBAN
        - `bban` string, nullable: The account BBAN
    - `contactId` string, nullable: Phone number of a contact from an extended journey (e.g. loans).
    - `redirectUrl` string, nullable: An optional URL to be redirected after a successful connection
    - `startDate` string, date: The date from which transactions would be collected
    - `createdAt` string, date-time, nullable: The timestamp in UTC when the connection was created
    - `updatedAt` string, date-time, nullable: The timestamp in UTC when the connection was last updated
    - `scaOAuth` string, nullable: URL for OAuth-based Strong Customer Authentication
    - `verifier` string, nullable: Verifier used for verifying the connection
    - `lastFetchedDataDate` string, date, nullable: Last date at which transactions have been fetched
    - `language` string, nullable: The language to use in the consent journey, if not set the user will be able to choose the language
    - `paymentId` string, nullable: Related payment identifier when the connection was created from a payment flow
    - `allowBusiness` boolean, nullable: Indicates if the connection allows business accounts
    - `allowInsurance` boolean, nullable: Indicates if the connection allows insurance-related data
    - `isPriority` boolean: Whether this connection is treated as priority for processing
    - `customerApprovalGranted` boolean, nullable: Indicates whether the end user has approved the customer approval terms. Only present when the feature is enabled on the organization

## Other responses

- `400`: userId is not allowed in query for non-admin users
- `401`: Unauthorized access - Invalid access token
- `403`: Forbidden - Access token missing the required permissions to preform this action
- `404`: Route or entity not found
- `500`: Internal server error

---

[API](https://skmtc.dev/open-finance/apis/data.md) - [All operations](https://skmtc.dev/open-finance/apis/data/llms.txt) - [OpenAPI document](https://skmtc.dev/open-finance/apis/data/revisions/c18eafb2a770?raw)