Users can subscribe to sections, articles, community posts, and community topics. Users are notified when somebody adds an article to a section, adds a comment to an article or a post, or adds a post to a topic.

JSON Format

Subscriptions are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
content_id integer true false The id of the subscribed item
content_type string true false The type of the subscribed item
created_at string true false The time at which the subscription was created
id integer true false Automatically assigned when the subscription is created
include_comments boolean true false Subscribe also to article comments. Only for section subscriptions.
locale string true true The locale of the subscribed item
updated_at string true false The time at which the subscription was last updated
url string true false The API url of the subscription
user_id integer true false The id of the user who has this subscription

Example

{  "content_id": 65466,  "created_at": "2012-04-04T09:14:57Z",  "id": 1635,  "locale": "en-us",  "user_id": 3465}

List Subscriptions By User

  • GET /api/v2/help_center/users/{user_id}/subscriptions

Lists the subscriptions of a given user. To list your own subscriptions, specify me as the user id.

Allowed for

  • Agents
  • End-users

Sideloads

The following sideloads are supported:

Name Will sideload For
users users all
articles articles article subscriptions
sections sections section subscriptions
questions questions question subscriptions
topics topics topic subscriptions
translations translations article or section subscriptions

Parameters

Name Type In Required Description
type string Query false List the user subscriptions of a particular user. Allowed values are "followings", or "followers".
user_id integer Path true The unique ID of the user

Using curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/users/{user_id}/subscriptions.json \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "subscriptions": [    {      "content_id": 8748733,      "content_type": "Article",      "id": 35467,      "locale": "en",      "user_id": 888887    }  ]}

List Topic Subscriptions

  • GET /api/v2/community/topics/{topic_id}/subscriptions

Lists the subscriptions to a given topic.

Allowed for

  • Agents
  • End-users

For end-users, the response will list only the subscriptions created by the requesting end-user.

Sideloads

The following sideloads are supported:

Name Will sideload
users users
topics topics

Parameters

Name Type In Required Description
topic_id integer Path true The unique ID of the topic

Using curl

curl https://{subdomain}.zendesk.com/api/v2/community/topics/{topic_id}/subscriptions.json \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "subscriptions": [    {      "content_id": 8748733,      "id": 35467,      "locale": "en",      "user_id": 888887    }  ]}

Show Topic Subscription

  • GET /api/v2/community/topics/{topic_id}/subscriptions/{subscription_id}

Allowed for

  • Agents
  • End-users

For end-users, the response will only show a subscription created by the requesting end-user.

Sideloads

The following sideloads are supported:

Name Will sideload For
users users all
topics topics topic subscriptions

Parameters

Name Type In Required Description
subscription_id integer Path true The unique ID of the subscription
topic_id integer Path true The unique ID of the topic

Using curl

curl https://{subdomain}.zendesk.com/api/v2/community/topics/{topic_id}/subscriptions/{subscription_id}.json \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "subscription": {    "content_id": 8748733,    "id": 35467,    "locale": "en",    "user_id": 888887  }}

Create Topic Subscription

  • POST /api/v2/community/topics/{topic_id}/subscriptions

Creates a subscription to a given topic.

Allowed for

  • End-users

Agents with the Help Center manager role can optionally supply a user_id value. If provided, the user associated with user_id will be subscribed to the topic.

Parameters

Name Type In Required Description
topic_id integer Path true The unique ID of the topic

Using curl

# you can use `"include_comments": true` to Subscribe also to new post comments. Default is falsecurl https://{subdomain}.zendesk.com/api/v2/community/topics/{topic_id}/subscriptions.json \  -d '{"subscription": {"include_comments": true}}' \  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"
# with `user_id`curl https://{subdomain}.zendesk.com/api/v2/community/topics/{topic_id}/subscriptions.json \  -d '{"subscription": {"include_comments": false, "user_id": 10056}}' \  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

Example Response

Status 201 Created
{  "subscription": {    "content_id": 8748733,    "id": 35467,    "locale": "en",    "user_id": 888887  }}

Update Topic Subscription

  • PUT /api/v2/community/topics/{topic_id}/subscriptions/{subscription_id}

Allowed for

  • End-users

Parameters

Name Type In Required Description
subscription_id integer Path true The unique ID of the subscription
topic_id integer Path true The unique ID of the topic

Using curl

curl https://{subdomain}.zendesk.com/api/v2/community/topics/{topic_id}/subscriptions/{subscription_id}.json \  -d '{"subscription": {"include_comments": true}}' \  -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"

Example Response

Status 200 OK
{  "subscription": {    "content_id": 8748733,    "id": 35467,    "locale": "en",    "user_id": 888887  }}

