Fields

Custom Field objects have the following fields and links:

Fields

field name description
name custom field name. This corresponds with the key value in the Desk.com Admin
label custom field label. This corresponds with the name value in the Desk.com Admin
type 'ticket' or 'customer'
active whether or not this custom field is active
data a hash containing the custom field's data type ('string', 'boolean', 'integer', 'date' or 'list'); if the custom field is a list, this field will also contain an array of choices

Links

rel class embeddable? description
self custom field no this custom field

List

Retrieve a paginated list of all custom fields.

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

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/custom_fields \
    -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
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/custom_fields?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/custom_fields?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/custom_fields?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "frequent_buyer",
        "label": "Frequent Buyer",
        "type": "customer",
        "active": true,
        "data": {
          "type": "boolean"
        },
        "_links": {
          "self": {
            "href": "/api/v2/custom_fields/1",
            "class": "custom_field"
          }
        }
      },
      {
        "name": "last_agent",
        "label": "Last Agent to Update",
        "type": "ticket",
        "active": false,
        "data": {
          "type": "list",
          "choices": [
            "Marianne",
            "Elinor",
            "Margaret"
          ]
        },
        "_links": {
          "self": {
            "href": "/api/v2/custom_fields/2",
            "class": "custom_field"
          }
        }
      }
    ]
  }
}

Show

Retrieve a single custom field.

GET https://yoursite.desk.com/api/v2/custom_field/: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/custom_fields/: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
{
  "name": "frequent_buyer",
  "label": "Frequent Buyer",
  "type": "customer",
  "active": true,
  "data": {
    "type": "boolean"
  },
  "_links": {
    "self": {
      "href": "/api/v2/custom_fields/1",
      "class": "custom_field"
    }
  }
}

Create

Create a custom field.

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

Applicable Roles

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

Example Curl Request

1
2
3
4
5
6
7
8
9
$ curl https://yoursite.desk.com/api/v2/custom_fields \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"List Custom Field", \
         "label":"list_custom_field", \
         "type":"customer", \
         "data": {"type":"list", "choices":["one", "two", "three"]}}'

Example Request Body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "name": "List Custom Field",
  "label": "list_custom_field",
  "type": "customer",
  "data": {
    "type": "list",
    "choices": [
      "one",
      "two",
      "three"
    ]
  }
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "name": "List Custom Field",
  "label": "list_custom_field",
  "type": "customer",
  "active": true,
  "data": {
    "type": "list",
    "choices": [
      "one",
      "two",
      "three"
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v2/custom_fields/1",
      "class": "custom_field"
    }
  }
}

Update

Update a custom field.

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

Applicable Roles

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

Example Curl Request

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

Example Request Body

1
2
3
4
{
  "name": "New Name",
  "active": false
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "name": "New Name",
  "label": "Frequent Buyer",
  "type": "customer",
  "active": false,
  "data": {
    "type": "boolean"
  },
  "_links": {
    "self": {
      "href": "/api/v2/custom_fields/1",
      "class": "custom_field"
    }
  }
}

Delete

Delete a custom field.

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

Applicable Roles

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

Example Response

1
204 No Content