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

Memberships are simple links between a user and a group

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned upon creation
url string yes no The API url of this record
user_id integer no yes The id of an agent
group_id integer no yes The id of a group
default boolean no no If true, tickets assigned directly to the agent will assume this membership's group.
created_at date yes no The time the membership was created
updated_at date yes no The time of the last update of the membership
Example
{
  "id":         4,
  "user_id":    29,
  "group_id":   12,
  "default":    true,
  "created_at": "2009-05-13T00:07:08Z",
  "updated_at": "2011-07-22T00:11:12Z"
}

List Memberships

GET /api/v2/group_memberships.json

GET /api/v2/users/{user_id}/group_memberships.json

GET /api/v2/groups/{group_id}/memberships.json

Allowed For:
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/group_memberships.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "group_memberships": [
    {
      "id":         4,
      "user_id":    29,
      "group_id":   12,
      "default":    true,
      "created_at": "2009-05-13T00:07:08Z",
      "updated_at": "2011-07-22T00:11:12Z"
    },
    {
      "id":         49,
      "user_id":    155,
      "group_id":   3,
      "default":    false,
      "created_at": "2012-03-13T22:01:32Z",
      "updated_at": "2012-03-13T22:01:32Z"
    }
  ]
}

List Assignable Memberships

GET /api/v2/group_memberships/assignable.json

GET /api/v2/groups/{group_id}/memberships/assignable.json

Allowed For:
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/group_memberships/assignable.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "group_memberships": [
    {
      "id":         4,
      "user_id":    29,
      "group_id":   12,
      "default":    true,
      "created_at": "2009-05-13T00:07:08Z",
      "updated_at": "2011-07-22T00:11:12Z"
    },
    {
      "id":         49,
      "user_id":    155,
      "group_id":   3,
      "default":    false,
      "created_at": "2012-03-13T22:01:32Z",
      "updated_at": "2012-03-13T22:01:32Z"
    }
  ]
}

Show Membership

GET /api/v2/group_memberships/{id}.json

GET /api/v2/users/{user_id}/group_memberships/{id}.json

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

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/group_memberships/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "group_membership": {
     "id":         4,
     "user_id":    29,
     "group_id":   12,
     "default":    true,
     "created_at": "2009-05-13T00:07:08Z",
     "updated_at": "2011-07-22T00:11:12Z"
  }
}

Create Membership

POST /api/v2/group_memberships.json

POST /api/v2/users/{user_id}/group_memberships.json

Assigns an agent to a given group.

Allowed For
  • Admins
Using curl
curl https://{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}
Example Response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/group_memberships/{id}.json

{
  "group_membership": {
     "id":         461,
     "user_id":    72,
     "group_id":   88,
     "default":    true,
     "created_at": "2012-04-03T12:34:01Z",
     "updated_at": "2012-04-03T12:34:01Z"
  }
}

Bulk Create Memberships

POST /api/v2/group_memberships/create_many.json

Assigns agents to given groups.

Allowed For
  • Admins
Using curl
curl https://{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}
Example Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion.

Delete Membership

DELETE /api/v2/group_memberships/{id}.json

DELETE /api/v2/users/{user_id}/group_memberships/{id}.json

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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/group_memberships/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 204 No Content

Bulk Delete Memberships

DELETE /api/v2/group_memberships/destroy_many.json?ids={group_membership_ids}

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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/group_memberships/destroy_many.json?ids=1,2,3 \
  -v -u {email_address}:{password} -X DELETE
Example Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion.

Set Membership as Default

PUT /api/v2/users/{user_id}/group_memberships/{membership_id}/make_default.json

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/group_memberships/{membership_id}/make_default.json \
  -v -u {email_address}:{password} -X PUT -d '{}' -H "Content-Type: application/json"
Example Response

Same as List Memberships.