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/groups/{group_id}/memberships
Pagination
  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/group_memberships.json \
  -v -u {email_address}:{password}
Example Response
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
    }
  ]
}

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
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
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

{
  "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
  }
}

List Assignable Memberships

  • GET /api/v2/group_memberships/assignable
  • GET /api/v2/groups/{group_id}/memberships/assignable

Returns a maximum of 100 group memberships per page.

Pagination
  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

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": [
    {
      "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
    }
  ]
}

Bulk Create Memberships

  • POST /api/v2/group_memberships/create_many

Assigns up to 100 agents to given groups.

Allowed For
  • Admins
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.

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
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"
  }
}

Bulk Delete Memberships

  • POST /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
Parameters
Name Type In Required Description
ids string Query false Id of the group memberships to delete. Comma separated
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
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"
  }
}

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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/group_memberships/{group_membership_id}.json \
  -v -u {email_address}:{password}
Example Response
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
  }
}

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

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
Using curl
curl https://{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"
Example Response
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
    }
  ]
}