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

# Entities

> Model the businesses that own connections and data

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

| Entity type            | When to use it                                                                                                                        |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Default org entity** | Use the Waycore-managed default entity when the integrator and the end business are the same organization.                            |
| **Customer entity**    | Create your own entity records when you need separate ownership boundaries for customers, subsidiaries, SPVs, or operating companies. |

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

<CardGroup cols={3}>
  <Card title="List entities" icon="list" href="/api-reference/entities/list-entities" />

  <Card title="Create entity" icon="plus" href="/api-reference/entities/create-entity" />

  <Card title="Get entity" icon="search" href="/api-reference/entities/get-entity" />

  <Card title="Update entity" icon="pen" href="/api-reference/entities/update-entity" />

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

## Required scopes

| Scope            | Used by                |
| ---------------- | ---------------------- |
| `entities:read`  | List, get              |
| `entities:write` | Create, update, delete |