--- title: "Link variants" description: "Create separate tracked links for each recipient, with independent revocation and per-recipient download and page-range overrides." canonical: "https://everypage.co/docs/sharing/link-variants" plan: "pro" last-updated: "2026-08-26" --- # Link variants Link variants let you create multiple tracked links from a single document, one per recipient. Each variant gets its own short link and optional setting overrides, so you can track readers individually and revoke one recipient's access without affecting others. ## How variants work A variant is a child link on your document with its own 12-character short identifier (the same shape as a file short ID) and an optional recipient label of up to 200 characters. The label is the only personal data stored. Each document supports up to 200 variants. When a reader opens a variant link, the access is attributed to that recipient in readership reporting and webhook payloads. Variant links resolve on your [custom domain](https://everypage.co/custom-domain) just like the parent document's own link, so each recipient's link can carry your brand instead of everypage.co. Variants are managed through the API, not the document settings screen: `/api/files/{uuid}/variants` for session-authenticated dashboard clients and `/api/v1/files/{uuid}/variants` for bearer tokens (`files:read` to list, `files:write` to create, update and delete). Both surfaces require the Pro plan and ownership of the file. ## Settings overrides Each variant can override two file-level settings for that recipient alone: download permission and page range. Overrides are optional — a variant without overrides simply inherits the parent file's settings. ### allowDownload By default, a variant inherits the parent file's download setting. If you set `allowDownload: false` on a variant, that recipient cannot download the file, even if downloads are enabled on the parent document. This is useful when you want to restrict archiving for a particular recipient but allow others to download. ### pageRange By default, a variant shows the full document or the page range set on the parent file. You can override this for a variant by setting `pageRange: { from: 5, to: 10 }` to show only pages 5–10 for that recipient. The pair must satisfy `1 <= from <= to`; anything else is rejected with HTTP 400. The explicit override `pageRange: { from: 0, to: 0 }` clears the override entirely, serving the full document through that variant even when the parent has a range. Ranged serving rewrites the PDF on every request, so page ranges — on the parent file or on a variant — are refused on documents larger than 100MB. ### Important: overrides are replaced, not merged When you update a variant's overrides, the entire override object is replaced with exactly what you send — it is never merged with the stored value. This means: - Sending `{ "overrides": { "allowDownload": false } }` replaces any stored overrides; if the variant previously had a `pageRange` override, it is removed. - Sending `{ "overrides": {} }` clears all overrides. - Omitting the `overrides` field entirely keeps the stored overrides unchanged. To remove one override while keeping another, send an `overrides` object containing only the override you are keeping. This is deliberate: a merge strategy would make it impossible to express "remove this override," because a JSON decoder cannot distinguish between a key that was explicitly set to null and a key that was absent. ## Revoking variants You can revoke a variant at any time, which immediately blocks access to that link. A revoked variant returns a uniform 404 response — indistinguishable from a link that never existed — so a revoked recipient cannot learn whether the canonical document exists or that their access has been removed. Revocation is reversible: set `revoked: false` in an API update to restore the link. Deleting a variant is not. ## GDPR redaction For compliance with data-protection regulations, you can permanently delete a variant's recipient label by including the `?redact=1` query parameter on a DELETE request. Redaction: - NULLs the variant's label permanently (the label can never be set again) - Transactionally scrubs the label from all stored webhook delivery payloads that reference this variant - Preserves the variant itself and its view history, so readership analytics remain intact Both forms of DELETE return HTTP 204 No Content on success. Hard deletion (without `?redact=1`) removes the variant entirely and scrubs the label from stored webhook payloads in the same way, but the variant's view-session records lose their attribution: the rows survive with their variant reference set to NULL. ## Important limitation: gates and passwords are NOT per-variant Every gate (email verification, password protection) applies to the entire file, not individual variants. A reader who passes an email gate or enters a password through one variant has satisfied that gate for all of the file's links. You cannot require different passwords for different recipients or set per-recipient email gates. For truly isolated experiences, use separate documents. ## Analytics and webhooks Each view session records the variant it started on. The per-file readership response then carries a Pro-only `variants` breakdown — sessions and average read time per variant, with each entry's label, revoked state and redacted state — omitted entirely when the file has no variants. See [Audience breakdowns](https://everypage.co/docs/readership/audience-breakdowns). Webhook events (`file.viewed`, `file.downloaded`) include `variantUuid` and `variantLabel` in the payload, so your integrations can route notifications based on which recipient opened the file. `variantLabel` is absent for unlabelled and redacted variants, and the canonical link's own events carry neither field. ## Known behavior Any recipient who actually opens their variant link can see the canonical document UUID in the public file metadata response. Revocation therefore only prevents future access; it does not prevent a recipient who has already viewed the document from proving they had access. If you need to truly erase a recipient's knowledge of the file, redaction is not sufficient — you must assume the canonical UUID is known to anyone who opened their link. ## Related - [Share links and short IDs](https://everypage.co/docs/sharing/share-links-and-short-ids) — how short identifiers work and how the system resolves links - [Download control](https://everypage.co/docs/security/download-control) — the parent document's download setting and how variant overrides interact with it - [Page range links](https://everypage.co/docs/security/page-range-links) — page-range setup and enforcement - [Audience breakdowns](https://everypage.co/docs/readership/audience-breakdowns) — how the Pro-tier Variants breakdown works - [Webhooks](https://everypage.co/docs/developers/webhooks) — how variant attribution flows into event payloads - [Plans and limits](https://everypage.co/docs/getting-started/plans-and-limits) — tier requirements and variant caps