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
}