User Segments

A user segment defines who can view the content of a section or topic. It can specify any of the following access restrictions:

You can use this API to define or change the access restrictions of user segments. However, you must use the Sections or Topics API to apply the user segments to sections or topics in Help Center.

JSON Format

User segments have the following attributes:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when the user segment is created
name string no no User segment name (localized to the locale of the current user for built-in user segments)
user_type string no yes The set of users who can view content
group_ids array no no The ids of the groups that have access
organization_ids array no no The ids of the organizations that have access
tags array no no All the tags a user must have to have access
or_tags array no no A user must have at least one tag in the list to have access
created_at timestamp yes no When the user segment was created
updated_at timestamp yes no When the user segment was last updated
built_in boolean yes no Whether the user segment is built-in. Built-in user segments cannot be modified

The user_type attribute takes one of the following values:

Value Users
signed_in_users only authenticated users
staff only agents and Help Center managers

For group_ids, organization_ids, tags, and or_tags, an empty array means that access is not restricted by the attribute. For example, if no group ids are specified, then users don't have to be in any specific group to have access.

For tags, a user must have all the listed tags to have access. For or_tags, a user must have at least one of the listed tags to have access.

Example

{
  "user_segment": {
    "name":             "VIP agents",
    "user_type":        "staff",
    "group_ids":        [12, ...],
    "organization_ids": [42, ...],
    "tags":             ["vip"],
    "created_at":       "2017-07-20T22:55:29Z",
    "updated_at":       "2017-07-23T21:43:28Z",
    "built_in":         false
  }
}

List User Segments

GET /api/v2/help_center/user_segments.json

GET /api/v2/help_center/user_segments/applicable.json

GET /api/v2/help_center/users/{user_id}/user_segments.json

Some user segments can only be applied to sections and topics on certain Guide plans. For instance, user segments with a user_type of "staff" cannot be applied to sections and topics on accounts with the Guide Lite plan. To request only user segments applicable on the account's current Guide plan, use the /api/v2/help_center/user_segments/applicable.json endpoint.

The /api/v2/help_center/users/{user_id}/user_segments.json endpoint returns the list of user segments that a particular user belongs to. This is the only list endpoint that agents have access to. When an agent makes a request to this endpoint with another user's id, the response only includes user segments that the requesting agent also belongs to.

These endpoints support pagination, as described in the pagination documentation.

Allowed for
  • Help Center managers
  • Agents
Available Parameters

Clients can pass the following optional filters:

Name Type Comment
built_in boolean Only built_in user segments if true, only custom user segments if false
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/user_segments.json \
  -v -u {email_address}:{password}

Requesting only applicable user segments:

curl https://{subdomain}.zendesk.com/api/v2/help_center/user_segments/applicable.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "user_segments": [
    {
      "id": 7284,
      "name": "VIP agents",
      "user_type": "staff",
      "group_ids": [12, ...],
      "organization_ids": [42, ...],
      "tags": ["vip"],
      "or_tags": [],
      "created_at": "2017-05-21T20:01:12Z",
      "updated_at": "2017-06-30T01:00:25Z",
      "built_in": false
    },
    {
      "id": 9930,
      "name": "IT support",
      "user_type": "staff",
      "group_ids": [43, ...],
      "organization_ids": [42, ...],
      "tags": [],
      "or_tags": [],
      "created_at": "2017-04-09T15:33:11Z",
      "updated_at": "2017-08-10T18:41:01Z",
      "built_in": false
    },
    ...
  ]
}

Show User Segment

GET /api/v2/help_center/user_segments/{id}.json

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/user_segments/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "user_segment": {
    "id": 7284,
    "name": "VIP agents",
    "user_type": "staff",
    "group_ids": [12, ...],
    "organization_ids": [42, ...],
    "tags": ["vip"],
    "or_tags": [],
    "created_at": "2017-05-21T20:01:12Z",
    "updated_at": "2017-06-30T01:00:25Z",
    "built_in": false
  }
}

List Sections using a User Segment

GET /api/v2/help_center/user_segments/{user_segment_id}/sections.json

This endpoint supports pagination, as described in the pagination documentation.

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/user_segments/{user_segment_id}/sections.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "sections": [
    {
      "id": 3242,
      "name": "A section",
      "locale": "en",
      "url": "https://{subdomain}.zendesk.com/api/v2/help_center/en/sections/3242-A-section-.json",
      "html_url": "https://{subdomain}.zendesk.com/hc/en/sections/3242-A-section-"
    },
    {
      "id": 7352,
      "name": "Another section",
      "locale": "en",
      "url": "https://{subdomain}.zendesk.com/api/v2/help_center/en/sections/7352-Another-section-.json",
      "html_url": "https://{subdomain}.zendesk.com/hc/en/sections/7352-Another-section-"
    },
    ...
  ]
}

List Topics using a User Segment

GET /api/v2/help_center/user_segments/{user_segment_id}/topics.json

This endpoint supports pagination, as described in the pagination documentation.

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/user_segments/{user_segment_id}/topics.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "topics": [
    {
      "id": 9273,
      "name": "A topic",
      "url": "https://{subdomain}.zendesk.com/api/v2/community/topics/9273.json",
      "html_url": "https://{subdomain}.zendesk.com/hc/en/community/topics/9273-A-topic-"
    },
    {
      "id": 2292,
      "name": "Another topic",
      "url": "https://{subdomain}.zendesk.com/api/v2/community/topics/2292-Another-topic-.json",
      "html_url": "https://{subdomain}.zendesk.com/hc/en/community/topics/2292-Another-topic-"
    },
    ...
  ]
}

Create User Segment

POST /api/v2/help_center/user_segments.json

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/user_segments.json \
  -d '{ \
    "user_segment": { \
      "name": "VIP agents", \
      "user_type": "staff", \
      "group_ids": [12, ...], \
      "organization_ids": [42, ...], \
      "tags": ["vip"] \
    } \
  }' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"
Example Response
Status: 201 OK

{
  "user_segment": {
    "id": 7284
    "name": "VIP agents",
    "user_type": "staff",
    "group_ids": [12, ...],
    "organization_ids": [42, ...],
    "tags": ["vip"],
    "or_tags": [],
    "created_at": "2017-05-21T20:01:12Z",
    "updated_at": "2017-05-21T20:01:12Z",
    "built_in": false
  }
}
Example Error Response
Status: 400 Bad Request

{
  "errors": {
    "user_type": [
      "value `foo` invalid; must be either `staff` or `signed_in_users`"
    ]
  }
}

Update User Segment

PUT /api/v2/help_center/user_segments/{id}.json

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/user_segments/{id}.json \
  -d '{ \
    "user_segment": { \
      "name": "VIP agents", \
      "user_type": "staff", \
      "group_ids": [12, ...], \
      "organization_ids": [42, ...], \
      "tags": ["vip"] \
    } \
  }' \
  -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"
Example Response
Status: 200 OK

{
  "user_segment": {
    "id": 7284,
    "name": "VIP agents",
    "user_type": "staff",
    "group_ids": [12, ...],
    "organization_ids": [42, ...],
    "tags": ["vip"],
    "or_tags": [],
    "created_at": "2017-05-21T20:01:12Z",
    "updated_at": "2017-06-30T01:00:25Z",
    "built_in": false
  }
}
Example Error Response
Status: 400 Bad Request

{
  "errors": {
    "user_type": [
      "value `foo` invalid; must be either `staff` or `signed_in_users`"
    ]
  }
}

Delete User Segment

DELETE /api/v2/help_center/user_segments/{id}.json

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/help_center/user_segments/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 204 No Content