Skip to content

GetSubscribers API

Returns the complete subscriber list of a document or folder at the specified path. The response includes both individual user subscribers and user group subscribers, each with their configured event notification flags. Use this API to audit who is subscribed to a document or folder and which events they are watching.

This one operation answers success="TRUE" in capitals, where every other operation in the API answers "true". Its event elements are TRUE/FALSE in capitals too. A client comparing the attribute against the lower case string reads every successful call as a failure.

Endpoint

/srv.asmx/GetSubscribers

Methods

  • GET /srv.asmx/GetSubscribers?authenticationTicket=...&path=...

  • POST /srv.asmx/GetSubscribers (form data)

  • SOAP Action: http://tempuri.org/GetSubscribers

Parameters

Parameter Type Required Description
authenticationTicket string Yes Authentication ticket obtained from AuthenticateUser.
path string Yes Full infoRouter path to the document or folder (e.g. /Finance/Reports/Q1-Report.pdf or /Finance/Reports). Supports short document ID paths (~D{id} or ~D{id}.ext). The API automatically detects whether the path refers to a document or a folder.

Response

Success Response

Returns a <response> element with success="TRUE" containing a <subscribers> element. The <subscribers> element holds zero or more <usersubscriber> elements (for individual users) followed by zero or more <groupsubscriber> elements (for user groups).

<response success="TRUE" error="">

  <subscribers>

    <usersubscriber>

      <userid>7</userid>

      <username>jsmith</username>

      <firstname>John</firstname>

      <lastname>Smith</lastname>

      <email>jsmith@example.com</email>

      <emailtype>HTML</emailtype>

      <language>en</language>

      <attachdocumenttoemail>FALSE</attachdocumenttoemail>

      <userstatus>1</userstatus>

      <on_read>FALSE</on_read>

      <on_change>TRUE</on_change>

      <on_update>TRUE</on_update>

      <on_checkout>FALSE</on_checkout>

      <on_approve>TRUE</on_approve>

      <on_reject>TRUE</on_reject>

      <on_comment>TRUE</on_comment>

      <on_move>TRUE</on_move>

      <on_delete>TRUE</on_delete>

      <on_checkin>FALSE</on_checkin>

      <on_newdoc>FALSE</on_newdoc>

    </usersubscriber>

    <groupsubscriber>

      <groupid>14</groupid>

      <groupname>Finance-Managers</groupname>

      <on_read>FALSE</on_read>

      <on_change>TRUE</on_change>

      <on_update>TRUE</on_update>

      <on_checkout>FALSE</on_checkout>

      <on_approve>TRUE</on_approve>

      <on_reject>TRUE</on_reject>

      <on_comment>FALSE</on_comment>

      <on_move>TRUE</on_move>

      <on_delete>TRUE</on_delete>

      <on_checkin>FALSE</on_checkin>

      <on_newdoc>TRUE</on_newdoc>

    </groupsubscriber>

  </subscribers>

</response>

Empty Result (No Subscribers)

<response success="TRUE" error="">

  <subscribers />

</response>

Error Response

<response success="false" error="Document not found." />

usersubscriber Element Fields

Field Type Description
userid int Unique ID of the subscribed user.
username string Login name of the subscribed user.
firstname string First name of the subscribed user.
lastname string Last name of the subscribed user.
email string Email address of the subscribed user.
emailtype string Email format preference (e.g. HTML or TEXT).
language string Language code for the user's notification emails.
attachdocumenttoemail TRUE/FALSE Whether the document is attached to notification emails.
userstatus int User account status: 1 = active, 0 = inactive/disabled.
on_read TRUE/FALSE Subscribed to read/download events.
on_change TRUE/FALSE Subscribed to property/metadata change events.
on_update TRUE/FALSE Subscribed to new version upload events.
on_checkout TRUE/FALSE Subscribed to checkout events.
on_approve TRUE/FALSE Subscribed to approval events.
on_reject TRUE/FALSE Subscribed to rejection events.
on_comment TRUE/FALSE Subscribed to comment events.
on_move TRUE/FALSE Subscribed to move events.
on_delete TRUE/FALSE Subscribed to deletion events.
on_checkin TRUE/FALSE Subscribed to check-in events.
on_newdoc TRUE/FALSE Subscribed to new document events (folder subscriptions only; always FALSE for document subscriptions).

