> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waycore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connections

> Onboard and manage entity-owned bank connections

In the API, a **Connection** is the technical resource that represents one entity’s delegated-user workspace at a bank. It is scoped to the authorized bank portal or institution, and it is the parent resource for accounts, balances, transactions, statements, workflow events, and execution-support activity.

<Note>
  The word Connection is an API resource name, not the category claim. Waycore is not a traditional bank API rail, aggregator, or account-access network. It is a universal commercial banking API adapter that operationalizes the bank workspace authorized by the business.
</Note>

Before you create a connection, you need:

1. An owning entity from [Entities](/entities)
2. Either an `institutionId` from [Institutions](/institutions) or a bank `portalUrl`

That input becomes the payload for `POST /v1/connections`.

<Note>
  A bank does not need to appear in `/v1/institutions` before you can start onboarding it. If it is not listed, create the connection with `entityId` plus `portalUrl`; Waycore returns a setup-stage connection and delegated-user instructions while support is added.
</Note>

## Connection kinds

| Kind    | Meaning                                                                                 |
| ------- | --------------------------------------------------------------------------------------- |
| `setup` | A setup-stage connection that still needs delegated-user onboarding or activation work. |
| `ready` | A live connection that can surface accounts and transactions and can be synced.         |

`POST /v1/connections` returns a `ConnectionResource`, which may be either `kind="setup"` or `kind="ready"`. New connections return setup details when delegated-user onboarding is still required. Existing connections may be returned directly with `200 OK`.

When a new connection returns `kind="setup"`, the current `setup.instructions` payload is included immediately on that first `POST /v1/connections` response. Integrators can surface the returned email, username, phone number, and related setup details without waiting for a separate provisioning poll.

## Creation modes

You can create or return a connection in two ways:

| Input mode      | When to use it                                                                                |
| --------------- | --------------------------------------------------------------------------------------------- |
| `institutionId` | Use when the bank is already in the public catalog.                                           |
| `portalUrl`     | Use when the bank is not in the catalog yet, or when you are starting from a bank portal URL. |

If an institution is already supported but has multiple login portals, you can pass `portalUrl` alongside `institutionId` to anchor the connection to the correct portal.

## Setup lifecycle

1. **Create or return the connection** with `POST /v1/connections` using `entityId` plus either `institutionId` or `portalUrl`.
2. **If the response is `kind="setup"`**, show the setup details returned on the `setup` object to the end user or your operations team.
3. **Provide credentials** with `PUT /v1/connections/{connectionId}/credentials`.
4. **Mark setup complete** with `PUT /v1/connections/{connectionId}/setupCompletion` once the bank-side delegated user is ready.
5. **Poll or fetch the connection** with `GET /v1/connections/{connectionId}` until it transitions to `kind="ready"`. In normal steady state, the connection status will then be `active`.
6. **If the response is already `kind="ready"`**, start reading data or queue a sync immediately.

From the integrator's perspective, `setupCompletion` hands control back to Waycore to finish activation. The initial historical data sync starts automatically as part of bringing the connection online.

## Status lifecycle

| Status              | Meaning                                                                                                                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `draft`             | The setup-stage connection exists, but onboarding inputs are still incomplete.                                                                                                                         |
| `pendingActivation` | Bank-side setup is complete and Waycore is validating or activating the connection.                                                                                                                    |
| `active`            | Syncing normally.                                                                                                                                                                                      |
| `reauthRequired`    | Credentials or bank authentication need attention before sync can continue.                                                                                                                            |
| `errored`           | A recoverable issue is preventing sync. Waycore will address and retry automatically.                                                                                                                  |
| `invalidConfig`     | Connection configuration is invalid and needs correction before normal operation can resume.                                                                                                           |
| `paused`            | Syncing has been intentionally suspended by the Waycore team, usually during a new version release or an active bug investigation. API read endpoints continue to work as expected during this period. |
| `revoked`           | Access has been removed. No further syncs will occur.                                                                                                                                                  |

When a connection changes status, Waycore can notify you via the [`connection.status_changed`](/webhooks) webhook.

## Setup-stage fields

* **`institutionId`** — Waycore's canonical identifier for the institution, when already known.
* **`portalUrl`** — Normalized portal URL used as the connection anchor, when available.
* **`setup.instructions`** — Structured delegated-user profile details, such as name, username, address, email, phone number, and provisioning statuses.
* **`setup.credentialsPresent`** — Whether working credentials have already been submitted.
* **`setup.nextAction`** — The next step in the setup flow, such as `createDelegatedUser`, `provideCredentials`, or `activateConnection`.
* **`setup.actionRequiredBy`** — Who needs to do the next step: the end user, the integrator, or Waycore.
* **`errorCode` / `errorMessage`** — Present when the setup-stage connection has a surfaced configuration or activation issue.

## Ready-connection fields

* **`entityId`** — Stable identifier for the business that owns the connection.
* **`portalUrl`** — Normalized portal URL used as the connection anchor, when available.
* **`lastSyncedAt`** — When data was last successfully refreshed. Useful for freshness indicators once the connection is ready.
* **`errorCode` / `errorMessage`** — Present when the connection has degraded or needs reauthentication.

## Listing and filtering

`GET /v1/connections` returns results newest first and supports filtering by:

* `status`
* `institutionId`
* `entityId`

Use `GET /v1/connections/{connectionId}` to fetch the latest shape for a single connection during setup or after activation.

## Syncing

`PUT /v1/connections/{connectionId}/sync` queues an asynchronous sync for a `kind="ready"` connection and returns `202 Accepted` when the job is queued.

After any sync is triggered for a connection, whether by API request or by a scheduled portal job, the connection enters a 45-minute cooldown. During that cooldown, additional manual sync requests return `429 Too Many Requests`. Honor `Retry-After` when present before retrying the same request.

Expect `409 Conflict` when:

* The connection is still in setup
* A sync is already in progress

Expect `429 Too Many Requests` when:

* A sync was triggered recently and the connection is still in cooldown

Use the [Webhooks](/webhooks) page for the event-driven model around `transactions.sync_available`.

## Deleting a connection

`DELETE /v1/connections/{connectionId}` performs a hard delete of the public connection plus any accounts and transactions tied to it.

Use it carefully:

* The delete is destructive.
* Downstream mirrors should treat the connection and all associated records as removed.
* You may receive `409 Conflict` when the connection cannot currently be represented through the requested public contract.

## Endpoints

<CardGroup cols={3}>
  <Card title="Create connection" icon="plus" href="/api-reference/connections/create-connection" />

  <Card title="List connections" icon="list" href="/api-reference/connections/list-connections" />

  <Card title="Get connection" icon="search" href="/api-reference/connections/get-connection" />

  <Card title="Update credentials" icon="key-round" href="/api-reference/connections/update-connection-credentials" />

  <Card title="Complete setup" icon="check-check" href="/api-reference/connections/complete-connection-setup" />

  <Card title="Sync connection" icon="refresh-cw" href="/api-reference/connections/sync-connection" />

  <Card title="Delete connection" icon="trash" href="/api-reference/connections/delete-connection" />
</CardGroup>

## Required scopes

| Scope               | Used by                                                  |
| ------------------- | -------------------------------------------------------- |
| `connections:write` | Create, update credentials, complete setup, sync, delete |
| `connections:read`  | List, get                                                |