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

# Institutions

> Use catalog records when available, or start onboarding with a portal URL

An **Institution** is a catalog record for a bank or banking platform Waycore already recognizes. It is not required to start onboarding a bank, and it is not a live connection.

Use the institutions endpoints to discover the correct `institutionId` when a bank is already in the catalog.

<Note>
  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.
</Note>

## Institution vs connection

| Object          | What it represents                                                                                                                        |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Institution** | A bank record in Waycore's public catalog, used when one is available.                                                                    |
| **Connection**  | A live, entity-owned integration created with either an `institutionId` or a bank `portalUrl`, after delegated-user setup and activation. |

In other words: institutions are a convenience for known banks, not a prerequisite for onboarding a new one.

## Connection input paths

| Input path                      | When to use it                                                                        |
| ------------------------------- | ------------------------------------------------------------------------------------- |
| `entityId` plus `institutionId` | Use when the bank appears in `GET /v1/institutions`.                                  |
| `entityId` plus `portalUrl`     | Use when the bank is not listed yet, or when you are starting from a bank portal URL. |

For catalog records, call `GET /v1/institutions`, search by institution name, identifier, portal URL, or portal domain, then use the returned `institutionId` in `POST /v1/connections`. For banks that are not listed, use the HTTPS bank `portalUrl` directly in `POST /v1/connections`.

## Key fields

* **`institutionId`** — Stable Waycore identifier used when creating connections.
* **`name`** — Display name for the bank or banking platform.
* **`canonicalPortalUrl`** — Default HTTPS portal URL for the institution.
* **`additionalPortalUrls`** — Other known HTTPS portal URLs that can be supplied when creating a connection.
* **`alternativeNames`** — Other names by which the institution is commonly known.
* **`logoUrl`** — URL of the institution's logo, when available.
* **`setupGuideUrl`** — Link to Waycore's user-facing setup guide for this institution.
* **`status`** — `live` if the institution is fully supported, or `pending` if it is in the catalog but not yet available for new connections.

## Searching

`GET /v1/institutions` supports a `query` parameter for name, identifier, portal URL, or portal domain search. Results are cursor-paginated, so you can browse the full catalog or power a searchable picker in your product.

Use `institutionId` when a catalog record fits the bank. Use `portalUrl` directly in the connection create call when the bank is unsupported, newly requested, or better identified by a specific portal URL.

## Endpoints

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

  <Card title="Get institution" icon="search" href="/api-reference/institutions/get-institution" />

  <Card title="Create connection" icon="plus" href="/api-reference/connections/create-connection" />
</CardGroup>

## Required scopes

| Scope               | Used by                                                         |
| ------------------- | --------------------------------------------------------------- |
| `connections:read`  | List, get                                                       |
| `connections:write` | Create a connection with the selected institution or portal URL |