Connections

A Connection is the live link between one entity and one supported institution or bank portal. Every account and transaction in the public API is scoped to a connection, and every connection must belong to an entityId. Before you create a connection, you need:

1. An owning entity from Entities
2. Either a target institution from Institutions or a raw 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.

​

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".
6. If the response is already kind="ready", start reading data or queue a sync immediately.

​

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, 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.

​

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. Expect 409 Conflict when:

• The connection is still in setup
• A sync is already in progress
• A sync was triggered very recently and 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