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 have the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when the subscription is created
url string yes no The API url of the subscription
user_id integer yes no The id of the user who has this subscription
content_id integer yes no The id of the subscribed item
content_type string yes no The type of the subscribed item
locale string yes yes The locale of the subscribed item
include_comments boolean yes no Subscribe also to article comments. Only for section subscriptions.
created_at timestamp yes no The time at which the subscription was created
updated_at timestamp yes no The time at which the subscription was last updated
Example
 
{
  "id":         1635,
  "user_id":    3465,
  "value":      1,
  "content_id": 65466,
  "locale":     "en-us",
  "created_at": "2012-04-04T09:14:57Z",
  ...
}

List Article Subscriptions

GET /api/v2/help_center/{locale}/articles/{article_id}/subscriptions.json

Lists the subscriptions to a given article.

The {locale} is required only for end users. Admins and agents can omit it.

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.

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": [
    {
      "id":          35467,
      "user_id":     888887,
      "content_id":   8748733,
      ...
    },
    ...
  ]
}

Show Article Subscription

GET /api/v2/help_center/{locale}/articles/{article_id}/subscriptions/{id}.json

The {locale} is required only for end users. Admins and agents can omit it.

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/articles/{article_id}/subscriptions/{id}.json \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

{
  "subscription": {
    "id":          35467,
    "user_id":     888887,
    "content_id":   8748733,
    ...
  }
}

Create Article Subscription

POST /api/v2/help_center/articles/{article_id}/subscriptions.json

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.

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"

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
Location: https://{subdomain}.zendesk.com/api/v2/help_center/subscriptions/{id}.json

{
  "subscription": {
    "id":          35467,
    "user_id":     888887,
    "content_id":   8748733,
    ...
  }
}

Delete Article Subscription

DELETE /api/v2/help_center/articles/{article_id}/subscriptions/{sub_id}.json

Removes the specified subscription from the specified article.

Allowed for
  • End users
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/subscriptions/{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.json

Lists the subscriptions to a given section.

The {locale} is required only for end users. Admins and agents can omit it.

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.

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": [
    {
      "id":          35467,
      "user_id":     888887,
      "content_id":   8748733,
      ...
    },
    ...
  ]
}

Show Section Subscription

GET /api/v2/help_center/{locale}/sections/{section_id}/subscriptions/{id}.json

The {locale} is required only for end users. Admins and agents can omit it.

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/sections/{section_id}/subscriptions/{id}.json \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

{
  "subscription": {
    "id":          35467,
    "user_id":     888887,
    "content_id":   8748733,
    ...
  }
}

Create Section Subscription

POST /api/v2/help_center/sections/{section_id}/subscriptions.json

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.

Available Parameters
Name Type Required Comments
include_comments boolean no Subscribe also to new article comments. Default is false
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{id}/subscriptions.json \
  -d '{"subscription": {"source_locale": "en-us", "include_comments": true}}' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{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
Location: https://{subdomain}.zendesk.com/api/v2/help_center/subscriptions/{id}.json

{
  "subscription": {
    "id":          35467,
    "user_id":     888887,
    "content_id":   8748733,
    ...
  }
}

Delete Section Subscription

DELETE /api/v2/help_center/sections/{section_id}/subscriptions/{sub_id}.json

Removes the specified subscription from the specified section.

Allowed for
  • End users
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{section_id}/subscriptions/{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.json

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/help_center/users/{id}/subscriptions.json \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

{
  "subscriptions": [
    {
      "id":        35467,
      "user_id":   888887,
      "content_id": 8748733,
      "content_type: "Article",
      ...
    },
    ...
  ]
}

List Post Subscriptions

GET /api/v2/community/posts/{post_id}/subscriptions.json

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
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": [
    {
      "id":          35467,
      "user_id":     888887,
      "content_id":   8748733,
      ...
    },
    ...
  ]
}

Show Post Subscription

GET /api/v2/community/posts/{post_id}/subscriptions/{id}.json

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/community/posts/{post_id}/subscriptions/{id}.json \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

{
  "subscription": {
    "id":          35467,
    "user_id":     888887,
    "content_id":   8748733,
    ...
  }
}

Create Post Subscription

POST /api/v2/community/posts/{post_id}/subscriptions.json

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.

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"

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
Location: https://{subdomain}.zendesk.com/api/v2/community/subscriptions/{id}.json

{
  "subscription": {
    "id":          35467,
    "user_id":     888887,
    "content_id":   8748733,
    ...
  }
}

Delete Post Subscription

DELETE /api/v2/community/posts/{post_id}/subscriptions/{id}.json

Removes a subscription to a given post.

Allowed for
  • End-users
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/community/posts/{post_id}/subscriptions/{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.json

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
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": [
    {
      "id":          35467,
      "user_id":     888887,
      "content_id":   8748733,
      ...
    },
    ...
  ]
}

Show Topic Subscription

GET /api/v2/community/topics/{topic_id}/subscriptions/{id}.json

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/community/topics/{topic_id}/subscriptions/{id}.json \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

{
  "subscription": {
    "id":          35467,
    "user_id":     888887,
    "content_id":   8748733,
    ...
  }
}

Create Topic Subscription

POST /api/v2/community/topics/{topic_id}/subscriptions.json

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.

Available Parameters
Name Type Required Comments
include_comments boolean no Subscribe also to new post comments. Default is false
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/community/topics/{id}/subscriptions.json \
  -d '{"subscription": {"include_comments": true}}' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

curl https://{subdomain}.zendesk.com/api/v2/community/topics/{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
Location: https://{subdomain}.zendesk.com/api/v2/community/subscriptions/{id}.json

{
  "subscription": {
    "id":          35467,
    "user_id":     888887,
    "content_id":   8748733,
    ...
  }
}

Update Topic Subscription

PUT /api/v2/community/topics/{topic_id}/subscriptions.json

Allowed for
  • End-users
Available Parameters
Name Type Required Comments
include_comments boolean no Subscribe also to new post comments. Default is false
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/community/topics/{topic_id}/subscriptions/{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": {
    "id":          35467,
    "user_id":     888887,
    "content_id":   8748733,
    ...
  }
}

Delete Topic Subscription

DELETE /api/v2/community/topics/{topic_id}/subscriptions/{id}.json

Removes a subscription to a given topic.

Allowed for
  • End-users
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/community/topics/{topic_id}/subscriptions/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
 
Status: 204 No Content

List User Subscriptions

GET /hc/api/v2/users/{user_id}/user_subscriptions?type=followings

List the user subscriptions of a particular user.

GET /hc/api/v2/users/{user_id}/user_subscriptions?type=followers

List the subscriptions that follow a particular user.

Allowed for
  • Agents
  • End users

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

Using curl
 
curl 'https://{subdomain}.zendesk.com/hc/api/v2/users/{user_id}/user_subscriptions?type=followings' \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

{
  "user_subscriptions": [
    {
      "id":          360000095593,
      "follower_id": 377841432074,
      "followed_id": 387562108194
      ...
    },
    ...
  ]
}