> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endstate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tap redirects

> Control where a user lands after tapping a chip. Set a redirect URL on a unit, a collection, or your organization default — the most specific one wins.

When a user taps a chip and lands on Endstate's hosted verification flow, you can send them straight to a destination you choose — a product page, a campaign, or your own verification experience. You configure that destination through the API at three levels. The **most specific level wins**, and if none is set, the user stays on Endstate's hosted verify page.

## Resolution order

Endstate resolves the destination for each tap from most specific to least specific, and uses the first one that is set:

| Level                    | Where you set it                          | Applies to                                                          |
| ------------------------ | ----------------------------------------- | ------------------------------------------------------------------- |
| **Unit**                 | `redirect_url` on the unit                | That one unit.                                                      |
| **Collection**           | `redirect_url` on the collection          | Every unit in the collection that has no redirect of its own.       |
| **Organization default** | `default_redirect_url` via `/v1/settings` | Every tap in your organization with no unit or collection redirect. |
| *Fallback*               | —                                         | Endstate's hosted verify page, when no redirect is configured.      |

A unit redirect overrides its collection's redirect; a collection redirect overrides the organization default. Set the level that matches how broadly you want the destination to apply.

<Note>
  The verify response (`POST /v1/chips/{chip_id}`) also returns a field named
  `redirect_url` — that one is different: it is the canonical verify-page URL on
  your verified domain, not the tap redirect configured here. See [Chips &
  verification](/concepts/chips#response-fields).
</Note>

## Continuing the flow on your destination

When Endstate redirects to your URL, it appends the tapped chip's id and one-time credential as query parameters, so your page has everything it needs to verify the tap:

| Parameter          | Description                                               |
| ------------------ | --------------------------------------------------------- |
| `endstate_chip_id` | The `chip_id` of the tapped chip.                         |
| `endstate_e`       | The one-time tap credential (the `e` value) for this tap. |

For example, a redirect URL of `https://brand.example/p` sends the user to:

```
https://brand.example/p?endstate_chip_id=ABCDEF0123&endstate_e=C78566198547116F3A715DC1C62AF96F
```

Your page forwards these to your server, which verifies the tap with `POST /v1/chips/{chip_id}` using your API key. See [Verify a unit](/guides/verify-a-unit) for the full server-side flow — this lets you host the entire post-tap experience on your own domain.

<Warning>
  The `endstate_e` value is a single-use credential with a short validity
  window. Forward it to your server and verify promptly; do not log it or store
  it at rest.
</Warning>

## Setting a redirect

A redirect URL must be a valid absolute URL (surrounding whitespace is trimmed). Every write requires an API key (`end_sk_...`) and is scoped to your organization. Send `null` to clear a redirect.

### On a unit

Set it at creation, or update it later. The value is returned when you read the unit.

```bash theme={null}
curl -X PATCH https://api2.endstate.io/v1/units/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer end_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "redirect_url": "https://brand.example/p/001" }'
```

### On a collection

Applies to every unit in the collection that does not set its own `redirect_url`.

```bash theme={null}
curl -X PATCH https://api2.endstate.io/v1/collections/8e1a7f50-90ab-4cde-b012-3456789abcde \
  -H "Authorization: Bearer end_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "redirect_url": "https://brand.example/collection" }'
```

### Organization default

The fallback for every tap that has no unit or collection redirect. Read the current value with `GET /v1/settings`; set or clear it with `PATCH /v1/settings`.

```bash theme={null}
curl -X PATCH https://api2.endstate.io/v1/settings \
  -H "Authorization: Bearer end_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "default_redirect_url": "https://brand.example" }'
```

```json theme={null}
{
  "default_redirect_url": "https://brand.example",
  "default_chain_id": 84532,
  "allowed_chain_ids": [84532]
}
```

(The settings response also carries your organization's read-only network configuration — `default_chain_id` and `allowed_chain_ids` — which controls what [collections](/concepts/collections#create-a-collection) are created on. Only `default_redirect_url` is editable here.)

### Clearing a redirect

Send `null` to remove a redirect at any level. Resolution then falls through to the next level down.

```bash theme={null}
curl -X PATCH https://api2.endstate.io/v1/units/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer end_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "redirect_url": null }'
```

## Endpoints

| Method  | Path                              | Description                                |
| ------- | --------------------------------- | ------------------------------------------ |
| `PATCH` | `/v1/units/{unit_id}`             | Set or clear a unit's redirect URL.        |
| `PATCH` | `/v1/collections/{collection_id}` | Set or clear a collection's redirect URL.  |
| `GET`   | `/v1/settings`                    | Read your organization's default redirect. |
| `PATCH` | `/v1/settings`                    | Set or clear your organization's default.  |

`redirect_url` is also accepted on `POST /v1/units` and `POST /v1/collections`, and returned on read. See the [API reference](/api-reference/introduction) for full schemas.

## Next steps

<CardGroup cols={2}>
  <Card title="Verify a unit" icon="scan-line" href="/guides/verify-a-unit">
    Complete verification server-side after a tap lands on your destination.
  </Card>

  <Card title="Units" icon="box" href="/concepts/units">
    Where a unit-level redirect lives, alongside the rest of the unit record.
  </Card>
</CardGroup>