Subscriptions Methods

Version: 2021.2

Using the subscriptions methods of the Tableau Server REST API you can do the operations listed in the following category:

Subscriptions (scheduled e-mails to users of snapshots of a workbook's views)

List all subscriptions configured for a site or get the details of a specific subscription
Create a subscription to a workbook or view for a user and add it to a schedule
Update or delete a subscription for a user
Set or get the format of images delivered by a subscription
Suspend or resume a subscription

This functionality relates to the UI elements and concepts described at: Subscribe to Views(Link opens in a new window).

Create Subscription

Creates a new, unsuspended subscription to a view or workbook for a specific user. When a user is subscribed to the content, Tableau Server sends the content to the user in email on the schedule that's defined in Tableau Server and specified in this call.

For more information, see Subscribe to Views(Link opens in a new window) in the Tableau Server documentation.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

POST /api/api-version/sites/site-id/subscriptions

Parameter Values

api-version	The version of the API to use, such as `3.12`. For more information, see REST API and Resource Versions.
site-id	The ID of the site to create the subscription in.

Request Body

<tsRequest>
  <subscription
	subject="subscription-subject"
	attachImage="attach-image-flag"
	attachPdf="attach-pdf-flag"
	pageOrientation="page-orientation"
	pageSizeOption="page-size-option">
	message="message">
	  <content id="content-id"
        type="content-type"
		sendIfViewEmpty="send-view-if-empty-flag"/>
	  <schedule id="schedule-id" />
	  <user id="user-id" />
	</subscription>
</tsRequest>

Attribute Values

subscription-subject	A description for the subscription. This description is displayed when users list subscriptions for a site in the server environment. A description is required.
attach-image-flag	(Optional) Setting this `true` will cause the subscriber to receive mail with .png images of workbooks or views attached to it. This is the default behavior if neither `attachImage` or `attachPdf` are specified. If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets `attachImage` to `false` will cause an error.
attach-pdf-flag	(Optional) Setting this `true` will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it. If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets `attachPdf` to `true` will cause an error.
page-orientation	(Optional) The orientation of the pages produced when attach-pdf-flag is `true`. The value can be `Portrait` or `Landscape`. If this parameter is not present the page orientation will default to `Portrait`.
page-size-option	(Optional) The type of page produced, which determines the page dimensions when attach-pdf-flag is `true`. The value can be: `A3`, `A4`, `A5`, `B5`, `Executive`, `Folio`, `Ledger`, `Legal`, `Letter`, `Note`, `Quarto`, or `Tabloid`. If this parameter is not present the page type will default to `Letter`.
message	The text body of the subscription email message.
content-type	`Workbook` to create a subscription for a workbook, or `View` to create a subscription for a view.
send-view-if-empty-flag	(Optional) Applies to views only. If `true`, an image is sent even if the view specified in a subscription is empty. If `false`, nothing is sent if the view is empty. The default value is true.
content-id	The ID of the workbook or view to subscribe to.
schedule-id	The ID of a schedule to associate the subscription with. To determine what schedules are available, call Query Schedules. The type of the schedule must be `Subscription`.
user-id	The ID of the user to create the subscription for. Note: The user must have an email address defined in Tableau Server.

Permissions

The following list summarizes the permissions required to subscribe a user to specific content:

Tableau Server users who are server administrators can subscribe any user to any content.
Site administrators can subscribe any user on the site to any content on that site.
Project leaders can subscribe users to any content that they are project leaders for.
Content owners can subscribe users to any content they own.
Non-owners can subscribe themselves to any content that they have Read (view) permissions for.

Response Code

201

Response Body

<tsResponse>
  <subscription id="subscription-id"
	subject="subscription-subject"
	suspended="suspended-flag"
	pageOrientation="page-orientation"
	pageSizeOption="page-size-option" >
	  <content id="content-id"
		type="content-type" />
	  <schedule id="schedule-id" name="schedule-name" />
	  <user id="user-id" name="user-name" />
  </subscription>
</tsResponse>

Response Headers

Location: /api/3.12/sites/site-id/subscriptions/new-subscription-id

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400067	Invalid subscription subject	The subscription subject is null or empty.
400	400068	Invalid subscription target	The content type specified in the request body is not a workbook or view.
400	400069	Invalid subscription type	The subscription type is not `Workbook` or `View`.
400	400069	Invalid schedule type	The schedule type is not `Subscription`.
403	403060	No permissions to create subscription.	The user does not have permission to create a subscription for the specified content.
403	403063	No user permissions for content.	The user specified in the request body does not have Read (view) permissions for the specified content.
403	403064	No user email address.	The user does not have an email address.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
404	404002	User not found	The user specified in the request body doesn't correspond to an existing user.
400	404006	Workbook not found	The workbook ID in the request body doesn't correspond to an existing workbook.
404	404011	View not found	The view ID in the request body doesn't correspond to an existing view.
404	404023	Schedule not found	The schedule ID in the request body doesn't correspond to an existing schedule.
405	405000	Invalid request method	Request type was not POST.

For more information, see Handling Errors.

Delete Subscription

Deletes the specified subscription.

URI

DELETE /api/api-version/sites/site-id/subscriptions/subscription-id

Parameter Values

api-version	The version of the API to use, such as `3.12`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the subscription.
subscription-id	The ID of the subscription to delete. To determine what subscriptions are available, call Query Subscriptions.

Request Body

None

Permissions

Tableau Server users can call this method to delete any subscription that they had permission to create. For details, see Create Subscription.

Response Code

204

Response Body

None

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
400	400062	Error deleting the subscription.	An unspecified error occured during the deletion operation.
401	401002	User not authenticated.	The user making the request has not been authenticated for this site.
403	403059	Delete forbidden.	A non-administrator user called this method but doesn't have permission to delete the subscription.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not DELETE.

For more information, see Handling Errors.

Query Subscription

Returns information about the specified subscription.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

GET /api/api-version/sites/site-id/subscriptions/subscription-id

Parameter Values

api-version	The version of the API to use, such as `3.12`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the subscriptions.
subscription-id	The ID of the subscription to get information for.

Request Body

None

Permissions

Tableau Server administrators and all site administrators can get subscription information for users of projects within the scope of their administrative permissions. Other users can get subscription information only for their own subscriptions.

Response Code

200

Response Body

<tsResponse>
   <subscription id="subscription-id" subject="subscription-subject"
	 attachImage="attach-image-flag" attachPdf="attach-pdf-flag"
	 suspended="suspended-flag"
	 pageOrientation="page-orientation"
	 pageSizeOption="page-size-option" ">
	   <content id="content-id"
	 	 type="content-type"
		 sendIfViewEmpty="send-view-if-empty-flag"/>
	   <schedule id="schedule-id" name="schedule-name" />
       <user id="user-id" name="user-name" />
   </subscription>
 </tsResponse>

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
403	403058	Unauthorized	The user attempted to get information for a subscription that they don't have permission to access.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
404	404025	Subscription not found	The specified subscription doesn't correspond to an existing subscription.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.12/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/subscriptions/59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <subscription id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" subject="Daily Statistics"
    attachImage="false" attachPdf="true" "suspended="false"
	pageOrientation="Landscape"
	pageSizeOption="A4" >
      <content id="08b50973-a526-4f65-b898-829e6292c949" type="View" sendIfViewEmpty="true"/>
      <schedule id="67e341a3-7c58-4605-9897-7db1e565e827" name="Mondays" />
      <user id="c6f87a48-f603-41dc-af0c-8098c763df97" name="joe@example.com" />
  </subscription>
</tsResponse>

Query Subscriptions

Returns a list of all the subscriptions on the specified site.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

GET /api/api-version/sites/site-id/subscriptions

GET /api/api-version/sites/site-id/subscriptions?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version	The version of the API to use, such as `3.12`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the subscriptions.
page-size	(Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number	(Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Response Code

200

Response Body

<tsResponse>
   <pagination pageNumber="pageNumber"
    pageSize="page-size"
    totalAvailable="total-available"  />
   <subscriptions>
     <subscription id="subscription-id"
       subject="subscription-subject"
	   attachImage="attach-image-flag"
       attachPdf="attach-pdf-flag"
       suspended="suspended-flag"
	   pageOrientation="page-orientation"
	   pageSizeOption="page-size-option" >
		 <content id="content-id"
		   type="content-type"
		   sendIfViewEmpty="send-view-if-empty-flag"/>
         <schedule id="schedule-id" name="schedule-name"
         <user id="user-id" name="user-name" />
     </subscription>
     <!--   ... additional subscriptions ...   -->
   </subscriptions>
 </tsResponse>

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
400	400006	Invalid page number	The page number parameter is not an integer, is less than one, or is greater than the final page number for the sites at the requested page size.
400	400007	Invalid page size	The page size parameter is not an integer, or is less than one.
403	403014	Page size limit exceeded	The specified page size is larger than the maximum page size.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.12/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/subscriptions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <subscriptions>
    <subscription id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" subject="Daily Statistics"
	  attachImage="false" attachPdf="true" suspended="false"
 	    pageOrientation="Lanscape" pageSizeOption="A4" >
          <content id="08b50973-a526-4f65-b898-829e6292c949" type="View" sendIfViewEmpty="true"/>
          <schedule id="67e341a3-7c58-4605-9897-7db1e565e827" name="Mondays" />
          <user id="c6f87a48-f603-41dc-af0c-8098c763df97" name="joe@example.com" />
    </subscription>
	<subscription id="672930ac-b7d2-4ed9-beb7-d931241f8209" subject="Sales Update" "suspended="true""
	  pageOrientation="Portrait" pageSizeOption="Letter" >
        <content id="8fcd394e-27f4-4071-9c5a-2dfed2ad1230" type="View" />
        <schedule id="67e341a3-7c58-4605-9897-7db1e565e827" name="Weekly Updates" />
        <user id="e54cde3c-0c44-4024-a34e-8cab98f58ea2" name="Michelle@example.com" />
    </subscription>
  </subscriptions>
</tsResponse>

Update Subscription

Modifies an existing subscription, allowing you to change the subject, schedule, and suspension state for the subscription.

URI

PUT /api/api-version/sites/site-id/subscriptions/subscription-id

Parameter Values

api-version	The version of the API to use, such as `3.12`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
subscription-id	The ID of the subscription to update.

Request Body

<tsRequest>
  <subscription
	subject="subscription-subject"
	attachImage="attach-image-flag"
	attachPdf="attach-pdf-flag"
	pageOrientation="page-orientation"
	pageSizeOption="page-size-option"
	suspended="suspended-flag">
	  <schedule id="new-schedule-id"
	  <content sendIfViewEmpty="send-view-if-empty-flag" />
  </subscription>
</tsRequest>

Attribute Values

new-subscription-subject	(Optional) A new subject for the subscription.
attach-image-flag	(Optional) Setting this `true` will cause the subscriber to receive mail with .png images of workbooks or views attached to it. This is the default behavior if neither `attachImage` or `attachPdf` are specified. If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets `attachImage` to `false` will cause an error.
attach-pdf-flag	(Optional) Setting this `true` will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it. If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets `attachPdf` to `true` will cause an error.
page-orientation	(Optional) The orientation of the pages produced when attach-pdf-flag is `true`. The value can be `Portrait` or `Landscape`. If this parameter is not present the page orientation will default to `Portrait`.
page-size-option	(Optional) The type of page produced, which determines the page dimensions when attach-pdf-flag is `true`. The value can be: `A3`, `A4`, `A5`, `B5`, `Executive`, `Folio`, `Ledger`, `Legal`, `Letter`, `Note`, `Quarto`, or `Tabloid`. If this parameter is not present the page type will default to `Letter`.
suspended-flag	(Optional boolean) Setting `suspended` to `true` stops email delivery for the specified subscription. Setting it to `false` will resume email delivery for the subscription.
new-schedule-id	(Optional) The ID of a schedule to associate this subscription with. To determine what schedules are available, call Query Schedules. The type of the schedule must be `Subscription`.
send-view-if-empty-flag	(Optional) Applies to views only. If `true`, an image is sent even if the view specified in a subscription is empty. If `false`, nothing is sent if the view is empty. The default value is true.

Permissions

Tableau Server users can call this method to update any subscription that they have permission to create. For details, see Create Subscription.

Response Code

200

Response Body

<tsResponse>
  <subscription id="subscription-id"
	subject="subscription-subject"
	suspended="suspended-flag"
	pageOrientation="page-orientation"
	pageSizeOption="page-size-option" >
	  <content id="content-id"
	    type="content-type"
	    sendIfViewEmpty="send-view-if-empty-flag"/>
	  <schedule id="schedule-id" name="schedule-name" />
	  <user id="user-id" name="user-name" />
  </subscription>
</tsResponse>

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400067	Invalid subscription subject	The subscription subject is null or empty.
400	400069	Invalid subscription type	The subscription type is not `Workbook` or `View`.
400	400069	Invalid schedule type	The schedule type is not `Subscription`.
400	400133	Invalid data condition type	The data condition type is invalid for the subscription.
403	403065	No permissions to update subscription.	The user does not have permission to update the specified subscription.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
404	404023	Schedule not found	The schedule ID in the request body doesn't correspond to an existing schedule.
405	405000	Invalid request method	Request type was not PUT.

For more information, see Handling Errors.

Thanks for your feedback!

Tableau REST API Help

Subscriptions Methods

Create Subscription

URI

Parameter Values

Request Body

Attribute Values

Permissions

Response Code

Response Body

Response Headers

Version

Errors

Delete Subscription

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Version

Errors

Query Subscription

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Version

Errors

Example

Query Subscriptions

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Version

Errors

Example

Update Subscription

URI

Parameter Values

Request Body

Attribute Values

Permissions

Response Code

Response Body

Version

Errors