Fields

User objects have the following fields and links:

Fields

field name description
id id for this resource
name name of the user
public_name public facing name of the user
email user's email
email_verified indicates if an email address has been verified
avatar user's avatar URL - image sourced from Gravatar.
level user's permission level
created_at when this record was created
updated_at when this record was last updated
current_login_at when this user most recently logged in
last_login_at when this user last logged in
available true when user is online with routing enabeld, false otherwise

Links

rel class embeddable? description
self user no this User
preferences user_preference no this User's preferences
macros macro no the Macros this User has permission to apply to a Case
searches searches no this User's searches
groups groups no this User's groups
filters filter no this User's filters
integration_urls integration_url no this User's integration urls

List

Retrieve a paginated list of all users.

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

Applicable Roles

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

ETags

The Users 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 users: id or name

The requesting user will either be first in the list (for ascending order) or last (for descending order).

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/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
107
108
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/users?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/users?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/users?page=1&per_page=50",
      "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": "2016-10-18T18:18:06Z",
        "updated_at": "2017-10-11T18:18:06Z",
        "current_login_at": "2017-10-17T18:18:06Z",
        "last_login_at": "2017-10-11T18:18:06Z",
        "avatar": "http://www.gravatar.com/avatar/3904fac733nf92bfbf54d71c9bbc18cd?default=404&rating=PG&size=50",
        "_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": 2,
        "name": "Jane Doe",
        "public_name": "Jane Doe",
        "email": "jane@acme.com",
        "level": "agent",
        "created_at": "2016-10-18T18:18:06Z",
        "updated_at": "2017-10-11T18:18:06Z",
        "current_login_at": "2017-10-17T18:18:06Z",
        "last_login_at": "2017-10-11T18:18:06Z",
        "avatar": "http://www.gravatar.com/avatar/3904fac733nf92bfbf54d71c9bbc18cd?default=404&rating=PG&size=50",
        "_links": {
          "self": {
            "href": "/api/v2/users/2",
            "class": "user"
          },
          "preferences": {
            "href": "/api/v2/users/2/preferences",
            "class": "user_preference"
          },
          "macros": {
            "href": "/api/v2/users/2/macros",
            "class": "macro"
          },
          "filters": {
            "href": "/api/v2/users/2/filters",
            "class": "filter"
          },
          "integration_urls": {
            "href": "/api/v2/users/2/integration_urls",
            "class": "integration_url"
          },
          "groups": {
            "href": "/api/v2/users/2/groups",
            "class": "group"
          },
          "searches": {
            "href": "/api/v2/users/2/searches",
            "class": "search"
          }
        }
      }
    ]
  }
}

Show

Retrieve a single user.

GET https://yoursite.desk.com/api/v2/users/: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/users/:id \
    -u email:password \
    -H 'Accept: application/json'

Instead of passing id you can pass the word me or current. This will return the user currently associated with the API authentication.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/users/me \
    -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
{
  "id": 1,
  "name": "John Doe",
  "public_name": "John Doe",
  "email": "john@acme.com",
  "level": "agent",
  "created_at": "2016-10-18T18:18:06Z",
  "updated_at": "2017-10-11T18:18:06Z",
  "current_login_at": "2017-10-17T18:18:06Z",
  "last_login_at": "2017-10-11T18:18:06Z",
  "avatar": "http://www.gravatar.com/avatar/3904fac733nf92bfbf54d71c9bbc18cd?default=404&rating=PG&size=50",
  "_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"
    }
  }
}

Update

Update a user.

PATCH https://yoursite.desk.com/api/v2/users/:id

Applicable Roles

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

Only the currently logged-in user may be updated.

Fields

field name description
current_password The user's current password. Required when changing the password field.
password New password. Must meet the requirements set in the Desk.com Admin.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/users/1 \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"current_password":"curr3nt_p4ssWORD", "password":"n3w_p4ssw0RD!"}'

Example Request Body

