API reference

Tracked share links API

A share link puts one document or one room in front of readers, behind whichever gates the deal needs. Every setting the share dialog offers is here under the same name, and every visit through a link is measured.

Create an API key Quick start

Base URL https://xdocs.io/api/v1, with Authorization: Bearer xdk_… on every request. Pagination, rate limits, scopes and error codes are the same for every endpoint and are described once, in how the API behaves.

Share links

A tracked link to one document or one room, with its own gates. Every gate the share dialog offers is here under the same name the response returns it with, so you can read a link, change one field and send it back.

GET/api/v1/linkslinks:read

Tracked links, newest first, each with its URL on your link origin.

Query parameters

documentIdstring: Links to one document.
dataRoomIdstring: Links to one room.
activeboolean: true for links that still answer.
limitinteger: Rows per page, up to 100. Defaults to 50.
cursorstring: The previous page's nextCursor. Opaque — pass it back unchanged.

Returns

{ data: Link[], nextCursor }

POST/api/v1/linkslinks:write

Publish a link to one document or one room.

Body (JSON)

documentIdstring: Exactly one of this and dataRoomId.
dataRoomIdstring: Exactly one of this and documentId.
namestring: How the link is labelled in analytics. Defaults to “Shared link”.
activeboolean: Defaults to true.
isPublicboolean: Publish the document: anyone with the address reads it immediately, and search engines are asked to index the page. Forces requireEmail, requireEmailVerification, password and requireNda off, whatever else the same request sets. Defaults to false, so a link is private unless you say otherwise.
requireEmailboolean: Ask a visitor who they are. Defaults to true, and ignored when isPublic is set.
requireEmailVerificationboolean: Send a six-digit code to that address and check it. Implies requireEmail.
passwordstring | null: Protect the link. Null removes it.
expiresAtISO 8601 datetime | null
maxViewsinteger | null: Stop answering after this many visits.
pinnedVersionIdstring | null: Serve one saved version rather than the live document.
allowDownloadboolean: Defaults to false.
watermarkboolean: Defaults to true.
watermarkConfigobject | null: { text, position, opacity, rotation, fontSize, color }, all optional and merged over the current values. text takes the placeholders {email}, {date}, {time}, {ip} and {link}; position is tiled, center or footer; opacity 1–100; rotation -90–90; fontSize 8–96; color a six-digit hex. Null clears it back to the default.
requireNdaboolean: Ask the visitor to accept terms before they can read.
ndaTextstring: Terms written on the link itself.
agreementIdstring | null: Terms from your agreements library instead. Editing that agreement re-asks everyone who accepted the old wording.
allowedEmailsstring[]: Only these addresses — or anyone at allowedDomains, when both are set. Up to 200 entries.
allowedDomainsstring[]: Only addresses at these domains, matched exactly: acme.com does not admit eu.acme.com. Up to 200.
blockedEmailsstring[]: Never these. An entry without an @ in the middle — rival.com or @rival.com — is a domain and blocks everybody at it. Up to 200.
notifyOnViewboolean: Email you when somebody opens it. Defaults to true.
screenshotProtectionboolean: Deter casual copying: printing is blocked and the page hides when the window loses focus. Defaults to false.
allowAssistantboolean: Let the reader ask questions about the document. Defaults to false.
allowAudioboolean: Let the reader have the document read aloud, choosing a voice and a speed. Defaults to false.
allowFeedbackboolean: Show a reaction bar under the document. Defaults to false.
bulkDownloadOtpboolean: Room links only: make a visitor confirm an emailed code before a zip of everything. Defaults to true.
tagsstring[]: Your own labels for filtering links: up to 20, each one word of up to 32 characters, stored lowercased.
captureFields{label, type?, required?, options?, id?}[]: Extra questions asked with the email, up to 8. type is text, select or checkbox and defaults to text; a select needs options. id is minted from the label when you omit it, and is the key the answers come back under on a view.
ogTitlestring | null: What a chat app or social card shows when the link is pasted. Defaults to the document or room name.
ogDescriptionstring | null: The line under that title.
ogImageUrlstring | null: The card's picture, an http or https address. Defaults to the XDocs card. 1200×630 previews best.
ogFaviconUrlstring | null: The icon in the browser tab on the viewer page.

Returns

201 { data: Link } — including url, slug and watermarkConfig as resolved

422 A pinned version or agreement that is not yours, or the plan's link ceiling has been reached.

GET/api/v1/links/:idlinks:read

One link and its gates. The password is reported as hasPassword, never returned.

Returns

{ data: Link } — id, name, slug, url, documentId, dataRoomId, groupId, viewCount, hasPassword, createdAt, updatedAt, and every setting POST accepts under the same name. ndaText is null while an agreementId supplies the terms. groupId marks a room link made in the app for one viewer group: it admits only that group's members and shows only the files the group was given, whatever allowDownload says.

PATCH/api/v1/links/:idlinks:write

Change any setting; omitted fields are kept. Tightening a gate re-gates visitors who already cleared it — a new password or new terms are asked for again, and the address lists are re-checked on every visit, so a newly blocked address is turned away on its next one.

Body (JSON)

…same as POST: Every setting POST accepts, all optional. documentId and dataRoomId are not among them: a link points at what it was made for.

Returns

{ data: Link }

422 A pinned version that is not this document's (or any pin on a room link), an agreement that is not in your library, or an `ogImageUrl` / `ogFaviconUrl` that is not http or https. A viewer-group link cannot be made public, or switched back on once its group has been deleted.

DELETE/api/v1/links/:idlinks:write

The link stops answering. Its visits are kept, because they are evidence about who read what.

Returns

204

POST/api/v1/links/:id/duplicatelinks:write

The same link again under its own URL and its own view count — how a second audience gets the same gates, and how one can later be revoked without touching the other. Everything copies: gates, password, watermark, terms, tags, preview card, any viewer group. The copy is live even when the original is off or expired; a passed expiry becomes the same length of window from now.

Body (JSON)

namestring: 1–120 characters. Defaults to “<name> (copy)”. The body may be left out entirely.

Returns

201 { data: Link } — raises link.created with copiedFrom in its metadata

409 What the link points at is in the trash or gone, or its viewer group has been deleted, so a copy would never open.
422 The plan's link ceiling has been reached.

GET/api/v1/links/:id/invitationslinks:read

Who the link was mailed to from XDocs, newest first, and what became of each mail.

Returns

{ data: Invitation[] } — id, shareLinkId, email, message, delivery (unsent, sent, delivered, failed or bounced, as the mail provider reports it), deliveryError, sentAt, viewedAt (when they first cleared the link's gates), createdAt

POST/api/v1/links/:id/invitationslinks:write

Mail the link to people under your branding. Each address is let past the link's own gates first — added to its allowlist when it has one, to its viewer group when it is a group link — and inviting somebody again re-sends and updates their row.

Body (JSON)

emailsstring[]required: Up to 100. Anything that is not an address is skipped.
messagestring: A note in the mail, up to 2,000 characters.

Returns

201 { data: Invitation[], sent: string[], failed: [{ email, reason }] } — data is the rows for these addresses. An address on the link's blockedEmails (or at a blocked domain) is not mailed or added, and comes back in failed.

409 The link cannot be opened: switched off, expired, at its view cap, pointing at something in the trash, or into an archived room.
422 None of the entries is an email address, or every one is blocked on the link.

DELETE/api/v1/links/:id/invitations/:invitationIdlinks:write

Forget an invitation. Only the record of the mail goes: an address it added to the link's allowlist or viewer group stays, so take it off there to shut the person out.

Returns

204

← The whole API reference Next: Virtual data room API →