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. Before you create a connection, you need:

1. An owning entity from Entities
2. Either an institutionId from Institutions or a bank portalUrl

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

​

Connection kinds

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: 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

When a connection changes status, Waycore can notify you via the connection.status_changed 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 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

​

Required scopes