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}