Fields

Group objects have the following fields and links:

Fields

field name description
id id for this resource
name name of group

Links

rel class embeddable? description
self group no this group
users user no users in this group
filters filter no filters for this group

List

Retrieve a paginated list of all groups.

GET https://yoursite.desk.com/api/v2/groups

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

ETags

The Groups List endpoint has support for ETags. See ETag Caching for details.

Limits

The maximum per_page parameter value for this endpoint is currently 1000.

Sorting

Sorting is supported by using sort_field and sort_direction parameters in your request.

  • sort_field - field on which you would like to sort
  • sort_direction - direction to sort - asc for ascending, desc for descending

The following fields can be used for sorting groups: id or name

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/groups \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/groups?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/groups?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/groups?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "id": 101,
        "name": "Support Ninjas",
        "_links": {
          "self": {
            "href": "/api/v2/groups/1",
            "class": "group"
          }
        }
      },
      {
        "id": 101,
        "name": "Administrators",
        "_links": {
          "self": {
            "href": "/api/v2/groups/2",
            "class": "group"
          }
        },
        "position": 2
      }
    ]
  }
}

Show

Retrieve a single group.

GET https://yoursite.desk.com/api/v2/groups/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/groups/:id \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "id": 101,
  "name": "Support Ninjas",
  "_links": {
    "self": {
      "href": "/api/v2/groups/1",
      "class": "group"
    }
  }
}

List Filters

Retrieve a paginated list of all filters for the given group.

GET https://yoursite.desk.com/api/v2/groups/:id/filters

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

Please see Filters for details on the specific fields for each filter.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/groups/:id/filters \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/groups/1/filters?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/groups/1/filters?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/groups/1/filters?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "My Active Cases",
        "sort_field": "priority",
        "sort_direction": "desc",
        "position": 1,
        "active": true,
        "_links": {
          "self": {
            "href": "/api/v2/filters/1",
            "class": "filter"
          },
          "group": null,
          "user": null,
          "cases": {
            "href": "/api/v2/filters/1/cases",
            "class": "case"
          }
        }
      },
      {
        "name": "New Cases",
        "sort_field": "priority",
        "sort_direction": "desc",
        "position": 1,
        "active": true,
        "_links": {
          "self": {
            "href": "/api/v2/filters/2",
            "class": "filter"
          },
          "group": null,
          "user": null,
          "cases": {
            "href": "/api/v2/filters/1/cases",
            "class": "case"
          }
        }
      }
    ]
  }
}

List Users

Retrieve a paginated list of all users for the given group.

GET https://yoursite.desk.com/api/v2/groups/:id/users

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

Please see Users for details on the specific fields for each user.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/groups/:id/users \
    -u email:password \
    -H 'Accept: application/json'

Example Response

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/groups/1/users?page=1&per_page=50&sort_direction=asc&sort_field=name",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/groups/1/users?page=1&per_page=50&sort_direction=asc&sort_field=name",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/groups/1/users?page=1&per_page=50&sort_direction=asc&sort_field=name",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "id": 1,
        "name": "John Doe",
        "public_name": "John Doe",
        "email": "john@acme.com",
        "level": "agent",
        "created_at": "2015-09-22T16:16:17Z",
        "updated_at": "2016-09-15T16:16:17Z",
        "current_login_at": "2016-09-21T16:16:17Z",
        "last_login_at": "2016-09-15T16:16:17Z",
        "_links": {
          "self": {
            "href": "/api/v2/users/1",
            "class": "user"
          },
          "preferences": {
            "href": "/api/v2/users/1/preferences",
            "class": "user_preference"
          },
          "macros": {
            "href": "/api/v2/users/1/macros",
            "class": "macro"
          },
          "filters": {
            "href": "/api/v2/users/1/filters",
            "class": "filter"
          },
          "integration_urls": {
            "href": "/api/v2/users/1/integration_urls",
            "class": "integration_url"
          },
          "groups": {
            "href": "/api/v2/users/1/groups",
            "class": "group"
          },
          "searches": {
            "href": "/api/v2/users/1/searches",
            "class": "search"
          }
        }
      },
      {
        "id": 1,
        "name": "Jane Smith",
        "public_name": "Jane Smith",
        "email": "jane@acme.com",
        "level": "agent",
        "created_at": "2015-09-22T16:16:17Z",
        "updated_at": "2016-09-15T16:16:17Z",
        "current_login_at": "2016-09-21T16:16:17Z",
        "last_login_at": "2016-09-15T16:16:17Z",
        "_links": {
          "self": {
            "href": "/api/v2/users/2",
            "class": "user"
          },
          "preferences": {
            "href": "/api/v2/users/1/preferences",
            "class": "user_preference"
          },
          "macros": {
            "href": "/api/v2/users/1/macros",
            "class": "macro"
          },
          "filters": {
            "href": "/api/v2/users/1/filters",
            "class": "filter"
          },
          "integration_urls": {
            "href": "/api/v2/users/1/integration_urls",
            "class": "integration_url"
          },
          "groups": {
            "href": "/api/v2/users/1/groups",
            "class": "group"
          },
          "searches": {
            "href": "/api/v2/users/1/searches",
            "class": "search"
          }
        }
      }
    ]
  }
}

Permission Fields

Group Permission objects have the following fields and links:

Fields

field description
name the name of the category the permission applies to (cases, content)

Links

rel class embeddable? description
delete site no implies the permission is scoped to site
delete group no the group to which this permission is scoped
export site no implies the permission is scoped to site
export group no the group to which this permission is scoped

List Permissions

List all of the group's permissions.

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/groups/:group_id/permissions \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/groups/1/permissions?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/groups/1/permissions?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/groups/1/permissions?page=1&per_page=50",
      "class": "page"
    },
    "previous": null,
    "next": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "cases",
        "_links": {
          "delete": {
            "href": "/api/v2/groups/1",
            "class": "group"
          },
          "export": {
            "href": null,
            "class": "site"
          }
        }
      },
      {
        "name": "content",
        "_links": {
          "delete": {
            "href": "/api/v2/groups/1",
            "class": "group"
          }
        }
      }
    ]
  }
}