Groups

When support requests arrive in Zendesk Support, they can be assigned to a Group. Groups serve as the core element of ticket workflow; support agents are organized into Groups and tickets can be assigned to a Group only, or to an assigned agent within a Group. A ticket can never be assigned to an agent without also being assigned to a Group.

JSON Format

Groups 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 true false If group is default for the account
deleted boolean true false Deleted groups get marked as such
description string false false The description of the group
id integer true false Automatically assigned when creating groups
name string false true The name of the group
updated_at string true false The time of the last update of the group
url string true false The API url of this group
Example
{
  "created_at": "2009-07-20T22:55:29Z",
  "default": true,
  "deleted": false,
  "description": "Some clever description here",
  "id": 3432,
  "name": "First Level Support",
  "updated_at": "2011-05-05T10:38:52Z",
  "url": "https://company.zendesk.com/api/v2/groups/3432.json"
}

List Groups

  • GET /api/v2/groups
  • GET /api/v2/users/{user_id}/groups
Pagination
  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For
  • Admins
  • Agents
Parameters
Name Type In Required Description
user_id integer Path true The ID of the user
Using curl
curl https://{subdomain}.zendesk.com/api/v2/groups.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "groups": [
    {
      "created_at": "2009-05-13T00:07:08Z",
      "id": 211,
      "name": "DJs",
      "updated_at": "2011-07-22T00:11:12Z"
    },
    {
      "created_at": "2009-08-26T00:07:08Z",
      "id": 122,
      "name": "MCs",
      "updated_at": "2010-05-13T00:07:08Z"
    }
  ]
}

Create Group

  • POST /api/v2/groups
Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/groups.json \
  -H "Content-Type: application/json" -d '{"group": {"name": "My Group"}}'
  -v -u {email_address}:{password} -X POST
Example Response
Status 201 Created

{
  "group": {
    "created_at": "2009-08-26T00:07:08Z",
    "id": 122,
    "name": "My Group",
    "updated_at": "2010-05-13T00:07:08Z"
  }
}

List Assignable Groups

  • GET /api/v2/groups/assignable
Pagination
  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

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

{
  "groups": [
    {
      "created_at": "2009-05-13T00:07:08Z",
      "id": 211,
      "name": "DJs",
      "updated_at": "2011-07-22T00:11:12Z"
    },
    {
      "created_at": "2009-08-26T00:07:08Z",
      "id": 122,
      "name": "MCs",
      "updated_at": "2010-05-13T00:07:08Z"
    }
  ]
}

Count Groups

  • GET /api/v2/groups/count
  • GET /api/v2/users/{user_id}/groups/count

Returns an approximate count of groups. If the count exceeds 100,000, it is updated every 24 hours.

The refreshed_at property of the count object is a timestamp that indicates when the count was last updated.

Note: When the count exceeds 100,000, refreshed_at may occasionally be null. This indicates that the count is being updated in the background, and the value property of the count object is limited to 100,000 until the update is complete.

Allowed For
  • Admins
  • Agents
Parameters
Name Type In Required Description
user_id integer Path true The ID of the user
Using curl
curl https://{subdomain}.zendesk.com/api/v2/groups/count.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "count": {
    "refreshed_at": "2020-04-06T02:18:17Z",
    "value": 102
  },
  "links": {
    "url": "https://{subdomain}.zendesk.com/api/v2/groups/count"
  }
}

Show Group

  • GET /api/v2/groups/{group_id}
Allowed For
  • Admins
  • Agents
Parameters
Name Type In Required Description
group_id integer Path true The ID of the group
Using curl
curl https://{subdomain}.zendesk.com/api/v2/groups/{group_id}.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "group": {
    "created_at": "2009-08-26T00:07:08Z",
    "id": 122,
    "name": "MCs",
    "updated_at": "2010-05-13T00:07:08Z"
  }
}

Update Group

  • PUT /api/v2/groups/{group_id}
Allowed For
  • Admins
Parameters
Name Type In Required Description
group_id integer Path true The ID of the group
Using curl
curl https://{subdomain}.zendesk.com/api/v2/groups/{group_id}.json \
  -H "Content-Type: application/json" -d '{"group": {"name": "Interesting Group"}}' \
  -v -u {email_address}:{password} -X PUT
Example Response
Status 200 OK

{
  "group": {
    "created_at": "2009-08-26T00:07:08Z",
    "id": 123,
    "name": "Interesting Group",
    "updated_at": "2010-05-13T00:07:08Z"
  }
}

Delete Group

  • DELETE /api/v2/groups/{group_id}
Allowed For
  • Admins
Parameters
Name Type In Required Description
group_id integer Path true The ID of the group
Using curl
curl https://{subdomain}.zendesk.com/api/v2/groups/{group_id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status 204 No Content