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:

signed_in_usersorstaffuser types
tags
organization ids(for signed in users)
group ids(for staff)

You can use this API to define or change the access restrictions of user segments. To apply user segments to content, use theArticlesorTopicsAPI and set theuser_segment_idproperty.

JSON format

User Segments are represented as JSON objects with the following properties:

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

Theuser_typeattribute takes one of the following values:

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

Forgroup_ids,organization_ids,tags, andor_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.

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

Example

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

List User Segments

GET /api/v2/help_center/user_segments
GET /api/v2/help_center/user_segments/applicable
GET /api/v2/help_center/users/{user_id}/user_segments

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

The/api/v2/help_center/users/{user_id}/user_segments.jsonendpoint 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 thepagination documentation.

Allowed for

Help Center managers
Agents

Pagination

Cursor pagination (recommended)
Offset pagination

SeePagination.

Parameters

Name	Type	In	Required	Description
built_in	boolean	Query	false	Only built_in user segments if true, only custom user segments if false

Code Samples

curl

              
               curlhttps://{subdomain}.亚博zendesk.com/api/v2/help_center/user_segments.json\-v -u{email_address}:{password}# Requesting only applicable user segments:curlhttps://{subdomain}.zendesk.com/api/v2/help_center/user_segments/applicable.json\-v -u{email_address}:{password}

              
               import("fmt""io""net/http")funcmain(){url:=“https://support.亚博zendesk.com/api/v2/help_center/user_segments?built_in="method:="GET"req,err:=http.NewRequest(method,url,nil)iferr!=nil{fmt.Println(err)return}req.Header.Add("Content-Type","application/json")req.Header.Add("Authorization","Basic ")// Base64 encoded "username:password"client:=&http.Client{}res,err:=client.Do(req)iferr!=nil{fmt.Println(err)return}deferres.Body.Close()body,err:=io.ReadAll(res.Body)iferr!=nil{fmt.Println(err)return}fmt.Println(string(body))}

Java

              
               importcom.squareup.okhttp.*;OkHttpClientclient=newOkHttpClient();HttpUrl.BuilderurlBuilder=HttpUrl.parse(“https://support.亚博zendesk.com/api/v2/help_center/user_segments").newBuilder().addQueryParameter("built_in","");Requestrequest=newRequest.Builder().url(urlBuilder.build()).method("GET",null).addHeader("Content-Type","application/json").addHeader("Authorization",Credentials.basic("your-email","your-password")).build();Responseresponse=client.newCall(request).execute();

Nodejs

              
               varaxios=require('axios');varconfig={method:'GET',url:'https://support.zendesk.com/api/v2/help_center/user_segments',headers:{'Content-Type':'application/json','Authorization':'Basic ',// Base64 encoded "username:password"},params:{'built_in':'',},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});

Python

              
               importrequestsurl=“https://support.亚博zendesk.com/api/v2/help_center/user_segments?built_in="headers={"Content-Type":"application/json",}response=requests.request("GET",url,auth=('',''),headers=headers)print(response.text)

Ruby

              
               require"net/http"uri=URI(“https://support.亚博zendesk.com/api/v2/help_center/user_segments")uri.query=URI.encode_www_form("built_in":"")request=Net::HTTP::Get.new(uri,"Content-Type":"application/json")request.basic_auth"username","password"response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|http.request(request)end

Example response(s)

200 OK

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

Show User Segment

GET /api/v2/help_center/user_segments/{user_segment_id}

Allowed for

Help Center managers

Parameters

Name	Type	In	Required	Description
user_segment_id	integer	Path	true	The unique ID of the user segment

Code Samples

curl

              
               curlhttps://{subdomain}.zendesk.com/api/v2/help_center/user_segments/{user_segment_id}.json\-v -u{email_address}:{password}

              
               import("fmt""io""net/http")funcmain(){url:=“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234"method:="GET"req,err:=http.NewRequest(method,url,nil)iferr!=nil{fmt.Println(err)return}req.Header.Add("Content-Type","application/json")req.Header.Add("Authorization","Basic ")// Base64 encoded "username:password"client:=&http.Client{}res,err:=client.Do(req)iferr!=nil{fmt.Println(err)return}deferres.Body.Close()body,err:=io.ReadAll(res.Body)iferr!=nil{fmt.Println(err)return}fmt.Println(string(body))}

Java

              
               importcom.squareup.okhttp.*;OkHttpClientclient=newOkHttpClient();HttpUrl.BuilderurlBuilder=HttpUrl.parse(“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234").newBuilder();Requestrequest=newRequest.Builder().url(urlBuilder.build()).method("GET",null).addHeader("Content-Type","application/json").addHeader("Authorization",Credentials.basic("your-email","your-password")).build();Responseresponse=client.newCall(request).execute();

Nodejs

              
               varaxios=require('axios');varconfig={method:'GET',url:'https://support.zendesk.com/api/v2/help_center/user_segments/1234',headers:{'Content-Type':'application/json','Authorization':'Basic ',// Base64 encoded "username:password"},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});

Python

              
               importrequestsurl=“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234"headers={"Content-Type":"application/json",}response=requests.request("GET",url,auth=('',''),headers=headers)print(response.text)

Ruby

              
               require"net/http"uri=URI(“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234")request=Net::HTTP::Get.new(uri,"Content-Type":"application/json")request.basic_auth"username","password"response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|http.request(request)end

Example response(s)

200 OK

              
               // Status 200 OK{"user_segment":{"built_in":false,"created_at":"2017-05-21T20:01:12Z","group_ids":[12],"id":7284,"name":"VIP agents","or_tags":[],"organization_ids":[],"tags":["vip"],"updated_at":"2017-05-21T20:01:12Z","user_type":"staff"}}

Create User Segment

POST /api/v2/help_center/user_segments

Allowed for

Help Center managers

Code Samples

curl

              
               curlhttps://{subdomain}.亚博zendesk.com/api/v2/help_center/user_segments.json\-d'{ \"user_segment": { \"name": "VIP agents", \"user_type": "staff", \"group_ids": [12, ...], \"tags": ["vip"] \} \}'\-v -u{email_address}:{password}-X POST -H"Content-Type: application/json"

              
               import("fmt""io""net/http")funcmain(){url:=“https://support.亚博zendesk.com/api/v2/help_center/user_segments"method:="POST"req,err:=http.NewRequest(method,url,nil)iferr!=nil{fmt.Println(err)return}req.Header.Add("Content-Type","application/json")req.Header.Add("Authorization","Basic ")// Base64 encoded "username:password"client:=&http.Client{}res,err:=client.Do(req)iferr!=nil{fmt.Println(err)return}deferres.Body.Close()body,err:=io.ReadAll(res.Body)iferr!=nil{fmt.Println(err)return}fmt.Println(string(body))}

Java

              
               importcom.squareup.okhttp.*;OkHttpClientclient=newOkHttpClient();HttpUrl.BuilderurlBuilder=HttpUrl.parse(“https://support.亚博zendesk.com/api/v2/help_center/user_segments").newBuilder();RequestBodybody=RequestBody.create(MediaType.parse("application/json"),"""""");Requestrequest=newRequest.Builder().url(urlBuilder.build()).method("POST",body).addHeader("Content-Type","application/json").addHeader("Authorization",Credentials.basic("your-email","your-password")).build();Responseresponse=client.newCall(request).execute();

Nodejs

              
               varaxios=require('axios');varconfig={method:'POST',url:'https://support.zendesk.com/api/v2/help_center/user_segments',headers:{'Content-Type':'application/json','Authorization':'Basic ',// Base64 encoded "username:password"},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});

Python

              
               importrequestsurl=“https://support.亚博zendesk.com/api/v2/help_center/user_segments"headers={"Content-Type":"application/json",}response=requests.request("POST",url,auth=('',''),headers=headers)print(response.text)

Ruby

              
               require"net/http"uri=URI(“https://support.亚博zendesk.com/api/v2/help_center/user_segments")request=Net::HTTP::Post.new(uri,"Content-Type":"application/json")request.basic_auth"username","password"response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|http.request(request)end

Example response(s)

201 Created

              
               // Status 201 Created{"user_segment":{"built_in":false,"created_at":"2017-05-21T20:01:12Z","group_ids":[12],"id":7284,"name":"VIP agents","or_tags":[],"organization_ids":[],"tags":["vip"],"updated_at":"2017-05-21T20:01:12Z","user_type":"staff"}}

400 Bad Request

              
               // 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/{user_segment_id}

Allowed for

Help Center managers

Parameters

Name	Type	In	Required	Description
user_segment_id	integer	Path	true	The unique ID of the user segment

Code Samples

curl

              
               curlhttps://{subdomain}.zendesk.com/api/v2/help_center/user_segments/{user_segment_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"

              
               import("fmt""io""net/http")funcmain(){url:=“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234"method:="PUT"req,err:=http.NewRequest(method,url,nil)iferr!=nil{fmt.Println(err)return}req.Header.Add("Content-Type","application/json")req.Header.Add("Authorization","Basic ")// Base64 encoded "username:password"client:=&http.Client{}res,err:=client.Do(req)iferr!=nil{fmt.Println(err)return}deferres.Body.Close()body,err:=io.ReadAll(res.Body)iferr!=nil{fmt.Println(err)return}fmt.Println(string(body))}

Java

              
               importcom.squareup.okhttp.*;OkHttpClientclient=newOkHttpClient();HttpUrl.BuilderurlBuilder=HttpUrl.parse(“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234").newBuilder();RequestBodybody=RequestBody.create(MediaType.parse("application/json"),"""""");Requestrequest=newRequest.Builder().url(urlBuilder.build()).method("PUT",body).addHeader("Content-Type","application/json").addHeader("Authorization",Credentials.basic("your-email","your-password")).build();Responseresponse=client.newCall(request).execute();

Nodejs

              
               varaxios=require('axios');varconfig={method:'PUT',url:'https://support.zendesk.com/api/v2/help_center/user_segments/1234',headers:{'Content-Type':'application/json','Authorization':'Basic ',// Base64 encoded "username:password"},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});

Python

              
               importrequestsurl=“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234"headers={"Content-Type":"application/json",}response=requests.request("PUT",url,auth=('',''),headers=headers)print(response.text)

Ruby

              
               require"net/http"uri=URI(“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234")request=Net::HTTP::Put.new(uri,"Content-Type":"application/json")request.basic_auth"username","password"response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|http.request(request)end

Example response(s)

200 OK

              
               // Status 200 OK{"user_segment":{"built_in":false,"created_at":"2017-05-21T20:01:12Z","group_ids":[12],"id":7284,"name":"VIP agents","or_tags":[],"organization_ids":[],"tags":["vip"],"updated_at":"2017-05-21T20:01:12Z","user_type":"staff"}}

400 Bad Request

              
               // Status 400 Bad Request{"errors":{"user_type":["value `foo` invalid; must be either `staff` or `signed_in_users`"]}}

删除User Segment

DELETE /api/v2/help_center/user_segments/{user_segment_id}

Allowed for

Help Center managers

Parameters

Name	Type	In	Required	Description
user_segment_id	integer	Path	true	The unique ID of the user segment

Code Samples

curl

              
               curlhttps://{subdomain}.zendesk.com/api/v2/help_center/user_segments/{user_segment_id}.json\-v -u{email_address}:{password}-X DELETE

              
               import("fmt""io""net/http")funcmain(){url:=“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234"method:="DELETE"req,err:=http.NewRequest(method,url,nil)iferr!=nil{fmt.Println(err)return}req.Header.Add("Content-Type","application/json")req.Header.Add("Authorization","Basic ")// Base64 encoded "username:password"client:=&http.Client{}res,err:=client.Do(req)iferr!=nil{fmt.Println(err)return}deferres.Body.Close()body,err:=io.ReadAll(res.Body)iferr!=nil{fmt.Println(err)return}fmt.Println(string(body))}

Java

              
               importcom.squareup.okhttp.*;OkHttpClientclient=newOkHttpClient();HttpUrl.BuilderurlBuilder=HttpUrl.parse(“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234").newBuilder();Requestrequest=newRequest.Builder().url(urlBuilder.build()).method("DELETE",null).addHeader("Content-Type","application/json").addHeader("Authorization",Credentials.basic("your-email","your-password")).build();Responseresponse=client.newCall(request).execute();

Nodejs

              
               varaxios=require('axios');varconfig={method:'DELETE',url:'https://support.zendesk.com/api/v2/help_center/user_segments/1234',headers:{'Content-Type':'application/json','Authorization':'Basic ',// Base64 encoded "username:password"},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});

Python

              
               importrequestsurl=“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234"headers={"Content-Type":"application/json",}response=requests.request("DELETE",url,auth=('',''),headers=headers)print(response.text)

Ruby

              
               require"net/http"uri=URI(“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234")request=Net::HTTP::删除.new(uri,"Content-Type":"application/json")request.basic_auth"username","password"response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|http.request(request)end

Example response(s)

204 No Content

              
               // Status 204 No Contentnull

List Sections with User Segment

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

Lists the sections that use the specified user segment.

This endpoint supports pagination as described inPagination.

Allowed for

Help Center managers

Parameters

Name	Type	In	Required	Description
user_segment_id	integer	Path	true	The unique ID of the user segment

Code Samples

curl

              
               curlhttps://{subdomain}.zendesk.com/api/v2/help_center/user_segments/{user_segment_id}/sections.json\-v -u{email_address}:{password}

              
               import("fmt""io""net/http")funcmain(){url:=“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234/sections"method:="GET"req,err:=http.NewRequest(method,url,nil)iferr!=nil{fmt.Println(err)return}req.Header.Add("Content-Type","application/json")req.Header.Add("Authorization","Basic ")// Base64 encoded "username:password"client:=&http.Client{}res,err:=client.Do(req)iferr!=nil{fmt.Println(err)return}deferres.Body.Close()body,err:=io.ReadAll(res.Body)iferr!=nil{fmt.Println(err)return}fmt.Println(string(body))}

Java

              
               importcom.squareup.okhttp.*;OkHttpClientclient=newOkHttpClient();HttpUrl.BuilderurlBuilder=HttpUrl.parse(“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234/sections").newBuilder();Requestrequest=newRequest.Builder().url(urlBuilder.build()).method("GET",null).addHeader("Content-Type","application/json").addHeader("Authorization",Credentials.basic("your-email","your-password")).build();Responseresponse=client.newCall(request).execute();

Nodejs

              
               varaxios=require('axios');varconfig={method:'GET',url:'https://support.zendesk.com/api/v2/help_center/user_segments/1234/sections',headers:{'Content-Type':'application/json','Authorization':'Basic ',// Base64 encoded "username:password"},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});

Python

              
               importrequestsurl=“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234/sections"headers={"Content-Type":"application/json",}response=requests.request("GET",url,auth=('',''),headers=headers)print(response.text)

Ruby

              
               require"net/http"uri=URI(“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234/sections")request=Net::HTTP::Get.new(uri,"Content-Type":"application/json")request.basic_auth"username","password"response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|http.request(request)end

Example response(s)

200 OK

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

List Topics with User Segment

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

Lists the topics that use the specified user segment.

This endpoint supports pagination as described inPagination.

Allowed for

Help Center managers

Pagination

Cursor pagination (recommended)
Offset pagination

SeePagination.

Parameters

Name	Type	In	Required	Description
user_segment_id	integer	Path	true	The unique ID of the user segment

Code Samples

curl

              
               curlhttps://{subdomain}.zendesk.com/api/v2/help_center/user_segments/{user_segment_id}/topics.json\-v -u{email_address}:{password}

              
               import("fmt""io""net/http")funcmain(){url:=“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234/topics"method:="GET"req,err:=http.NewRequest(method,url,nil)iferr!=nil{fmt.Println(err)return}req.Header.Add("Content-Type","application/json")req.Header.Add("Authorization","Basic ")// Base64 encoded "username:password"client:=&http.Client{}res,err:=client.Do(req)iferr!=nil{fmt.Println(err)return}deferres.Body.Close()body,err:=io.ReadAll(res.Body)iferr!=nil{fmt.Println(err)return}fmt.Println(string(body))}

Java

              
               importcom.squareup.okhttp.*;OkHttpClientclient=newOkHttpClient();HttpUrl.BuilderurlBuilder=HttpUrl.parse(“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234/topics").newBuilder();Requestrequest=newRequest.Builder().url(urlBuilder.build()).method("GET",null).addHeader("Content-Type","application/json").addHeader("Authorization",Credentials.basic("your-email","your-password")).build();Responseresponse=client.newCall(request).execute();

Nodejs

              
               varaxios=require('axios');varconfig={method:'GET',url:'https://support.zendesk.com/api/v2/help_center/user_segments/1234/topics',headers:{'Content-Type':'application/json','Authorization':'Basic ',// Base64 encoded "username:password"},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});

Python

              
               importrequestsurl=“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234/topics"headers={"Content-Type":"application/json",}response=requests.request("GET",url,auth=('',''),headers=headers)print(response.text)

Ruby

              
               require"net/http"uri=URI(“https://support.亚博zendesk.com/api/v2/help_center/user_segments/1234/topics")request=Net::HTTP::Get.new(uri,"Content-Type":"application/json")request.basic_auth"username","password"response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|http.request(request)end

Example response(s)

200 OK

              
               // Status 200 OK{"topics":[{"html_url":"https://{subdomain}.zendesk.com/hc/en/community/topics/9273-A-topic-","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/2292-Another-topic-","id":2292,"name":"Another topic","url":"https://{subdomain}.zendesk.com/api/v2/community/topics/2292-Another-topic-.json"}]}

Help Center API

Federated Search

Help Center Templates

User Segments

JSON format

Example

List User Segments

Allowed for

Parameters

Code Samples

Example response(s)

Show User Segment

Allowed for

Parameters

Code Samples

Example response(s)

Create User Segment

Allowed for

Code Samples

Example response(s)

Update User Segment

Allowed for

Parameters

Code Samples

Example response(s)

删除User Segment

Allowed for

Parameters

Code Samples

Example response(s)

List Sections with User Segment

Allowed for

Parameters

Code Samples

Example response(s)

List Topics with User Segment

Allowed for

Parameters

Code Samples

Example response(s)