Delete Topic Subscription

  • DELETE /api/v2/community/topics/{topic_id}/subscriptions/{subscription_id}

Removes a subscription to a given topic.

Allowed for

  • End-users

Parameters

Name Type In Required Description
subscription_id integer Path true The unique ID of the subscription
topic_id integer Path true The unique ID of the topic

Using curl

curl https://{subdomain}.zendesk.com/api/v2/community/topics/{topic_id}/subscriptions/{subscription_id}.json \  -v -u {email_address}:{password} -X DELETE

Example Response

Status 204 No Content

List Post Subscriptions

  • GET /api/v2/community/posts/{post_id}/subscriptions

Lists the subscriptions to a given post.

Allowed for

  • Agents
  • End-users

For end-users, the response will list only the subscriptions created by the requesting end-user.

Sideloads

The following sideloads are supported:

Name Will sideload
users users
posts posts

Parameters

Name Type In Required Description
post_id integer Path true The unique ID of the post

Using curl

curl https://{subdomain}.zendesk.com/api/v2/community/posts/{post_id}/subscriptions.json \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "subscriptions": [    {      "content_id": 8748733,      "id": 35467,      "locale": "en",      "user_id": 888887    }  ]}

Show Post Subscription

  • GET /api/v2/community/posts/{post_id}/subscriptions/{subscription_id}

Allowed for

  • Agents
  • End-users

For end-users, the response will only show a subscription created by the requesting end-user.

Sideloads

The following sideloads are supported:

Name Will sideload For
users users all
posts posts post subscriptions

Parameters

Name Type In Required Description
post_id integer Path true The unique ID of the post
subscription_id integer Path true The unique ID of the subscription

Using curl

curl https://{subdomain}.zendesk.com/api/v2/community/posts/{post_id}/subscriptions/{subscription_id}.json \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "subscription": {    "content_id": 8748733,    "id": 35467,    "locale": "en",    "user_id": 888887  }}

Create Post Subscription

  • POST /api/v2/community/posts/{post_id}/subscriptions

Creates a subscription to a given post.

Allowed for

  • End-users

Agents with the Help Center manager role can optionally supply a subscription object containing a user_id value. If provided, the user associated with user_id will be subscrbed to the post.

Parameters

Name Type In Required Description
post_id integer Path true The unique ID of the post

Using curl

curl https://{subdomain}.zendesk.com/api/v2/community/posts/{post_id}/subscriptions.json \  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"
# with `user_id`curl https://{subdomain}.zendesk.com/api/v2/community/posts/{post_id}/subscriptions.json \  -d '{"subscription": {"user_id": 10056}}' \  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

Example Response

Status 201 Created
{  "subscription": {    "content_id": 8748733,    "id": 35467,    "locale": "en",    "user_id": 888887  }}

Delete Post Subscription

  • DELETE /api/v2/community/posts/{post_id}/subscriptions/{subscription_id}

Removes a subscription to a given post.

Allowed for

  • End-users

Parameters

Name Type In Required Description
post_id integer Path true The unique ID of the post
subscription_id integer Path true The unique ID of the subscription

Using curl

curl https://{subdomain}.zendesk.com/api/v2/community/posts/{post_id}/subscriptions/{subscription_id}.json \  -v -u {email_address}:{password} -X DELETE

Example Response

Status 204 No Content

List Section Subscriptions

  • GET /api/v2/help_center{/locale}/sections/{section_id}/subscriptions

Lists the subscriptions to a given section.

Note: {/locale} is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

Allowed for

  • Agents
  • End-users

For end-users, the response will list only the subscriptions created by the requesting end-user.

Sideloads

The following sideloads are supported:

Name Will sideload
users users
sections sections
translations translations of any sideloaded articles and sections

To sideload the section translations, specify the translations sideload in addition to sections.

Parameters

Name Type In Required Description
locale string Path false The locale the item is displayed in
section_id integer Path true The unique ID of the section

Using curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/sections/{section_id}/subscriptions.json \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "subscriptions": [    {      "content_id": 8748733,      "id": 35467,      "locale": "en",      "user_id": 888887    }  ]}

Show Section Subscription

  • GET /api/v2/help_center{/locale}/sections/{section_id}/subscriptions/{subscription_id}

Note: {/locale} is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

Allowed for

  • Agents
  • End-users

Sideloads

The following sideloads are supported:

Name Will sideload For
users users all
sections sections section subscriptions
translations translations article or section subscriptions

Parameters

Name Type In Required Description
locale string Path false The locale the item is displayed in
section_id integer Path true The unique ID of the section
subscription_id integer Path true The unique ID of the subscription

