Documentation API Reference

Group Memberships

A membership links an agent to a group. Groups can have many agents, as agents can be in many groups. You can use the API to list what agents are in which groups, and reassign group members.

JSON format

Group Memberships are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
created_at string true false The time the group was created
default boolean false false If true, tickets assigned directly to the agent will assume this membership's group
group_id integer false true The id of a group
id integer true false Automatically assigned upon creation
updated_at string true false The time of the last update of the group
url string true false The API url of this record
user_id integer false true The id of an agent

List Memberships

  • GET /api/v2/group_memberships
  • GET /api/v2/users/{user_id}/group_memberships
  • GET / api / v2 /团体/ {group_id}/memberships

Pagination

  • Cursor pagination (recommended)
  • Offset pagination

SeePagination.

Returns a maximum of 100 records per page.

Allowed For:

  • Agents

Parameters

Name Type In Required Description
group_id integer Path true The ID of the group
user_id integer Path true The id of the user

Code Samples

curl 
              

               
curlhttps://{subdomain}.zendesk.com/api/v2/group_memberships.json\-v -u{email_address}:{password}
Go 
              

               
import("fmt""io""net/http")funcmain(){url:="https://example.zendesk.com/api/v2/group_memberships"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://example.zendesk.com/api/v2/group_memberships").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://example.zendesk.com/api/v2/group_memberships',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://example.zendesk.com/api/v2/group_memberships"headers={"Content-Type":"application/json",}response=requests.request("GET",url,auth=('',''),headers=headers)print(response.text)
Ruby 
              

               
require"net/http"uri=URI("https://example.zendesk.com/api/v2/group_memberships")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{"group_memberships":[{"created_at":"2009-05-13T00:07:08Z","default":true,"group_id":12,"id":4,"updated_at":"2011-07-22T00:11:12Z","user_id":29},{"created_at":"2012-03-13T22:01:32Z","default":false,"group_id":3,"id":49,"updated_at":"2012-03-13T22:01:32Z","user_id":155}]}

List Assignable Memberships

  • GET /api/v2/group_memberships/assignable
  • GET / api / v2 /团体/ {group_id}/memberships/assignable

Returns a maximum of 100 group memberships per page.

Pagination

  • Cursor pagination (recommended)
  • Offset pagination

SeePagination.

Returns a maximum of 100 records per page.

Allowed For:

  • Agents

Code Samples

curl 
              

               
curlhttps://{subdomain}.zendesk.com/api/v2/group_memberships/assignable.json\-v -u{email_address}:{password}
Go 
              

               
import("fmt""io""net/http")funcmain(){url:="https://example.zendesk.com/api/v2/group_memberships/assignable"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://example.zendesk.com/api/v2/group_memberships/assignable").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://example.zendesk.com/api/v2/group_memberships/assignable',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://example.zendesk.com/api/v2/group_memberships/assignable"headers={"Content-Type":"application/json",}response=requests.request("GET",url,auth=('',''),headers=headers)print(response.text)
Ruby 
              

               
require"net/http"uri=URI("https://example.zendesk.com/api/v2/group_memberships/assignable")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{"group_memberships":[{"created_at":"2009-05-13T00:07:08Z","default":true,"group_id":12,"id":4,"updated_at":"2011-07-22T00:11:12Z","user_id":29},{"created_at":"2012-03-13T22:01:32Z","default":false,"group_id":3,"id":49,"updated_at":"2012-03-13T22:01:32Z","user_id":155}]}

Show Membership

  • GET /api/v2/group_memberships/{group_membership_id}
  • GET /api/v2/users/{user_id}/group_memberships/{group_membership_id}

The 'id' is the group membership id, not a group id.

Allowed For

  • Agents

Parameters

Name Type In Required Description
group_membership_id integer Path true The ID of the group membership
user_id integer Path true The id of the user

Code Samples

curl 
              

               
curlhttps://{subdomain}.zendesk.com/api/v2/group_memberships/{group_membership_id}.json\-v -u{email_address}:{password}
Go 
              

               
import("fmt""io""net/http")funcmain(){url:="https://example.zendesk.com/api/v2/group_memberships/4"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://example.zendesk.com/api/v2/group_memberships/4").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://example.zendesk.com/api/v2/group_memberships/4',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://example.zendesk.com/api/v2/group_memberships/4"headers={"Content-Type":"application/json",}response=requests.request("GET",url,auth=('',''),headers=headers)print(response.text)
Ruby 
              

               
require"net/http"uri=URI("https://example.zendesk.com/api/v2/group_memberships/4")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{"group_membership":{"created_at":"2012-04-03T12:34:01Z","default":true,"group_id":88,"id":461,"updated_at":"2012-04-03T12:34:01Z","user_id":72}}

Create Membership

  • POST /api/v2/group_memberships
  • POST /api/v2/users/{user_id}/group_memberships

Assigns an agent to a given group.

Allowed For

  • Admins
  • Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

Parameters

Name Type In Required Description
group_id integer Path true The ID of the group
user_id integer Path true The id of the user

Code Samples

curl 
              

               
curlhttps://{subdomain}.zendesk.com/api/v2/group_memberships.json\-X POST -d'{"group_membership": {"user_id": 72, "group_id": 88}}'\-H"Content-Type: application/json"-v -u{email_address}:{password}
Go 
              

               
import("fmt""io""net/http")funcmain(){url:="https://example.zendesk.com/api/v2/group_memberships"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://example.zendesk.com/api/v2/group_memberships").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://example.zendesk.com/api/v2/group_memberships',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://example.zendesk.com/api/v2/group_memberships"headers={"Content-Type":"application/json",}response=requests.request("POST",url,auth=('',''),headers=headers)print(response.text)
Ruby 
              

               
require"net/http"uri=URI("https://example.zendesk.com/api/v2/group_memberships")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{"group_membership":{"created_at":"2012-04-03T12:34:01Z","default":true,"group_id":88,"id":461,"updated_at":"2012-04-03T12:34:01Z","user_id":72}}

Bulk Create Memberships

  • POST / api / v2 / group_memberships / create_many

Assigns up to 100 agents to given groups.

Allowed For

  • Admins
  • Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

Response

This endpoint returns ajob_statusJSON objectand queues a background job to do the work. Use theShow Job Statusendpoint to check for the job's completion.

Code Samples

curl 
              

               
curlhttps://{subdomain}.zendesk.com/api/v2/group_memberships/create_many.json\-X POST -d'{"group_memberships": [{"user_id": 72, "group_id": 88}, {"user_id": 73, "group_id": 88}]}'\-H"Content-Type: application/json"-v -u{email_address}:{password}
Go 
              

               
import("fmt""io""net/http")funcmain(){url:="https://example.zendesk.com/api/v2/group_memberships/create_many"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://example.zendesk.com/api/v2/group_memberships/create_many").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://example.zendesk.com/api/v2/group_memberships/create_many',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://example.zendesk.com/api/v2/group_memberships/create_many"headers={"Content-Type":"application/json",}response=requests.request("POST",url,auth=('',''),headers=headers)print(response.text)
Ruby 
              

               
require"net/http"uri=URI("https://example.zendesk.com/api/v2/group_memberships/create_many")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)

200 OK 
              

               
// Status 200 OK{"job_status":{"id":"82de0b044094f0c67893ac9fe64f1a99","message":"Completed at 2018-03-08 10:07:04 +0000","progress":2,"results":[{"action":"update","id":244,"status":"Updated","success":true},{"action":"update","id":245,"status":"Updated","success":true}],"status":"completed","total":2,"url":"https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"}}

Set Membership as Default

  • PUT /api/v2/users/{user_id}/group_memberships/{group_membership_id}/make_default

Allowed For:

  • Agents

Parameters

Name Type In Required Description
group_membership_id integer Path true The ID of the group membership
user_id integer Path true The id of the user

Code Samples

curl 
              

               
curlhttps://{subdomain}.zendesk.com/api/v2/users/{user_id}/group_memberships/{group_membership_id}/make_default.json\-v -u{email_address}:{password}-X PUT -d'{}'-H"Content-Type: application/json"
Go 
              

               
import("fmt""io""net/http")funcmain(){url:="https://example.zendesk.com/api/v2/users/35436/group_memberships/4/make_default"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://example.zendesk.com/api/v2/users/35436/group_memberships/4/make_default").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://example.zendesk.com/api/v2/users/35436/group_memberships/4/make_default',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://example.zendesk.com/api/v2/users/35436/group_memberships/4/make_default"headers={"Content-Type":"application/json",}response=requests.request("PUT",url,auth=('',''),headers=headers)print(response.text)
Ruby 
              

               
require"net/http"uri=URI("https://example.zendesk.com/api/v2/users/35436/group_memberships/4/make_default")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{"group_memberships":[{"created_at":"2009-05-13T00:07:08Z","default":true,"group_id":12,"id":4,"updated_at":"2011-07-22T00:11:12Z","user_id":29},{"created_at":"2012-03-13T22:01:32Z","default":false,"group_id":3,"id":49,"updated_at":"2012-03-13T22:01:32Z","user_id":155}]}

删除Membership

  • DELETE /api/v2/group_memberships/{group_membership_id}
  • DELETE /api/v2/users/{user_id}/group_memberships/{group_membership_id}

Immediately removes a user from a group and schedules a job to unassign all working tickets that are assigned to the given user and group combination.

Allowed For

  • Admins
  • Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

Parameters

Name Type In Required Description
group_membership_id integer Path true The ID of the group membership
user_id integer Path true The id of the user

Code Samples

curl 
              

               
curlhttps://{subdomain}.zendesk.com/api/v2/group_memberships/{group_membership_id}.json\-v -u{email_address}:{password}-X DELETE
Go 
              

               
import("fmt""io""net/http")funcmain(){url:="https://example.zendesk.com/api/v2/group_memberships/4"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://example.zendesk.com/api/v2/group_memberships/4").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://example.zendesk.com/api/v2/group_memberships/4',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://example.zendesk.com/api/v2/group_memberships/4"headers={"Content-Type":"application/json",}response=requests.request("DELETE",url,auth=('',''),headers=headers)print(response.text)
Ruby 
              

               
require"net/http"uri=URI("https://example.zendesk.com/api/v2/group_memberships/4")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

Bulk Delete Memberships

  • DELETE /api/v2/group_memberships/destroy_many

Immediately removes users from groups and schedules a job to unassign all working tickets that are assigned to the given user and group combinations.

Allowed For

  • Admins
  • Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

Parameters

Name Type In Required Description
ids string 查询 false Id of the group memberships to delete. Comma separated

Code Samples

curl 
              

               
curlhttps://{subdomain}.zendesk.com/api/v2/group_memberships/destroy_many.json?ids=1,2,3\-v -u{email_address}:{password}-X DELETE
Go 
              

               
import("fmt""io""net/http")funcmain(){url:="https://example.zendesk.com/api/v2/group_memberships/destroy_many?ids=1%2C2%2C3"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://example.zendesk.com/api/v2/group_memberships/destroy_many").newBuilder().addQueryParameter("ids","1,2,3");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://example.zendesk.com/api/v2/group_memberships/destroy_many',headers:{'Content-Type':'application/json','Authorization':'Basic ',// Base64 encoded "username:password"},params:{'ids':'1%2C2%2C3',},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});
Python 
              

               
importrequestsurl="https://example.zendesk.com/api/v2/group_memberships/destroy_many?ids=1%2C2%2C3"headers={"Content-Type":"application/json",}response=requests.request("DELETE",url,auth=('',''),headers=headers)print(response.text)
Ruby 
              

               
require"net/http"uri=URI("https://example.zendesk.com/api/v2/group_memberships/destroy_many")uri.query=URI.encode_www_form("ids":"1,2,3")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)

200 OK 
              

               
// Status 200 OK{"job_status":{"id":"82de0b044094f0c67893ac9fe64f1a99","message":"Completed at 2018-03-08 10:07:04 +0000","progress":2,"results":[{"action":"delete","id":244,"status":"Deleted","success":true},{"action":"delete","id":245,"status":"Deleted","success":true}],"status":"completed","total":2,"url":"https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"}}