Fields

Brand objects have the following fields and links:

Fields

field name description
name name of the brand
created_at when the brand was created
updated_at when the brand was last updated

Links

rel class embeddable? description
self brand no this brand

List

Retrieve a paginated list of all brands.

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

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/brands \
    -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
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/brands?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/brands?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/brands?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "Desk.com",
        "created_at": "2017-07-20T22:43:30Z",
        "updated_at": "2017-07-20T22:43:30Z",
        "_links": {
          "self": {
            "href": "/api/v2/brands/1",
            "class": "brand"
          },
          "articles": {
            "href": "/api/v2/brands/1/articles",
            "class": "article"
          }
        }
      },
      {
        "name": "Alpha Inc",
        "created_at": "2017-07-20T22:43:30Z",
        "updated_at": "2017-07-20T22:43:30Z",
        "_links": {
          "self": {
            "href": "/api/v2/brands/2",
            "class": "brand"
          },
          "articles": {
            "href": "/api/v2/brands/2/articles",
            "class": "article"
          }
        }
      }
    ]
  }
}

Show

Retrieve a single brand.

GET https://yoursite.desk.com/api/v2/brands/: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/brands/: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": "Desk.com",
  "created_at": "2017-07-20T22:43:30Z",
  "updated_at": "2017-07-20T22:43:30Z",
  "_links": {
    "self": {
      "href": "/api/v2/brands/1",
      "class": "brand"
    },
    "articles": {
      "href": "/api/v2/brands/1/articles",
      "class": "article"
    }
  }
}

List Articles

Retrieve a paginated list of all articles for a brand.

GET https://yoursite.desk.com/api/v2/brands/:id/articles

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/brands/1/articles \
    -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
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/articles?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/articles?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/articles?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "subject": "Awesome Subject",
        "body": "<p>Awesome apples</p>",
        "body_email": "Email for Awesome apples",
        "body_email_auto": false,
        "body_chat": "Awesome apples",
        "body_chat_auto": true,
        "body_web_callback": "<p>Awesome Apples</p>",
        "body_web_callback_auto": false,
        "body_twitter": "Awesome apples",
        "body_twitter_auto": true,
        "body_qna": "Awesome apples",
        "body_qna_auto": true,
        "body_phone": "Awesome apples",
        "body_phone_auto": true,
        "body_facebook": "Awesome apples",
        "body_facebook_auto": true,
        "rating": 75,
        "rating_count": 4,
        "rating_score": 3,
        "position": 1,
        "quickcode": "AWESOME",
        "in_support_center": true,
        "internal_notes": "Notes to the agent here",
        "publish_at": "2017-07-20T22:48:30Z",
        "created_at": "2017-07-20T22:43:30Z",
        "updated_at": "2017-07-20T22:48:30Z",
        "_links": {
          "self": {
            "href": "/api/v2/articles/1",
            "class": "article"
          },
          "topic": {
            "href": "/api/v2/topics/1",
            "class": "topic"
          },
          "translations": {
            "href": "/api/v2/articles/1/translations",
            "class": "article_translation"
          },
          "attachments": {
            "href": "/api/v2/articles/1/attachments",
            "class": "attachment",
            "count": 1
          },
          "brands": null,
          "created_by": {
            "href": "/api/v2/users/1",
            "class": "user"
          },
          "updated_by": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "subject": "How to make your customers happy",
        "body": "<strong>Use Desk.com</strong>",
        "body_email": "Email just doesn't cut it",
        "body_email_auto": false,
        "body_chat": "Use Desk.com",
        "body_chat_auto": true,
        "body_web_callback": "<strong>Use Desk.com</strong>",
        "body_web_callback_auto": false,
        "body_twitter": "Use Desk.com in 140 chars or less",
        "body_twitter_auto": false,
        "body_qna": "Use Desk.com",
        "body_qna_auto": true,
        "body_phone": "Use Desk.com",
        "body_phone_auto": true,
        "body_facebook": "Use Desk.com",
        "body_facebook_auto": true,
        "rating": 75,
        "rating_count": 4,
        "rating_score": 3,
        "position": 1,
        "quickcode": "AWESOME",
        "in_support_center": true,
        "internal_notes": "Notes to the agent here",
        "publish_at": "2017-07-20T22:48:30Z",
        "created_at": "2017-07-20T22:43:30Z",
        "updated_at": "2017-07-20T22:48:30Z",
        "_links": {
          "self": {
            "href": "/api/v2/articles/2",
            "class": "article"
          },
          "topic": {
            "href": "/api/v2/topics/1",
            "class": "topic"
          },
          "translations": {
            "href": "/api/v2/articles/2/translations",
            "class": "article_translation"
          },
          "attachments": {
            "href": "/api/v2/articles/1/attachments",
            "class": "attachment",
            "count": 1
          },
          "brands": null,
          "created_by": {
            "href": "/api/v2/users/1",
            "class": "user"
          },
          "updated_by": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      }
    ]
  }
}

List Topics

Retrieve a paginated list of topics for this brand.

GET https://yoursite.desk.com/api/v2/brands/:brand_id/topics

Applicable Roles

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

Request Headers

header name description
Accept-Language ISO language code. Return only topics for this language code and return the translated fields for the name and description.

Sorting

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

  • sort_field - the field to sort by: id or position
  • sort_direction - direction to sort: asc for ascending, desc for descending

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/brands/1/topics \
    -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
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/brands/1/topics?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/brands/1/topics?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/brands/1/topics?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "Customer Support",
        "description": "This is key to going from good to great",
        "position": 1,
        "allow_questions": true,
        "in_support_center": true,
        "created_at": "2017-07-10T22:53:30Z",
        "updated_at": "2017-07-15T22:53:30Z",
        "_links": {
          "self": {
            "href": "/api/v2/brands/1/topics/1",
            "class": "topic"
          },
          "articles": {
            "href": "/api/v2/topics/1/articles",
            "class": "article"
          },
          "translations": {
            "href": "/api/v2/topics/1/translations",
            "class": "topic_translation"
          }
        }
      },
      {
        "name": "Another Topic",
        "description": "Not the first one, but another one!",
        "position": 2,
        "allow_questions": true,
        "in_support_center": true,
        "created_at": "2017-07-10T22:53:30Z",
        "updated_at": "2017-07-15T22:53:30Z",
        "_links": {
          "self": {
            "href": "/api/v2/brands/1/topics/2",
            "class": "topic"
          },
          "articles": {
            "href": "/api/v2/topics/1/articles",
            "class": "article"
          },
          "translations": {
            "href": "/api/v2/topics/1/translations",
            "class": "topic_translation"
          }
        }
      }
    ]
  }
}