Pro plan

Link variants

Create separate tracked links for each recipient, with independent revocation and per-recipient download and page-range overrides.

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.

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.

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.