Tap redirects

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.

The tap response (POST /v1/taps) 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.

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:

string

The chip_id of the tapped chip.

string

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_e=C78566198547116F3A715DC1C62AF96F&endstate_chip_id=ABCDEF0123

Read endstate_chip_id and send it as chip_id:

const params = new URLSearchParams(window.location.search);
const chipId = params.get("endstate_chip_id"); // the API's chip_id
const e = params.get("endstate_e");

Your page then records the tap with POST /v1/taps, either way round - the endpoint takes either credential:

With a backend - forward the two values to your server, which calls POST /v1/taps with your API key. See Verify a unit.
Without one - the page calls POST /v1/taps itself with your publishable key, then reads the unit with the session token it gets back. See Host your own verify page.

Either way you host the entire post-tap experience on your own domain.

The endstate_e value is a single-use credential with a short validity window. Verify promptly; do not log it or store it at rest.

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.

await endstate.units.update("a1b2c3d4-e5f6-7890-abcd-ef1234567890", {
  redirect_url: "https://brand.example/p/001",
});

curl -X PATCH https://api2.endstate.io/v1/units/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer end_sk_..." \
  -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.

await endstate.collections.update("8e1a7f50-90ab-4cde-b012-3456789abcde", {
  redirect_url: "https://brand.example/collection",
});

curl -X PATCH https://api2.endstate.io/v1/collections/8e1a7f50-90ab-4cde-b012-3456789abcde \
  -H "Authorization: Bearer end_sk_..." \
  -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. See Organization settings for the rest of that response.

await endstate.settings.update({
  default_redirect_url: "https://brand.example",
});

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

Response

{
  "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 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.

await endstate.units.update("a1b2c3d4-e5f6-7890-abcd-ef1234567890", {
  redirect_url: null,
});

curl -X PATCH https://api2.endstate.io/v1/units/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer end_sk_..." \
  -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 for full schemas.

Get started

Settings

Core concepts

API conventions

Updates

Resolution order

Continuing the flow on your destination

Setting a redirect

On a unit

On a collection

Organization default

Clearing a redirect

Endpoints

Next steps

Verify a unit

Units

​Resolution order

​Continuing the flow on your destination

​Setting a redirect

​On a unit

​On a collection

​Organization default

​Clearing a redirect

​Endpoints

​Next steps

Verify a unit

Units

Resolution order

Continuing the flow on your destination

Setting a redirect

On a unit

On a collection

Organization default

Clearing a redirect

Endpoints

Next steps