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.

JSON Format

Brands are represented as JSON objects which have the following keys:

Name Type Read-only Mandatory Comment
url string yes no The API url of this brand
id integer yes no Automatically assigned when the brand is created
name string no yes The name of the brand
brand_url string no no The url of the brand
has_help_center boolean no no If the brand has a Help Center
help_center_state string yes no The state of the Help Center: enabled, disabled, or restricted
active boolean no no If the brand is set as active
default boolean no no Is the brand the default brand for this account
logo Attachment no no Logo image for this brand
ticket_form_ids array yes no The ids of ticket forms that are available for use by a brand
created_at date yes no The time the brand was created
updated_at date yes no The time of the last update of the brand
subdomain string no yes The subdomain of the brand
host_mapping string no no The hostmapping to this brand, if any (only admins view this key)
signature_template string no no The signature template for a brand
Example
{
  "id":                    47,
  "url":                   "https://company.zendesk.com/api/v2/brands/47.json",
  "name":                  "Brand 1",
  "brand_url":             "https://brand1.com",
  "has_help_center":       true,
  "help_center_state":     "enabled",
  "active":                true,
  "default":               true,
  "logo": {
    "url":                   "https://company.zendesk.com/api/v2/attachments/928374.json",
    "id":                    928374,
    "file_name":             "brand1_logo.png",
    "content_url":           "https://company.zendesk.com/logos/brand1_logo.png",
    "mapped_content_url":    "https://company.com/logos/brand1_logo.png",
    "content_type":          "image/png",
    "size":                  166144,
    "thumbnails": [
      {
        "url":                 "https://company.zendesk.com/api/v2/attachments/928375.json",
        "id":                  928375,
        "file_name":           "brand1_logo_thumb.png",
        "content_url":         "https://company.zendesk.com/photos/brand1_logo_thumb.png",
        "mapped_content_url":  "https://company.com/photos/brand1_logo_thumb.png",
        "content_type":        "image/png",
        "size":                58298,
      },
      {
        "url":                 "https://company.zendesk.com/api/v2/attachments/928376.json",
        "id":                  928376,
        "file_name":           "brand1_logo_small.png",
        "content_url":         "https://company.zendesk.com/photos/brand1_logo_small.png",
        "mapped_content_url":  "https://company.com/photos/brand1_logo_small.png",
        "content_type":        "image/png",
        "size":                58298,
      }
    ]
  },
  "ticket_form_ids":       [ 47, 33 22 ]
  "created_at":            "2012-04-02t22:55:29z",
  "updated_at":            "2012-04-02t22:55:29z",
  "subdomain":             "brand1",
  "host_mapping":          "brand1.com",
  "signature_template":    "{{agent.signature}}"
}

List Brands

GET /api/v2/brands.json

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": [
    {
      "id":                    47,
      "url":                   "https://company.zendesk.com/api/v2/brands/47.json",
      "name":                  "Brand 1",
      "brand_url":             "https://brand1.zendesk.com",
      ...
    },
    {
      "id":                    42,
      "url":                   "https://company.zendesk.com/api/v2/brands/42.json",
      "name":                  "Brand 42",
      "brand_url":             "https://brand42.zendesk.com",
      ...
    }
  ]
}

Show a Brand

GET /api/v2/brands/{id}.json

Returns a brand for your account.

Allowed for
  • Admins, Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/brands/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "brand": {
    "id":   47,
    "url":  "https://company.zendesk.com/api/v2/brands/47.json",
    "name": "Brand 1",
    ...
  }
}

Create Brand

POST /api/v2/brands.json

Allowed for
  • Admins
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
Location: https://{subdomain}.zendesk.com/api/v2/brands/{id}.json

{
  "brand": {
    "id":        47,
    "url":       "https://company.zendesk.com/api/v2/brands/47.json",
    "name":      "Brand 1",
    "brand_url": "https://brand1.zendesk.com",
    "subdomain": "brand1",
    ...
  }
}

Update a Brand

PUT /api/v2/brands/{id}.json

Returns an updated brand.

Allowed for
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/brands/{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}
Example Response
Status: 200 OK

{
  "brand": {
    "id":                    47,
    "url":                   "https://company.zendesk.com/api/v2/brands/47.json",
    "name":                  "Brand 1",
    "brand_url":             "https://brand1.com",
    "subdomain":             "brand1",
    "host_mapping":          "brand1.com"
    ...
  }
}

Delete a Brand

DELETE /api/v2/brands/{id}.json

Deletes a brand.

Allowed for
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/brands/{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.json?host_mapping={host_mapping}&subdomain={subdomain}

Returns a JSON object determining whether a host mapping is valid for a given subdomain.

Allowed for
  • Admins
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

{
  "is_valid": true,
  "cname": "bar.zendesk.com"
}
Status: 200 OK

{
  "is_valid": false,
  "reason": "wrong_cname",
  "cname": "google.com",
  "expected_cnames": ["bar.zendesk.com", "bar.ssl.zendesk.com"]
}
Status: 200 OK

{
  "is_valid": false,
  "reason": "not_a_cname",
  "expected_cnames": ["bar.zendesk.com", "bar.ssl.zendesk.com"]
}

Check host mapping validity for an existing brand

GET /api/v2/brands/{id}/check_host_mapping.json

Returns a JSON object determining whether a host mapping is valid for the given brand.

Allowed for
  • Admins
Using curl
curl 'https://{subdomain}.zendesk.com/api/v2/brands/{id}/check_host_mapping.json' \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "is_valid": true,
  "cname": "bar.zendesk.com"
}
Status: 200 OK

{
  "is_valid": false,
  "reason": "wrong_cname",
  "cname": "google.com",
  "expected_cnames": ["bar.zendesk.com", "bar.ssl.zendesk.com"]
}
Status: 200 OK

{
  "is_valid": false,
  "reason": "not_a_cname",
  "expected_cnames": ["bar.zendesk.com", "bar.ssl.zendesk.com"]
}

Updating a Brand's Image

A brand image can be updated by uploading a local file using the update brand endpoint.

Example Request
curl -v -u {email_address}:{password} -X PUT \
  -F "brand[photo][uploaded_data]=@/path/to/image/image.jpg" \
  https://{subdomain}.zendesk.com/api/v2/brands/{id}.json
Example Response
Status: 200 OK

{
  "brand": {
    "id":   47,
    "url":  "https://company.zendesk.com/api/v2/brands/47.json",
    "name": "Brand 1",
    "logo": {
      "url":       "https://company.zendesk.com/api/v2/attachments/928374.json",
      "id":        928374,
      "file_name": "image.jpg",
      ...
    }
  }
}

Updating the Default Brand

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.

Example Request
curl https://{subdomain}.zendesk.com/api/v2/brands.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{ "settings": { "brands": { "default_brand_id": 47 }}}' \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

"settings": {
  ...
  "brands": {
    "default_brand_id": 47
  }
}