1
2
3
4
{
  "current_password": "curr3nt_p4ssWORD",
  "password": "n3w_p4ssw0RD!"
}

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
{
  "id": 1,
  "name": "John Doe",
  "public_name": "John Doe",
  "email": "john@acme.com",
  "level": "agent",
  "created_at": "2016-10-18T18:18:06Z",
  "updated_at": "2017-10-11T18:18:06Z",
  "current_login_at": "2017-10-17T18:18:06Z",
  "last_login_at": "2017-10-11T18:18:06Z",
  "avatar": "http://www.gravatar.com/avatar/3904fac733nf92bfbf54d71c9bbc18cd?default=404&rating=PG&size=50",
  "_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"
    }
  }
}

Current

Retrieve the current user.

GET https://yoursite.desk.com/api/v2/users/current

GET https://yoursite.desk.com/api/v2/users/me

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/users/current \
    -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
{
  "id": 1,
  "name": "John Doe",
  "public_name": "John Doe",
  "email": "john@acme.com",
  "level": "agent",
  "created_at": "2016-10-18T18:18:06Z",
  "updated_at": "2017-10-11T18:18:06Z",
  "current_login_at": "2017-10-17T18:18:06Z",
  "last_login_at": "2017-10-11T18:18:06Z",
  "avatar": "http://www.gravatar.com/avatar/3904fac733nf92bfbf54d71c9bbc18cd?default=404&rating=PG&size=50",
  "_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"
    }
  }
}

Phone Integration

Retrieve the current user's phone integration.

GET https://yoursite.desk.com/api/v2/users/current/phone_integration

GET https://yoursite.desk.com/api/v2/users/me/phone_integration

Applicable Roles

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

Fields

field name description
id id for this resource
name name of the phone integration
url url of the phone integration
height height of the softphone panel in pixels
width width of the softphone panel in pixels
active boolean for the active status of the phone integration

Links

rel class embeddable? description
self phone_integration no this phone integration

Example Curl Request

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

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "id": 27,
  "name": "Demo",
  "url": "https://demodeskcti.herokuapp.com",
  "height": 100,
  "width": 100,
  "active": true,
  "_links": {
    "self": {
      "href": "/api/v2/users/me/phone_integration",
      "class": "phone_integration"
    }
  }
}

Case Layout

Retrieve the current user's case layout.

GET https://yoursite.desk.com/api/v2/users/current/case_layout

GET https://yoursite.desk.com/api/v2/users/me/case_layout

Applicable Roles

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

Fields

field name description
name name of the case layout
defaut boolean for if this is the default case layout
system boolean for if this is the system case layout
layout array of the layout objects

Links

rel class embeddable? description
self case_layout no this case layout

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/users/current/case_layout \
    -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
{
  "name": "Agent Layout",
  "default": false,
  "system": false,
  "layout": [
    [
      {
        "type": "standard",
        "id": "subject",
        "width": 2,
        "input_type": "string"
      }
    ],
    [
      {
        "type": "standard",
        "id": "status",
        "width": 1,
        "input_type": "list"
      },
      {
        "type": "standard",
        "id": "agent",
        "width": 1,
        "input_type": "list"
      }
    ],
    [
      {
        "type": "standard",
        "id": "group",
        "width": 1,
        "input_type": "list"
      },
      {
        "type": "standard",
        "id": "priority",
        "width": 1,
        "input_type": "list"
      }
    ],
    [
      {
        "type": "standard",
        "id": "description",
        "width": 2,
        "input_type": "string"
      }
    ],
    [
      {
        "type": "standard",
        "id": "labels",
        "width": 2,
        "input_type": "tag_cloud"
      }
    ],
    [
      {
        "type": "integration_url",
        "id": "432465",
        "width": 2,
        "input_type": "",
        "height": "500"
      }
    ]
  ],
  "_links": {
    "self": {
      "href": "/api/v2/users/me/case_layout",
      "class": "case_layout"
    }
  }
}

List Filters

Retrieve a paginated list of all filters for the user sorted by the position field.

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

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/users/: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/users/12367/filters?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/users/12367/filters?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/users/12367/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": "Spam Cases",
        "sort_field": "priority",
        "sort_direction": "desc",
        "position": 2,
        "active": true,
        "_links": {
          "self": {
            "href": "/api/v2/filters/2",
            "class": "filter"
          },
          "group": null,
          "user": null,
          "cases": {
            "href": "/api/v2/filters/2/cases",
            "class": "case"
          }
        }
      }
    ]
  }
}

