Help Center API

Subscriptions

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 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 this 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
    }
  ]
}

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 this 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
  }
}

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 this Post
subscription_id integer Path true The unique ID of this 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
  }
}

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 this Post
subscription_id integer Path true The unique ID of this 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 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 this 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
    }
  ]
}

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 this Topic
Using curl
 
# you can use `"include_comments": true` to Subscribe also to new post comments. Default is false
curl 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
  }
}

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 this Subscription
topic_id integer Path true The unique ID of this 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
  }
}

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 this Subscription
topic_id integer Path true The unique ID of this 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 this Subscription
topic_id integer Path true The unique ID of this 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 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 this 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 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 this Article
locale string Path false The locale that the category 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
    }
  ]
}

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 this Article
locale string Path false The locale that the category 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
  }
}

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 this Article
locale string Path false The locale that the category is displayed in
subscription_id integer Path true The unique ID of this 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
  }
}

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 this Article
locale string Path false The locale that the category is displayed in
subscription_id integer Path true The unique ID of this 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

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 that the category is displayed in
section_id integer Path true The unique ID of this 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
    }
  ]
}

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 that the category is displayed in
section_id integer Path true The unique ID of this Section
Using curl
 
# you can use `"include_comments": true` to Subscribe also to new post comments. Default is false
curl 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
  }
}

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 that the category is displayed in
section_id integer Path true The unique ID of this Section
subscription_id integer Path true The unique ID of this 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
  }
}

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 that the category is displayed in
section_id integer Path true The unique ID of this Section
subscription_id integer Path true The unique ID of this 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