groupsubscriber Element Fields

Field Type Description
groupid int Unique ID of the subscribed user group.
groupname string Name of the subscribed user group.
on_read -" on_newdoc TRUE/FALSE Same event flags as for user subscribers (see table above).

Required Permissions

Any authenticated user with read access to the document or folder can call this API.

Example

GET Request

GET /srv.asmx/GetSubscribers

  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301

  &path=/Finance/Reports/Q1-2024-Report.pdf

HTTP/1.1

GET Request -" Folder

GET /srv.asmx/GetSubscribers

  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301

  &path=/Finance/Reports

HTTP/1.1

POST Request

POST /srv.asmx/GetSubscribers HTTP/1.1

Content-Type: application/x-www-form-urlencoded

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301

&path=/Finance/Reports/Q1-2024-Report.pdf

SOAP Request

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

               xmlns:tns="http://tempuri.org/">

  <soap:Body>

    <tns:GetSubscribers>

      <tns:AuthenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:AuthenticationTicket>

      <tns:Path>/Finance/Reports/Q1-2024-Report.pdf</tns:Path>

    </tns:GetSubscribers>

  </soap:Body>

</soap:Envelope>

JavaScript

Every call answers XML with HTTP 200, success or not, so success is the thing to branch on and errorCode is the number to report.

async function call(action, params) {
  const response = await fetch(`/srv.asmx/${action}?${new URLSearchParams(params)}`);
  const root = new DOMParser()
    .parseFromString(await response.text(), 'text/xml')
    .documentElement;

  if (root.getAttribute('success') !== 'true') {
    throw new Error(`${root.getAttribute('errorCode')}: ${root.getAttribute('error')}`);
  }
  return root;
}

Reads who is subscribed to a document or a folder.

// GetSubscribers answers success="TRUE" in capitals, so compare case-insensitively.
const response = await fetch(
  `/srv.asmx/GetSubscribers?${new URLSearchParams({ authenticationTicket: ticket, Path: '/Public/Reports/q3.pdf' })}`);
const root = new DOMParser().parseFromString(await response.text(), 'text/xml').documentElement;

if (root.getAttribute('success').toLowerCase() !== 'true') {
  throw new Error(`${root.getAttribute('errorCode')}: ${root.getAttribute('error')}`);
}

for (const subscriber of root.querySelectorAll('usersubscriber')) {
  console.log(subscriber.querySelector('username').textContent,
              subscriber.querySelector('on_read').textContent);   // TRUE or FALSE, also in capitals
}

Notes

  • Document and Folder: The same API serves both documents and folders. The path is resolved first as a document; if not found, it is resolved as a folder. If neither is found, an error is returned.

  • User Subscribers Sorted: User subscribers are returned sorted by first name in ascending order.

  • Group Subscribers Sorted: Group subscribers are returned sorted by group name in ascending order.

  • on_newdoc for Documents: The on_newdoc field is always FALSE for document subscriber entries, since new-document events only apply to folder subscriptions.

  • userstatus Values: A userstatus of 1 indicates an active account; 0 indicates a disabled or inactive account. Disabled users will not receive notifications.

  • Short Path Support: The path parameter supports short document ID notation: ~D123 or ~D123.pdf.

  • Empty List: If no subscribers exist, the <subscribers> element is returned empty -" this is not an error.

  • Response Case: The success attribute value is TRUE (uppercase) on success, unlike most other APIs which use lowercase true.

Error Codes

The errorCode values this operation returns, checked against a running server:

errorCode When
4010 the ticket is expired or unknown, or there is no ticket at all
4041 no document or folder at that path, including one the caller may not see
HTTP 400 a required string parameter was empty; refused by model binding, so there is no error document