Mobile Device Fields

Mobile Devices have the following fields and links:

Fields

field description
id this object's id
device_token a unique identifier for the physical device, provided by the device's manufacturer
type currently only ios is supported
created_at when this object was created
updated_at when this object was last updated

Links

rel class embeddable? description
self mobile_device no this object
user user no the user to which this device belongs

List Mobile Devices

List all of the user's mobile devices.

Applicable Roles

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

Only devices belonging to the current user may be accessed.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/users/1/mobile_devices \
    -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
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/mobile_devices?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/mobile_devices?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/mobile_devices?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "id": 1,
        "device_token": "1234abcde",
        "type": "ios",
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:08:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/users/1/mobile_devices/1",
            "class": "mobile_device"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "id": 2,
        "device_token": "123abc",
        "type": "ios",
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:08:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/users/1/mobile_devices/2",
            "class": "mobile_device"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      }
    ]
  }
}

Show Mobile Device

Show a single Mobile Device

Applicable Roles

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

Only devices belonging to the current user may be accessed.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/users/1/mobile_devices/1 \
    -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
{
  "id": 1,
  "device_token": "1234abcde",
  "type": "ios",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:08:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/users/1/mobile_devices/1",
      "class": "mobile_device"
    },
    "user": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Delete Mobile Device

Delete a mobile device

DELETE https://yoursite.desk.com/api/v2/users/:user_id/mobile_devices/: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
4
5
$ curl https://yoursite.desk.com/api/v2/users/:user_id/mobile_devices/:id \
    -u email:password \
    -X DELETE \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Response

1
204 No Content

Mobile Device Setting Fields

Mobile Device Settings have the following fields and links:

Fields

field description
id identifier of the notification setting
name name of the notification setting
value value of the setting, currently only true and false are supported

Links

rel class embeddable? description
self mobile_setting no the link to the setting
mobile_device mobile_device no the mobile device this setting belongs to

List Mobile Device Settings

Retrieve a list of mobile device settings.

GET https://yoursite.desk.com/api/v2/users/:user_id/mobile_devices/:mobile_device_id/settings

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/users/:user_id/mobile_devices/:mobile_device_id/settings \
    -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
107
108
109
110
111
112
113
114
{
  "total_entries": 6,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/users/1/mobile_devices/1/settings?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/users/1/mobile_devices/1/settings?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/users/1/mobile_devices/1/settings?page=1&per_page=50",
      "class": "page"
    },
    "previous": null,
    "next": null
  },
  "_embedded": {
    "entries": [
      {
        "id": 100,
        "name": "case_created",
        "value": false,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/mobile_devices/1/settings/100",
            "class": "mobile_setting"
          },
          "mobile_device": {
            "href": "/api/v2/users/1/mobile_devices/1",
            "class": "mobile_device"
          }
        }
      },
      {
        "id": 200,
        "name": "case_assigned_to_me",
        "value": false,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/mobile_devices/1/settings/200",
            "class": "mobile_setting"
          },
          "mobile_device": {
            "href": "/api/v2/users/1/mobile_devices/1",
            "class": "mobile_device"
          }
        }
      },
      {
        "id": 210,
        "name": "new_case_assigned_to_group",
        "value": false,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/mobile_devices/1/settings/210",
            "class": "mobile_setting"
          },
          "mobile_device": {
            "href": "/api/v2/users/1/mobile_devices/1",
            "class": "mobile_device"
          }
        }
      },
      {
        "id": 300,
        "name": "case_priority_changed",
        "value": false,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/mobile_devices/1/settings/300",
            "class": "mobile_setting"
          },
          "mobile_device": {
            "href": "/api/v2/users/1/mobile_devices/1",
            "class": "mobile_device"
          }
        }
      },
      {
        "id": 400,
        "name": "new_case_response",
        "value": false,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/mobile_devices/1/settings/400",
            "class": "mobile_setting"
          },
          "mobile_device": {
            "href": "/api/v2/users/1/mobile_devices/1",
            "class": "mobile_device"
          }
        }
      },
      {
        "id": 500,
        "name": "case_note_created",
        "value": false,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/mobile_devices/1/settings/500",
            "class": "mobile_setting"
          },
          "mobile_device": {
            "href": "/api/v2/users/1/mobile_devices/1",
            "class": "mobile_device"
          }
        }
      }
    ]
  }
}

