Fields

Label objects have the following fields and links:

Fields

field name description
id identifier for this resource
name name of the label
description an optional description
enabled whether or not the label can be used in the Agent
types an array of the label's types. Can be case or macro
color the color representing the label - one of default, blue, white, yellow, red, orange, green, black, purple, brown, grey, pink

Links

rel class description
self label this label

List

Retrieve a paginated list of all labels. This endpoint accepts a max per_page param value of 1000.

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

Applicable Roles

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

ETags

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

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/labels \
    -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
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/labels?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/labels?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/labels?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "id": 1,
        "name": "MyLabel",
        "description": "My Label Description",
        "types": [
          "case",
          "macro"
        ],
        "active": true,
        "color": "green",
        "position": 1,
        "_links": {
          "self": {
            "href": "/api/v2/labels/1",
            "class": "label"
          }
        }
      },
      {
        "id": 1,
        "name": "Another Label",
        "description": "Label Description",
        "types": [
          "case",
          "macro"
        ],
        "active": true,
        "color": "green",
        "position": 2,
        "_links": {
          "self": {
            "href": "/api/v2/labels/2",
            "class": "label"
          }
        }
      }
    ]
  }
}

Show

Retrieve a single label.

GET https://yoursite.desk.com/api/v2/labels/: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/labels/:id \
    -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
{
  "id": 1,
  "name": "MyLabel",
  "description": "My Label Description",
  "types": [
    "case",
    "macro"
  ],
  "active": true,
  "color": "green",
  "position": 1,
  "_links": {
    "self": {
      "href": "/api/v2/labels/1",
      "class": "label"
    }
  }
}

Create

Create a label.

POST https://yoursite.desk.com/api/v2/labels

Applicable Roles

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

Fields

field name description
name label's name
description label's description
types an array of the label's types. Can be case, macro, or article
enabled whether or not this label is enabled
color the color representing the label - one of default, blue, white, yellow, red, orange, green, black, purple, brown, grey, pink

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/labels \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"MyLabel","description":"A Test Label", "types": ["case", "macro"], "color": "blue"}'

Example Request Body

1
2
3
4
5
6
7
8
9
{
  "name": "MyLabel",
  "description": "A Test Label",
  "types": [
    "case",
    "macro"
  ],
  "color": "blue"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "id": 1,
  "name": "My Label",
  "description": "A Test Label",
  "types": [
    "case",
    "macro"
  ],
  "active": true,
  "color": "blue",
  "position": 1,
  "_links": {
    "self": {
      "href": "/api/v2/labels/1",
      "class": "label"
    }
  }
}

Update

Update a label.

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

Applicable Roles

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

Fields

Please see Create for details on the fields available for update.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/labels/1 \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Label 5"}'

Example Request Body

1
2
3
{
  "name": "Label 5"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "id": 1,
  "name": "Label 5",
  "description": "My Label Description",
  "types": [
    "case",
    "macro"
  ],
  "active": true,
  "color": "green",
  "position": 1,
  "_links": {
    "self": {
      "href": "/api/v2/labels/1",
      "class": "label"
    }
  }
}

Delete

Delete a label.

DELETE https://yoursite.desk.com/api/v2/labels/:id

Applicable Roles

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/labels/1 \
    -u email:password \
    -X DELETE

Example Response

1
204 No Content