# List Connections

**GET** `/users/{user_id}/connections`

Base URL: `https://live.savewithsail.com/api/v1`

All connections for a user, optionally filtered by type.

## Authorization

- PartnerKey (http, bearer)

## Path parameters

- `user_id` (string, required)
  The Sail user id.

## Query parameters

- `type` (string)
  Filter to connections of one type.
- `status` (string)
  Filter to connections in one status.
- `limit` (integer)
  Max results per page.
- `offset` (integer)
  Pagination offset.

## Responses

### 200

The user's connections.

- `data` (object[])
  - `id` (string)
    The Sail connection id.
  - `user_id` (string)
    The Sail user this connection belongs to.
  - `type` ("card" | "store" | "benefit_account" | "external")
    The kind of data source this connection links to.
  - `status` ("active" | "aggregating" | "user_input_required" | "error" | "disconnected")
    The connection's current sync/authentication status.
  - `products` ("expenses" | "benefit_account" | "account_numbers" | "identity"[])
    Capabilities enabled on this connection.
  - `accounts` (object[])
    Embedded summaries of the accounts under this connection, so account ids are discoverable without a second call. Populated for `benefit_account` connections (a single administrator login can hold multiple benefit accounts, e.g. HSA + LPFSA); empty for connection types whose accounts are not exposed. Full detail — balances, numbers, contributions — lives at /users/{user_id}/accounts/{account_id}.
    - `id` (string)
      The Sail account id.
    - `type` ("hsa" | "fsa" | "hra" | "checking" | "savings" | "credit_card")
      The account type.
    - `name` (string)
      The account's display name.
  - `provider` (object)
    The external party this connection links to.
    - `id` (string)
      The provider's identifier in Sail's directory (merchant or administrator id).
    - `name` (string)
      The provider's display name.
    - `kind` ("administrator" | "financial_institution" | "merchant" | "external")
      What kind of external party this provider is.
    - `icon_url` (string)
      URL of the provider's icon/logo.
  - `error` (object)
    Present when the connection is in an error state. Null otherwise.
    - `code` (string)
      Machine-readable error code.
    - `message` (string)
      Human-readable error message.
    - `recoverable` (boolean)
      Whether the user can resolve this error via a `reconnect` hosted session.
  - `last_sync_at` (string<date-time>)
    When this connection last completed a sync. Null if it has never synced.
  - `created_at` (string<date-time>)
    When the connection was created.
  - `updated_at` (string<date-time>)
    When the connection was last updated.
- `pagination` (object)
  Pagination metadata for this page.
  - `total` (integer)
    Total number of matching records, across all pages.
  - `limit` (integer)
    The `limit` used for this page.
  - `offset` (integer)
    The `offset` used for this page.
  - `has_more` (boolean)
    Whether additional pages remain after this one.

Example:

```json
{
  "data": [
    {
      "id": "conn_9f2c",
      "user_id": "string",
      "type": "card",
      "status": "active",
      "products": [
        "expenses"
      ],
      "accounts": [
        {
          "id": "acct_77b1",
          "type": "hsa",
          "name": "HealthEquity HSA"
        }
      ],
      "provider": {
        "id": "string",
        "name": "HealthEquity",
        "kind": "administrator",
        "icon_url": "string"
      },
      "error": {
        "code": "INVALID_CREDENTIALS",
        "message": "string",
        "recoverable": true
      },
      "last_sync_at": "1970-01-01T00:00:00.000Z",
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  }
}
```

### default

Standard error envelope covering 400, 401, 403, 404, 429, and 500.

- `error` (object)
  The error detail.
  - `code` (string)
    Machine-readable code, e.g. `not_found`, `token_scope_mismatch`, `product_not_enabled`, `insufficient_key_scope`, `insufficient_token_scope`, `user_token_required`, `user_token_expired`, `invalid_user_token`, `invalid_key_configuration`, `connection_not_reconnectable`, `rate_limited`.
  - `message` (string)
    Human-readable error message. May change, so match on `error.code` instead.
  - `param` (string)
    The request field that caused the error, when applicable. Null otherwise.

Example:

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "param": "string"
  }
}
```