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.

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.

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.

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.

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. This is typically used for maintenance.
revoked	Access has been removed. No further syncs will occur.

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

Create connection

List connections

Get connection

Update credentials

Complete setup

Sync connection

Delete connection

Required scopes

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