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 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
}

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"
  }
}

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
}

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"
  }
}

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 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
}