Update Mobile Device Setting

Update a mobile device setting

PATCH https://yoursite.desk.com/api/v2/users/:user_id/mobile_devices/:mobile_device_id/settings/:id

Applicable Roles

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

Fields

field description
value value of preference (true or false)

Setting list

Below is a list of available settings for mobile devices.

id name if true, notified when
100 case_created a case is created
200 case_assigned_to_me a case is assigned to user
210 new_case_assigned_to_group a new case is assigned to group
300 case_priority_changed a case's priority changed
400 new_case_response a case has a new response
500 case_note_created a case has a new note added

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/users/:user_id/mobile_device/:mobile_device_id/settings/:id \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"value":true}'

Example Request Body

1
2
3
{
  "value": true
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "id": 100,
  "name": "case_created",
  "value": true,
  "_links": {
    "self": {
      "href": "/api/v2/mobile_devices/1/settings/100",
      "class": "mobile_setting"
    },
    "mobile_device": {
      "href": "/api/v2/mobile_devices/100",
      "class": "mobile_device"
    }
  }
}

List Macros

Retrieve a paginated list of all Macros the given User can apply to a Case.

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

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/users/:id/macros \
    -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
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/macros?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/macros?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/macros?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "Macro Macro",
        "description": "On repeat",
        "enabled": true,
        "position": 1,
        "folders": [
          "Sample Macros",
          "Favorites"
        ],
        "_links": {
          "self": {
            "href": "/api/v2/macros/1",
            "class": "macro"
          },
          "actions": {
            "href": "/api/v2/macros/1/actions",
            "class": "macro_action"
          }
        }
      },
      {
        "name": "Another Macro",
        "description": null,
        "enabled": true,
        "position": 2,
        "folders": [
          "Sample Macros",
          "Favorites"
        ],
        "_links": {
          "self": {
            "href": "/api/v2/macros/2",
            "class": "macro"
          },
          "actions": {
            "href": "/api/v2/macros/1/actions",
            "class": "macro_action"
          }
        }
      }
    ]
  }
}

Preference Fields

User Preference objects have the following fields and links:

Fields

field description
name the name of the preference
value value of preference

Links

rel class embeddable? description
self user_preference no this user preference
user user yes the user to which this preference belongs

enable_routing_filter_on_login Link

When setting enable_routing_filter_on_login to a filter, a link to the filter will be present.

rel class embeddable? description
filter filter no filter being used for routing

case_default_view Link

When setting case_default_view to an integration url, a link to the integration url will be present.

rel class embeddable? description
integration_url integration_url no integration_url being used in the default case view

List Preferences

List all of the user's preferences.

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/users/1/preferences \
    -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
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
{
  "total_entries": 14,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/users/1/preferences?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/users/1/preferences?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/users/1/preferences?page=1&per_page=50",
      "class": "page"
    },
    "previous": null,
    "next": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "enable_routing_filter_on_login",
        "value": "12",
        "id": 1001,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/1001",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          },
          "filter": {
            "href": "/api/v2/filters/12",
            "class": "filter"
          }
        }
      },
      {
        "name": "scroll_to_bottom_on_open",
        "value": "1",
        "id": 2000,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/2000",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "auto_accept_on_route",
        "value": false,
        "id": 2100,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/2100",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "case_filter_view",
        "value": "200",
        "id": 2200,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/2200",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "warn_before_exit",
        "value": false,
        "id": 2300,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/2300",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "screenpop_sound",
        "value": "80",
        "id": 3000,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/3000",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "screenpop_sound_repeat_enabled",
        "value": false,
        "id": 3100,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/3100",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "inactivity_sound",
        "value": "10",
        "id": 3500,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/3500",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "inactivity_sound_repeat_enabled",
        "value": false,
        "id": 3600,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/3600",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "new_chat_message_sound",
        "value": "70",
        "id": 3800,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/3800",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "confirm_on_short_replies",
        "value": true,
        "id": 4000,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/4000",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "case_default_view",
        "value": "-1",
        "id": 5000,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/5000",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "show_labels_in_case_filter_view",
        "value": true,
        "id": 6000,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/6000",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "bulk_case_filter_manage_confirm",
        "value": true,
        "id": 7000,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/7000",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "knows_about_inline_macros",
        "value": true,
        "id": 8000,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/8000",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "enable_kb_shortcuts",
        "value": true,
        "id": 9000,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/9000",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "name": "language",
        "value": "en_us",
        "id": 10000,
        "_links": {
          "self": {
            "href": "/api/v2/users/1/preferences/10000",
            "class": "user_preference"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      }
    ]
  }
}

