Brands
Brands are your customer-facing identities. They might represent multiple products or services, or they might literally be multiple brands owned and represented by your company.
The default brand is the one that tickets get assigned to if the ticket is generated from a non-branded channel. You can update the default brand using the Update Account Settings endpoint.
JSON Format
Brands are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
active | boolean | false | false | If the brand is set as active |
brand_url | string | false | false | The url of the brand |
created_at | string | true | false | The time the brand was created |
default | boolean | false | false | Is the brand the default brand for this account |
has_help_center | boolean | false | false | If the brand has a Help Center |
help_center_state | string | true | false | The state of the Help Center. Allowed values are "enabled", "disabled", or "restricted". |
host_mapping | string | false | false | The hostmapping to this brand, if any. Only admins view this property. |
id | integer | true | false | The ID automatically assigned when the brand is created |
is_deleted | boolean | false | false | If the brand object is deleted or not |
logo | object | false | false | A file represented as an Attachment object |
name | string | false | true | The name of the brand |
signature_template | string | false | false | The signature template for a brand |
subdomain | string | false | true | The subdomain of the brand |
ticket_form_ids | array | true | false | The ids of ticket forms that are available for use by a brand |
updated_at | string | true | false | The time of the last update of the brand |
url | string | true | false | The API url of this brand |
Example
{
"active": true,
"brand_url": "https://brand1.com",
"created_at": "2012-04-02T22:55:29Z",
"default": true,
"has_help_center": true,
"help_center_state": "enabled",
"host_mapping": "brand1.com",
"id": 47,
"logo": {
"content_type": "image/png",
"content_url": "https://company.zendesk.com/logos/brand1_logo.png",
"file_name": "brand1_logo.png",
"id": 928374,
"size": 166144,
"thumbnails": [
{
"content_type": "image/png",
"content_url": "https://company.zendesk.com/photos/brand1_logo_thumb.png",
"file_name": "brand1_logo_thumb.png",
"id": 928375,
"mapped_content_url": "https://company.com/photos/brand1_logo_thumb.png",
"size": 58298,
"url": "https://company.zendesk.com/api/v2/attachments/928375.json"
},
{
"content_type": "image/png",
"content_url": "https://company.zendesk.com/photos/brand1_logo_small.png",
"file_name": "brand1_logo_small.png",
"id": 928376,
"mapped_content_url": "https://company.com/photos/brand1_logo_small.png",
"size": 58298,
"url": "https://company.zendesk.com/api/v2/attachments/928376.json"
}
],
"url": "https://company.zendesk.com/api/v2/attachments/928374.json"
},
"name": "Brand 1",
"signature_template": "{{agent.signature}}",
"subdomain": "brand1",
"ticket_form_ids": [
47,
33,
22
],
"updated_at": "2012-04-02T22:55:29Z",
"url": "https://company.zendesk.com/api/v2/brands/47.json"
}
List Brands
GET /api/v2/brands
Returns a list of all brands for your account sorted by name.
Allowed for
- Admins, Agents
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/brands.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"brands": [
{
"active": true,
"brand_url": "https://brand1.zendesk.com",
"created_at": "2019-08-06T02:43:39Z",
"default": true,
"has_help_center": true,
"help_center_state": "enabled",
"host_mapping": "brand1.com",
"id": 360002783572,
"is_deleted": false,
"logo": {
"content_type": "image/png",
"content_url": "https://company.zendesk.com/logos/brand1_logo.png",
"file_name": "brand1_logo.png",
"id": 928374,
"mapped_content_url": "https://company.com/logos/brand1_logo.png",
"size": 166144,
"thumbnails": [
{
"content_type": "image/png",
"content_url": "https://company.zendesk.com/photos/brand1_logo_thumb.png",
"file_name": "brand1_logo_thumb.png",
"id": 928375,
"mapped_content_url": "https://company.com/photos/brand1_logo_thumb.png",
"size": 58298,
"url": "https://company.zendesk.com/api/v2/attachments/928375.json"
},
{
"content_type": "image/png",
"content_url": "https://company.zendesk.com/photos/brand1_logo_small.png",
"file_name": "brand1_logo_small.png",
"id": 928376,
"mapped_content_url": "https://company.com/photos/brand1_logo_small.png",
"size": 58298,
"url": "https://company.zendesk.com/api/v2/attachments/928376.json"
}
],
"url": "https://company.zendesk.com/api/v2/attachments/928374.json"
},
"name": "Brand 1",
"signature_template": "{{agent.signature}}",
"subdomain": "hello-world",
"ticket_form_ids": [
360000660811
],
"updated_at": "2019-08-06T02:43:40Z",
"url": "https://company.zendesk.com/api/v2/brands/360002783572.json"
}
],
"count": 1,
"next_page": null,
"previous_page": null
}
Show a Brand
GET /api/v2/brands/{brand_id}
Returns a brand for your account.
Allowed for
- Admins, Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
brand_id | integer | Path | true | The ID of the brand |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/brands/{brand_id}.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"brand": {
"active": true,
"brand_url": "https://brand1.zendesk.com",
"created_at": "2019-08-06T02:43:39Z",
"default": true,
"has_help_center": true,
"help_center_state": "enabled",
"host_mapping": "brand1.com",
"id": 360002783572,
"is_deleted": false,
"logo": {
"content_type": "image/png",
"content_url": "https://company.zendesk.com/logos/brand1_logo.png",
"file_name": "brand1_logo.png",
"id": 928374,
"mapped_content_url": "https://company.com/logos/brand1_logo.png",
"size": 166144,
"thumbnails": [
{
"content_type": "image/png",
"content_url": "https://company.zendesk.com/photos/brand1_logo_thumb.png",
"file_name": "brand1_logo_thumb.png",
"id": 928375,
"mapped_content_url": "https://company.com/photos/brand1_logo_thumb.png",
"size": 58298,
"url": "https://company.zendesk.com/api/v2/attachments/928375.json"
},
{
"content_type": "image/png",
"content_url": "https://company.zendesk.com/photos/brand1_logo_small.png",
"file_name": "brand1_logo_small.png",
"id": 928376,
"mapped_content_url": "https://company.com/photos/brand1_logo_small.png",
"size": 58298,
"url": "https://company.zendesk.com/api/v2/attachments/928376.json"
}
],
"url": "https://company.zendesk.com/api/v2/attachments/928374.json"
},
"name": "Brand 1",
"signature_template": "{{agent.signature}}",
"subdomain": "hello-world",
"ticket_form_ids": [
360000660811
],
"updated_at": "2019-08-06T02:43:40Z",
"url": "https://company.zendesk.com/api/v2/brands/360002783572.json"
}
}
Create Brand
POST /api/v2/brands
Allowed for
- Admins
Example Body
{
"brand": {
"name": "Brand 1",
"subdomain": "Brand1"
}
}
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/brands.json \
-H "Content-Type: application/json" -X POST \
-d '{"brand": {"name": "Brand 1", "subdomain": "brand1"}}' \
-v -u {email_address}:{password}
Example Response
Status 201 Created
{
"brand": {
"active": true,
"brand_url": "https://brand1.zendesk.com",
"created_at": "2019-08-06T02:43:39Z",
"default": true,
"has_help_center": true,
"help_center_state": "enabled",
"host_mapping": "brand1.com",
"id": 360002783572,
"is_deleted": false,
"logo": {
"content_type": "image/png",
"content_url": "https://company.zendesk.com/logos/brand1_logo.png",
"file_name": "brand1_logo.png",
"id": 928374,
"mapped_content_url": "https://company.com/logos/brand1_logo.png",
"size": 166144,
"thumbnails": [
{
"content_type": "image/png",
"content_url": "https://company.zendesk.com/photos/brand1_logo_thumb.png",
"file_name": "brand1_logo_thumb.png",
"id": 928375,
"mapped_content_url": "https://company.com/photos/brand1_logo_thumb.png",
"size": 58298,
"url": "https://company.zendesk.com/api/v2/attachments/928375.json"
},
{
"content_type": "image/png",
"content_url": "https://company.zendesk.com/photos/brand1_logo_small.png",
"file_name": "brand1_logo_small.png",
"id": 928376,
"mapped_content_url": "https://company.com/photos/brand1_logo_small.png",
"size": 58298,
"url": "https://company.zendesk.com/api/v2/attachments/928376.json"
}
],
"url": "https://company.zendesk.com/api/v2/attachments/928374.json"
},
"name": "Brand 1",
"signature_template": "{{agent.signature}}",
"subdomain": "hello-world",
"ticket_form_ids": [
360000660811
],
"updated_at": "2019-08-06T02:43:40Z",
"url": "https://company.zendesk.com/api/v2/brands/360002783572.json"
}
}
Update a Brand
PUT /api/v2/brands/{brand_id}
Returns an updated brand.
Allowed for
- Admins
Updating a Brand's Image
A brand image can be updated by uploading a local file using the update brand endpoint. See the Using curl sections below for more information.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
brand_id | integer | Path | true | The ID of the brand |
Example Body
{
"brand": {
"active": true,
"host_mapping": "brand1.com",
"name": "Brand 1",
"subdomain": "Brand1"
}
}
Using cURL
Update brand details with JSON.
curl https://{subdomain}.zendesk.com/api/v2/brands/{brand_id}.json \
-H "Content-Type: application/json" -X PUT \
-d '{"brand": {"name": "Brand 1", "subdomain": "brand1", "host_mapping": "brand1.com", "active": true}}' \
-v -u {email_address}:{password}}
Using cURL
Update brand image by uploading a local image file.
curl -v -u {email_address}:{password} -X PUT \
-F "brand[logo][uploaded_data][email protected]/path/to/image/image.jpg" \
https://{subdomain}.zendesk.com/api/v2/brands/{brand_id}.json
Example Response
Status 200 OK
{
"brand": {
"active": true,
"brand_url": "https://brand1.zendesk.com",
"created_at": "2019-08-06T02:43:39Z",
"default": true,
"has_help_center": true,
"help_center_state": "enabled",
"host_mapping": "brand1.com",
"id": 360002783572,
"is_deleted": false,
"logo": {
"content_type": "image/png",
"content_url": "https://company.zendesk.com/logos/brand1_logo.png",
"file_name": "brand1_logo.png",
"id": 928374,
"mapped_content_url": "https://company.com/logos/brand1_logo.png",
"size": 166144,
"thumbnails": [
{
"content_type": "image/png",
"content_url": "https://company.zendesk.com/photos/brand1_logo_thumb.png",
"file_name": "brand1_logo_thumb.png",
"id": 928375,
"mapped_content_url": "https://company.com/photos/brand1_logo_thumb.png",
"size": 58298,
"url": "https://company.zendesk.com/api/v2/attachments/928375.json"
},
{
"content_type": "image/png",
"content_url": "https://company.zendesk.com/photos/brand1_logo_small.png",
"file_name": "brand1_logo_small.png",
"id": 928376,
"mapped_content_url": "https://company.com/photos/brand1_logo_small.png",
"size": 58298,
"url": "https://company.zendesk.com/api/v2/attachments/928376.json"
}
],
"url": "https://company.zendesk.com/api/v2/attachments/928374.json"
},
"name": "Brand 1",
"signature_template": "{{agent.signature}}",
"subdomain": "hello-world",
"ticket_form_ids": [
360000660811
],
"updated_at": "2019-08-06T02:43:40Z",
"url": "https://company.zendesk.com/api/v2/brands/360002783572.json"
}
}
Delete a Brand
DELETE /api/v2/brands/{brand_id}
Deletes a brand.
Allowed for
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
brand_id | integer | Path | true | The ID of the brand |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/brands/{brand_id}.json \
-X DELETE -v -u {email_address}:{password}
Example Response
Status 204 No Content
Check Host Mapping Validity
GET /api/v2/brands/check_host_mapping?host_mapping={host_mapping}&subdomain={subdomain}
Returns a JSON object determining whether a host mapping is valid for a given subdomain.
Allowed for
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
host_mapping | string | Query | true | The hostmapping to a brand, if any (only admins view this key) |
subdomain | string | Query | true | Subdomain for a given Zendesk account address |
Using cURL
curl 'https://{subdomain}.zendesk.com/api/v2/brands/check_host_mapping.json?host_mapping={host_mapping}&subdomain={subdomain}' \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"cname": "bar.zendesk.com",
"is_valid": true
}
Check Host Mapping Validity for an Existing Brand
GET /api/v2/brands/{brand_id}/check_host_mapping
Returns a JSON object determining whether a host mapping is valid for the given brand.
Allowed for
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
brand_id | integer | Path | true | The ID of the brand |
Using cURL
curl "https://{subdomain}.zendesk.com/api/v2/brands/{brand_id}/check_host_mapping.json" \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"cname": "bar.zendesk.com",
"is_valid": true
}