API reference

Views and visitors API

Reading is measured section by section, and time only accrues while a section is on screen in an active tab — attention, not page loads. Pull visits and visitors into a CRM, or export them as CSV.

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.

Views and visitors

Reading measured section by section. Time accrues only while a section is on screen and the tab is active, so these are attention numbers rather than tab-left-open numbers.

GET/api/v1/viewsviews:read

Visits, newest first. A visit counts once every gate was cleared.

Query parameters

documentIdstring
dataRoomIdstring
shareLinkIdstring
emailstring
sinceISO 8601 datetime: Visits started at or after this.
includeUnopenedboolean: true also lists visits that never cleared the gates.
limitinteger: Rows per page, up to 100. Defaults to 50.
cursorstring: The previous page's nextCursor. Opaque — pass it back unchanged.

Returns

{ data: View[], nextCursor } — id, shareLinkId, documentId, dataRoomId, viewerEmail, emailVerified, ndaAcceptedAt, ndaText (the exact terms accepted, whatever the link says now), ndaSignedName, openedAt (null until every gate was cleared), lastOpenedAt, startedAt, lastSeenAt, totalMs (active reading, not wall clock), opens (separate sittings), completion, downloadedAt, captureAnswers (keyed by the link's capture field id), country, city, referrer, userAgent, ipAddress

400 `since` is not a timestamp.

GET/api/v1/views/:idviews:read

One visit with its per-section reading — per page for a PDF.

Returns

{ data: View & { sections: [{ documentId, index, heading, visibleMs }] } } — a room visit carries several documents' sections, told apart by documentId

GET/api/v1/visitorsviews:read

Visits grouped by the person who made them: not “opened nine times” but “this person has read four documents for an hour”.

Query parameters

documentIdstring
dataRoomIdstring
shareLinkIdstring
emailstring: One visitor, by the address they gave.
sinceISO 8601 datetime
limitinteger: Rows per page, up to 100. Defaults to 50.
cursorstring: The previous page's nextCursor. Opaque — pass it back unchanged.

Returns

{ data: Visitor[], nextCursor } — email, views, documents, totalMs, avgCompletion, firstSeenAt, lastSeenAt, verified, acceptedNda, downloaded. Only visits that captured an address and cleared the gates are counted.

400 `since` is not a timestamp.

GET/api/v1/visitors/:emailviews:read

One person, with their most recent visits.

Returns

{ data: Visitor & { views: View[] } } — the latest 100 visits

400 The path is not a URL-encoded email address.
404 No visits from that address.

GET/api/v1/visits/exportdocuments:read

Every counted visit as CSV, one row per visit per document read — the file the settings page offers.

Query parameters

fromISO 8601 date or datetime: Visits from this moment.
toISO 8601 date or datetime: Visits up to this moment. A bare date covers the whole of that day.

Returns a file

A CSV file.

← The whole API reference Next: Document analytics API →