Show Preference

Show a single user preference

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/users/1/preferences/1 \
    -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
{
  "name": "enable_routing_filter_on_login",
  "value": "12",
  "_links": {
    "self": {
      "href": "/api/v2/users/1/preferences/1",
      "class": "user_preference"
    },
    "user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "filter": {
      "href": "/api/v2/filters/12",
      "class": "filter"
    }
  }
}

Update Preference

Update a user preference

PATCH https://yoursite.desk.com/api/v2/users/:user_id/preferences/:id

Applicable Roles

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

Fields

field description
value value of preference

enable_routing_filter_on_login link

When setting enable_routing_filter_on_login to a filter, you may use a link to the filter to be assigned.

rel description
filter filter to be used

ticket_default_view link

When setting ticket_default_view to an integration url, you may use a link to the integration url to be assigned.

rel description
integration_url integration_url to be used

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/users/:user_id/preferences/:id \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"value":true}'

Example Request Body

1
2
3
{
  "value": true
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "name": "auto_accept_on_route",
  "value": true,
  "_links": {
    "self": {
      "href": "/api/v2/users/1/preferences/3",
      "class": "user_preference"
    },
    "user": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Preference Types

NOTE: Default values are highlighted

enable_routing_filter_on_login

Automatically start routing as soon as you login

Possible values:

value description
-2 route by priority and permissions
0 disabled
filter_id any filter id will enable routing only for the specified filter

scroll_to_bottom_on_open

Default action when the case is open

value description
0 scroll to the first interaction and put cursor in macro box
1 scroll to the last interaction and put cursor in reply box
2 scroll to the last interaction and put cursor in macro box

auto_accept_on_route

Automatically accept a screen-popped case (you will not see the screen-pop).

value description
true enabled
false disabled

case_filter_view

The default view when you login and view case filters

value description
100 full
200 table

warn_before_exit

Warn prior to exiting the Desk.com Desktop to prevent accidental closure of the desktop and possible data loss

value description
true enabled
false disabled

screenpop_sound

Play sounds on screenpop events to help alert the agent.

value description
0 (Disabled)
10 Bass
20 Beat
30 Beep
40 Grumble
50 Low Ripple
60 Perky
70 Pew
80 Phone Ringing
90 Swish
100 Synth

screenpop_sound_repeat_enabled

If the screenpop sound is enabled this setting will repeat it until you take action.

value description
true enabled
false disabled

inactivity_sound

Play sounds on inactivity to help alert the agent they will be logged out.

value description
0 (Disabled)
10 Bass
20 Beat
30 Beep
40 Grumble
50 Low Ripple
60 Perky
70 Pew
80 Phone Ringing
90 Swish
100 Synth

inactivity_sound_repeat_enabled

If the inactivity sound is enabled this setting will repeat it until you take action.

value description
true enabled
false disabled

new_chat_message_sound

Play sounds when an agent receives a new chat message

value description
0 (Disabled)
10 Bass
20 Beat
30 Beep
40 Grumble
50 Low Ripple
60 Perky
70 Pew
80 Phone Ringing
90 Swish
100 Synth

confirm_on_short_replies

When a message is less than 10 characters confirm that it should be sent.

value description
true enabled
false disabled

case_default_view

The default view when you work on a case (case, customer or integration urls that are inline)

value description
-2 customer view
-1 case view
integration_url_id id of any integration url

show_labels_in_case_filter_view

Display labels when viewing cases in the case filter view

value description
true enabled
false disabled

bulk_case_filter_manage_confirm

Display confirmation when applying bulk changes to cases

value description
true enabled
false disabled

Permission Fields

User 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 user no the user to which this permission is scoped
delete site no implies the permission is scoped to site
delete group no the group to which this permission is scoped
export user no the user 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 user'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/users/:user_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/users/1/permissions?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/users/1/permissions?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/users/1/permissions?page=1&per_page=50",
      "class": "page"
    },
    "previous": null,
    "next": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "cases",
        "_links": {
          "delete": {
            "href": "/api/v2/users/1",
            "class": "user"
          },
          "export": {
            "href": null,
            "class": "site"
          }
        }
      },
      {
        "name": "content",
        "_links": {
          "delete": {
            "href": "/api/v2/groups/1",
            "class": "group"
          }
        }
      }
    ]
  }
}

