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:

NameTypeRead-onlyMandatoryDescription
activebooleanfalsefalseIf the brand is set as active
brand_urlstringfalsefalseThe url of the brand
created_atstringtruefalseThe time the brand was created
defaultbooleanfalsefalseIs the brand the default brand for this account
has_help_centerbooleanfalsefalseIf the brand has a Help Center
help_center_statestringtruefalseThe state of the Help Center. Allowed values are "enabled", "disabled", or "restricted".
host_mappingstringfalsefalseThe hostmapping to this brand, if any. Only admins view this property.
idintegertruefalseThe ID automatically assigned when the brand is created
is_deletedbooleanfalsefalseIf the brand object is deleted or not
logoobjectfalsefalseA file represented as an Attachment object
namestringfalsetrueThe name of the brand
signature_templatestringfalsefalseThe signature template for a brand
subdomainstringfalsetrueThe subdomain of the brand
ticket_form_idsarraytruefalseThe ids of ticket forms that are available for use by a brand
updated_atstringtruefalseThe time of the last update of the brand
urlstringtruefalseThe 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

Pagination

  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/v2/brands.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/brands"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/brands")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/brands',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/brands"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/brands")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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

NameTypeInRequiredDescription
brand_idintegerPathtrueThe ID of the brand

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/v2/brands/{brand_id}.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/brands/360002783572"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/brands/360002783572")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/brands/360002783572',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/brands/360002783572"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/brands/360002783572")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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"  }}

Code Samples

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}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://example.zendesk.com/api/v2/brands"	method := "POST"	payload := strings.NewReader(`{  "brand": {    "name": "Brand 1",    "subdomain": "Brand1"  }}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/brands")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"brand\": {    \"name\": \"Brand 1\",    \"subdomain\": \"Brand1\"  }}""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "brand": {    "name": "Brand 1",    "subdomain": "Brand1"  }});
var config = {  method: 'POST',  url: 'https://example.zendesk.com/api/v2/brands',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport json
url = "https://example.zendesk.com/api/v2/brands"
payload = json.loads("""{  "brand": {    "name": "Brand 1",    "subdomain": "Brand1"  }}""")headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	auth=('<username>', '<password>'),	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/brands")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.body = %q({  "brand": {    "name": "Brand 1",    "subdomain": "Brand1"  }})request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

201 Created
// 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

NameTypeInRequiredDescription
brand_idintegerPathtrueThe ID of the brand

Example body

{  "brand": {    "active": true,    "host_mapping": "brand1.com",    "name": "Brand 1",    "subdomain": "Brand1"  }}

Code Samples

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}/token:{api_token}}
cURL

Update brand image by uploading a local image file.

curl -v -u {email_address}/token:{api_token} -X PUT \  -F "brand[logo][uploaded_data]=@/path/to/image/image.jpg" \  https://{subdomain}.zendesk.com/api/v2/brands/{brand_id}.json
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://example.zendesk.com/api/v2/brands/360002783572"	method := "PUT"	payload := strings.NewReader(`{  "brand": {    "active": true,    "host_mapping": "brand1.com",    "name": "Brand 1",    "subdomain": "Brand1"  }}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/brands/360002783572")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"brand\": {    \"active\": true,    \"host_mapping\": \"brand1.com\",    \"name\": \"Brand 1\",    \"subdomain\": \"Brand1\"  }}""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "brand": {    "active": true,    "host_mapping": "brand1.com",    "name": "Brand 1",    "subdomain": "Brand1"  }});
var config = {  method: 'PUT',  url: 'https://example.zendesk.com/api/v2/brands/360002783572',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport json
url = "https://example.zendesk.com/api/v2/brands/360002783572"
payload = json.loads("""{  "brand": {    "active": true,    "host_mapping": "brand1.com",    "name": "Brand 1",    "subdomain": "Brand1"  }}""")headers = {	"Content-Type": "application/json",}
response = requests.request(	"PUT",	url,	auth=('<username>', '<password>'),	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/brands/360002783572")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")request.body = %q({  "brand": {    "active": true,    "host_mapping": "brand1.com",    "name": "Brand 1",    "subdomain": "Brand1"  }})request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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

NameTypeInRequiredDescription
brand_idintegerPathtrueThe ID of the brand

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/v2/brands/{brand_id}.json \  -X DELETE -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/brands/360002783572"	method := "DELETE"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/brands/360002783572")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("DELETE", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'DELETE',  url: 'https://example.zendesk.com/api/v2/brands/360002783572',  headers: {	'Content-Type': 'application/json',	'Authorization':<