Using curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/sections/{section_id}/subscriptions/{subscription_id}.json \-v -u {email_address}:{password}

Example Response

Status 200 OK
{  "subscription": {    "content_id": 8748733,    "id": 35467,    "locale": "en",    "user_id": 888887  }}

Create Section Subscription

  • POST /api/v2/help_center{/locale}/sections/{section_id}/subscriptions

Creates a subscription to a given section.

Allowed for

  • End-users

Agents with the Help Center manager role can optionally supply a user_id value. If provided, the user associated with user_id will be subscribed to the section.

Parameters

Name Type In Required Description
locale string Path false The locale the item is displayed in
section_id integer Path true The unique ID of the section

Using curl

# you can use `"include_comments": true` to Subscribe also to new post comments. Default is falsecurl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{section_id}/subscriptions.json \  -d '{"subscription": {"source_locale": "en-us", "include_comments": true}}' \  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"
# with `include_comments`curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{section_id}/subscriptions.json \  -d '{"subscription": {"source_locale": "en-us", "include_comments": false, "user_id": 10056}}' \  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

Example Response

Status 201 Created
{  "subscription": {    "content_id": 8748733,    "id": 35467,    "locale": "en",    "user_id": 888887  }}

Delete Section Subscription

  • DELETE /api/v2/help_center{/locale}/sections/{section_id}/subscriptions/{subscription_id}

Removes the specified subscription from the specified section.

Allowed for

  • End users

Parameters

Name Type In Required Description
locale string Path false The locale the item is displayed in
section_id integer Path true The unique ID of the section
subscription_id integer Path true The unique ID of the subscription

Using curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{section_id}/subscriptions/{subscription_id}.json \  -v -u {email_address}:{password} -X DELETE

Example Response

Status 204 No Content

List Article Subscriptions

  • GET /api/v2/help_center{/locale}/articles/{article_id}/subscriptions

Lists the subscriptions to a given article.

Note: {/locale} is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

Allowed for

  • Agents
  • End-users

For end-users, the response will list only the subscriptions created by the requesting end-user.

Sideloads

The following sideloads are supported:

Name Will sideload
users users
articles articles
sections sections

Note that you need to specify the articles sideload to get the sections and translations sideloaded because these are not directly associated with the subscriptions.

Parameters

Name Type In Required Description
article_id integer Path true The unique ID of the article
locale string Path false The locale the item is displayed in

Using curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/articles/{article_id}/subscriptions.json \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "subscriptions": [    {      "content_id": 8748733,      "id": 35467,      "locale": "en",      "user_id": 888887    }  ]}

Show Article Subscription

  • GET /api/v2/help_center{/locale}/articles/{article_id}/subscriptions/{subscription_id}

Note: {/locale} is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

Allowed for

  • Agents
  • End-users

For end-users, the response will only show a subscription created by the requesting end-user.

Sideloads

The following sideloads are supported:

Name Will sideload For
users users all
articles articles article subscriptions
sections sections section subscriptions

Parameters

Name Type In Required Description
article_id integer Path true The unique ID of the article
locale string Path false The locale the item is displayed in
subscription_id integer Path true The unique ID of the subscription

Using curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/articles/{article_id}/subscriptions/{subscription_id}.json \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "subscription": {    "content_id": 8748733,    "id": 35467,    "locale": "en",    "user_id": 888887  }}

Create Article Subscription

  • POST /api/v2/help_center{/locale}/articles/{article_id}/subscriptions

Creates a subscription to a given article.

Allowed for

  • End-users

Agents with the Help Center manager role can optionally supply a user_id value. If provided, the user associated with user_id will be subscribed to the article.

Parameters

Name Type In Required Description
article_id integer Path true The unique ID of the article
locale string Path false The locale the item is displayed in

Using curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/subscriptions.json \  -d '{"subscription": {"source_locale": "en-us"}}' \  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"
# with `user_id`curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/subscriptions.json \  -d '{"subscription": {"source_locale": "en-us", "user_id": 10056}}' \  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

Example Response

Status 201 Created
{  "subscription": {    "content_id": 8748733,    "id": 35467,    "locale": "en",    "user_id": 888887  }}

Delete Article Subscription

  • DELETE /api/v2/help_center{/locale}/articles/{article_id}/subscriptions/{subscription_id}

Removes the specified subscription from the specified article.

Allowed for

  • End users

Parameters

Name Type In Required Description
article_id integer Path true The unique ID of the article
locale string Path false The locale the item is displayed in
subscription_id integer Path true The unique ID of the subscription

Using curl

curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/subscriptions/{subscription_id}.json \  -v -u {email_address}:{password} -X DELETE

Example Response

Status 204 No Content