Skip to main content
An Entity is the ownership boundary for the public API. Every connection belongs to exactly one entityId, and the accounts and transactions discovered through that connection inherit the same ownership. Use entities to model the businesses, funds, subsidiaries, or customers you manage through Waycore.

​
Why entities come first

Before you create a connection, you need:
  1. An owning entity from GET /v1/entities or POST /v1/entities
  2. Either a target institution from GET /v1/institutions or a raw bank portalUrl
That entity then becomes the owner in POST /v1/connections.

​
Default org entity vs customer entities

The isDefaultOrgEntity flag tells you whether an entity is the special organization-attached default.

​
Key fields

  • entityId — Stable Waycore identifier used throughout the API.
  • externalEntityId — Your own stable identifier for the business. This is the best key to use when mapping back to your system.
  • name — Human-readable display name.
  • contactEmails — Email addresses for people who manage this entity’s connections.
  • metadata — Opaque key-value data for your own routing and bookkeeping.

​
When to create a new entity

Create a new entity when you need a separate ownership boundary for:
  • A new customer
  • A new legal entity or fund
  • A new business unit that should have its own bank connections
  • A separate reconciliation or access-control boundary in your product
If the same business owns multiple bank connections, reuse the same entity across those connections.

​
Contact emails

Use contactEmails to tell Waycore who manages an entity’s bank connections. Waycore uses these addresses to reach the right people when a connection has invalid configuration or needs attention. You can provide contact emails when creating an entity. To replace the list later, call PATCH /v1/entities/{entityId} with the full replacement list. Send an empty array to clear all contacts.

​
Listing and filtering

GET /v1/entities supports filtering by externalEntityId. Results are cursor-paginated and return the canonical entity records visible to your organization.

​
Deleting an entity

DELETE /v1/entities/{entityId} performs a hard delete of the entity plus its owned public connections and related data, including linked accounts and transactions. Important caveats:
  • Organization-managed default entities cannot be deleted.
  • You may receive 409 Conflict while one of the entity’s connections is syncing.
  • This is a destructive operation for the entity’s full public data footprint.

​
Endpoints

List entities

Create entity

Get entity

Update entity

Delete entity

​
Required scopes