Subscriptions Methods

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.13. 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.13/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.13. 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.13. 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.13/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.13. 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

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>
   <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.13/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.13. 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!