Search Fields

Saved Search objects have the following fields and links:

Fields

field description
name name of the saved search
query query to be used when searching
search_object what is to be searched (one of case, customer, or company)

Links

rel class embeddable? description
self search no this saved search
user user yes user to whom this search belongs
results case,company,customer no search results for the saved search

List Searches

A list of saved searches for the user

GET https://yoursite.desk.com/api/v2/users/:user_id/searches

Applicable Roles

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

Fields

Please see Show Search for details on the specific fields for each search.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/users/:user_id/searches \
    -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
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/users/1/searches?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/users/1/searches?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/users/1/searches?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "my new, open and pending email cases",
        "query": "assigned:me channel:email status:new,open,pending",
        "search_object": "case",
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:08:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/users/1/searches/1",
            "class": "search"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          },
          "results": {
            "href": "/api/v2/cases/search?q=assigned:me",
            "class": "case"
          }
        }
      },
      {
        "name": "updated by me today",
        "query": "assigned:me updated:today status:pending",
        "search_object": "case",
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:08:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/users/1/searches/2",
            "class": "search"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          },
          "results": {
            "href": "/api/v2/cases/search?q=assigned:me%20updated:today%20status:pending",
            "class": "case"
          }
        }
      }
    ]
  }
}

Show Search

Show a saved search

GET https://yoursite.desk.com/api/v2/users/:user_id/searches/: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/users/:user_id/searches/1 \
    -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
{
  "name": "my new, open and pending email cases",
  "query": "assigned:me channel:email status:new,open,pending",
  "search_object": "case",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:08:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/users/1/searches/1",
      "class": "search"
    },
    "user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "results": {
      "href": "/api/v2/cases/search?q=assigned:me",
      "class": "case"
    }
  }
}

Create Search

Create a saved search

POST https://yoursite.desk.com/api/v2/users/:user_id/searches

Applicable Roles

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

Fields

Please see Show Search for details on the specific fields for each search.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/users/:user_id/searches \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Assigned to me", "query":"assigned:me", "search_object":"case"}'

Example Request Body

1
2
3
4
5
{
  "name": "Assigned to me",
  "query": "assigned:me",
  "search_object": "case"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "name": "Assigned to me",
  "query": "assigned:me",
  "search_object": "case",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:08:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/users/1/searches/1",
      "class": "search"
    },
    "user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "results": {
      "href": "/api/v2/cases/search?q=assigned:me",
      "class": "case"
    }
  }
}

Update Search

Update a saved search

PATCH https://yoursite.desk.com/api/v2/users/:user_id/searches/:id

Applicable Roles

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

Fields

Please see Show Search for details on the specific fields for each search.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/users/:user_id/searches/1 \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Assigned to me", "query":"assigned:me", "search_object":"case"}'

Example Request Body

1
2
3
4
5
{
  "name": "Assigned to me",
  "query": "assigned:me",
  "search_object": "case"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "name": "Assigned to me",
  "query": "assigned:me",
  "search_object": "case",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:08:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/users/1/searches/1",
      "class": "search"
    },
    "user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "results": {
      "href": "/api/v2/cases/search?q=assigned:me",
      "class": "case"
    }
  }
}

Delete Search

Delete a saved search

DELETE https://yoursite.desk.com/api/v2/users/:user_id/searches/: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
4
5
$ curl https://yoursite.desk.com/api/v2/users/:user_id/searches/:id \
    -u email:password \
    -X DELETE \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Response

1
204 No Content

List Groups

Retrieve a paginated list of all groups for a given user.

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

Applicable Roles

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

ETags

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

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/users/1/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
      }
    ]
  }
}