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

# Your first API call

Before you can read account and transaction data, you first need to set up a connection. The public API flow is:

1. Identify the owning entity
2. Choose a bank target with either an institution catalog record or a portal URL
3. Create or return a connection
4. Provide the delegated-user credentials
5. Mark setup complete
6. Wait for the connection to become `kind="ready"`
7. Read data or trigger a sync

```bash theme={null}
API_KEY="way_live_<key_id>_<secret>"
BASE_URL="https://api.waycore.com/v1"
ENTITY_ID="11111111-2222-3333-4444-555555555555"
INSTITUTION_ID="chase"
CONNECTION_ID="conn_123"
```

## 1. Find the owning entity

Start by listing entities and choosing either the default org entity or a customer entity you created earlier.

```bash theme={null}
curl -sS "$BASE_URL/entities?limit=10" \
  -H "Authorization: Bearer $API_KEY"
```

## 2. Choose the bank target

If the bank is already in the public institution catalog, search by name, identifier, portal URL, or portal domain, then capture the `institutionId` you want to connect.

A bank does not need to appear in `/v1/institutions` before you can start onboarding it. If it is not listed, use its HTTPS `portalUrl` when creating the connection.

```bash theme={null}
curl -sS "$BASE_URL/institutions?query=chase" \
  -H "Authorization: Bearer $API_KEY"
```

## 3. Create or return a connection

Create the connection using the chosen `entityId` plus either `institutionId` or `portalUrl`. The response returns a `ConnectionResource`, which may be a new `kind="setup"` connection or an existing connection returned directly.

If the response is `kind="setup"`, you can use the returned `setup.instructions` immediately. The current email, username, phone number, and other setup details are included on that first create response.

```bash theme={null}
curl -sS "$BASE_URL/connections" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "'"$ENTITY_ID"'",
    "institutionId": "'"$INSTITUTION_ID"'"
  }'
```

```bash theme={null}
curl -sS "$BASE_URL/connections" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "'"$ENTITY_ID"'",
    "portalUrl": "https://business.bank.example.com/login"
  }'
```

## 4. Provide credentials

Once the delegated user exists in the bank, submit the current working credentials. Include `password` when that bank requires one.

```bash theme={null}
curl -sS "$BASE_URL/connections/$CONNECTION_ID/credentials" \
  -X PUT \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bankUsername": "waycore.user",
    "bankCustomerId": "company-001",
    "password": "super-secret-password"
  }'
```

## 5. Mark setup complete

After the bank-side delegated-user setup is finished, notify Waycore so activation can continue. From there, Waycore completes activation and starts the initial historical backfill automatically.

```bash theme={null}
curl -sS "$BASE_URL/connections/$CONNECTION_ID/setupCompletion" \
  -X PUT \
  -H "Authorization: Bearer $API_KEY"
```

## 6. Wait for `kind="ready"`

If the create call returned `kind="setup"`, poll the connection until it transitions to `kind="ready"`. Once the connection is ready, the normal steady-state status is `active`.

```bash theme={null}
curl -sS "$BASE_URL/connections/$CONNECTION_ID" \
  -H "Authorization: Bearer $API_KEY"
```

## 7. Read data or queue a sync

Once the connection is ready, you can read accounts and transactions immediately, or trigger a sync if you need fresh data right away. Manual sync triggers are subject to the connection cooldown described in [Connections](/connections).

```bash theme={null}
curl -sS "$BASE_URL/accounts?connectionId=$CONNECTION_ID" \
  -H "Authorization: Bearer $API_KEY"
```

```bash theme={null}
curl -sS "$BASE_URL/connections/$CONNECTION_ID/sync" \
  -X PUT \
  -H "Authorization: Bearer $API_KEY"
```

From there, use `GET /v1/transactions` for backfills and `GET /v1/transactions/sync` plus webhooks to keep your mirror current.