JSON Format

Account Settings are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
active_features object false false The active features for an account. See Active Features
agents object false false Configuration for the agent workspace. See Agents
api object false false API configuration options. See API
apps object false false Apps configuration options. See Apps
billing object false false Billing configuration options. See Billing
branding object false false Branding settings. See Branding
brands object false false Brand settings. See Brands
cdn object false false CDN settings
chat object false false Zendesk Chat settings. See Chat
cross_sell object false false Cross Sell settings
gooddata_advanced_analytics object false false GoodData settings, used for insights. Legacy configuration prior to Zendesk Explore. See GoodData Advanced Analytics
google_apps object false false Google Apps configuration. See G Suite
groups object false false Group configuration
limits object false false Account limits configuration. See Limits
localization object false false Internationalization configuration settings. See Localization
lotus object false false Support UI settings. See Lotus
metrics object false false Account metrics settings. See Metrics
onboarding object false false Onboarding settings
rule object false false Rules settings for triggers, macros, views, and automations. See Rules
screencast object false false Screencast settings
statistics object false false Account statistics settings. See Statistics
ticket_form object false false Ticket form settings. See Ticket Form
ticket_sharing_partners object false false Ticket sharing partners settings. See Ticket Sharing Partners
tickets object false false Ticket settings. See Tickets
twitter object false false Twitter settings. See Twitter
user object false false User settings. See Users
voice object false false Zendesk Talk settings. See Voice

You can access the following data describing the settings of an account. You can update the settings marked as not read-only.

Branding

Name Type Read-only Comment
header_color string no HEX of the header color
page_background_color string no HEX of the page background color
tab_background_color string no HEX of tab background color
text_color string no HEX of the text color, usually matched to contrast well with header_color
header_logo_url string yes The URL for the custom header logo
favicon_url string yes The URL for the custom favicon

Apps

Name Type Read-only Comment
use boolean yes The account can use apps
create_private boolean yes The account can create private apps

Tickets

Name Type Read-only Comment
comments_public_by_default boolean no Comments from agents are public by default
is_first_comment_private_enabled boolean no Allow first comment on tickets to be private
list_newest_comments_first boolean no When viewing a ticket, show the newest comments and events first
collaboration boolean yes CCs may be added to a ticket
private_attachments boolean no Users must sign in to access attachments
email_attachments boolean no Attachments should be sent as real attachments when under the size limit
agent_collision boolean yes Clients should provide an indicator when a ticket is being viewed by ther agent
list_empty_views boolean no Clients should display views with no matching tickets in menus
maximum_personal_views_to_list number yes Maximum number of personal views clients should display in menus
tagging boolean no Tickets may be tagged
markdown_ticket_comments boolean no Whether agent comments should be processed with Markdown
emoji_autocompletion boolean no Whether agent comments should allow for Emoji rendering
agent_ticket_deletion boolean no Whether agents can delete tickets

Agents

Name Type Read-only Comment
agent_workspace boolean no Toggles the Agent Workspace experience
aw_self_serve_migration_enabled boolean yes Toggles the AW Self-serve migration control setting

Chat

Name Type Read-only Comment
enabled boolean yes Chat is enabled
maximum_requests number yes The maximum number of chat requests an agent may handle at one time
welcome_message string yes The message automatically sent to end-users when they begin chatting with agent

Twitter

Name Type Read-only Comment
shorten_url string yes Possible values: 'always', 'optional', 'never'

G Suite

Name Type Read-only Comment
has_google_apps boolean yes
has_google_apps_admin boolean no Account has at least one G Suite admin

Voice

Name Type Read-only Comment
enabled boolean yes Voice is enabled
maintenance boolean yes
logging boolean yes
outbound_enabled boolean yes
agent_confirmation_when_forwarding boolean yes
agent_wrap_up_after_calls boolean yes
maximum_queue_size number yes
maximum_queue_wait_time number yes
only_during_business_hours boolean yes
recordings_public boolean yes
uk_mobile_forwarding boolean yes

Users

Name Type Read-only Comment
tagging boolean no Users may be tagged
time_zone_selection boolean yes Whether user can view time zone for profile
language_selection boolean yes Whether to display language drop down for a user
agent_created_welcome_emails boolean no Whether a user created by an agent receives a welcome email
end_user_phone_number_validation boolean no Whether a user's phone number is validated
have_gravatars_enabled boolean no Whether user gravatars are displayed in the UI

GoodData Advanced Analytics

Name Type Read-only Comment
enabled boolean yes GoodData Advanced Analytics is enabled

Brands

Name Type Read-only Comment
default_brand_id number no The id of the brand that is assigned to tickets by default
require_brand_on_new_tickets boolean no Require agents to select a brand before saving tickets

Statistics

Name Type Read-only Comment
forum boolean yes Allow users to view forum statistics
search boolean yes Allow users to view search statistics

Billing

Name Type Read-only Comment
backend string yes Backend Billing system either 'internal' or 'zuora'

Active Features

Name Type Read-only Comment
on_hold_status boolean yes Account can use status hold
user_tagging boolean no Enable user tags
ticket_tagging boolean no Allow tagging tickets
topic_suggestion boolean yes Allow topic suggestions in tickets
voice boolean yes Voice support
facebook_login boolean yes
google_login boolean yes
twitter_login boolean yes
forum_analytics boolean yes Forum and search analytics
business_hours boolean no
agent_forwarding boolean yes
chat boolean yes
chat_about_my_ticket boolean yes
customer_satisfaction boolean no
satisfaction_prediction boolean no
csat_reason_code boolean yes
markdown boolean yes Markdown in ticket comments
bcc_archiving boolean yes Account has a bcc_archive_address set
allow_ccs boolean yes Allow CCs on tickets
advanced_analytics boolean yes
insights boolean yes
explore boolean yes Has account plan setting 'explore'
good_data_and_explore boolean yes Has account plan setting 'good_data_and_explore'
explore_on_support_pro_plan boolean yes Allowed to show explore role controls
sandbox boolean yes Account has a sandbox
suspended_ticket_notification boolean yes
twitter boolean yes Account monitors at least one Twitter handle
facebook boolean yes Account is actively linked to at least one Facebook page
feedback_tabs boolean yes Feedback tab has been configured before
dynamic_contents boolean yes Account has at least one dynamic content
light_agents boolean yes Account has at least one light agent
is_abusive boolean yes Account exceeded trial limits
rich_content_in_email boolean yes Account supports incoming HTML email
fallback_composer boolean yes Fallback composer for Asian languages

API

Name Type Read-only Comment
accepted_api_agreement boolean no Account has accepted the API agreement
api_password_access boolean no Allow the account to use the API with username/password
api_token_access boolean no Allow the account to use the API with API tokens

Ticket Form

Name Type Read-only Comment
ticket_forms_instructions string no

Lotus

Name Type Read-only Comment
prefer_lotus boolean yes Prefers the current version of Zendesk Support rather than Zendesk Classic

Ticket Sharing Partners

Name Type Read-only Comment
support_addresses object yes Array of support addresses for all accepted sharing agreement accounts

Rules

Name Type Read-only Comment
macro_most_used boolean no Display the most-used macros in the Apply macro list. Defaults to true
macro_order string no Default macro display order. Possible values are 'alphabetical' or 'position'
skill_based_filtered_views object no Array of view ids

Limits

Name Type Read-only Comment
attachment_size number yes The maximum ticket attachment file size (in bytes)

Metrics

Name Type Read-only Comment
account_size string yes An account size category computed from the number of billable agents

Localization

Name Type Read-only Comment
locale_ids array no Array of locale IDs enabled for the account. See Locales for possible values

Example

{  "active_features": {    "advanced_analytics": false,    "agent_forwarding": false,    "allow_ccs": true,    "allow_email_template_customization": true,    "automatic_answers": false,    "bcc_archiving": false,    "benchmark_opt_out": false,    "business_hours": false,    "chat": false,    "chat_about_my_ticket": false,    "csat_reason_code": false,    "custom_dkim_domain": true,    "customer_context_as_default": false,    "customer_satisfaction": false,    "dynamic_contents": false,    "explore": true,    "explore_on_support_ent_plan": false,    "explore_on_support_pro_plan": false,    "facebook": false,    "facebook_login": false,    "fallback_composer": false,    "forum_analytics": true,    "good_data_and_explore": false,    "google_login": false,    "insights": false,    "is_abusive": false,    "light_agents": false,    "markdown": false,    "on_hold_status": false,    "rich_content_in_emails": true,    "sandbox": false,    "satisfaction_prediction": false,    "screencasts": false,    "suspended_ticket_notification": false,    "ticket_forms": true,    "ticket_tagging": true,    "topic_suggestion": false,    "twitter": true,    "twitter_login": false,    "user_org_fields": true,    "user_tagging": true,    "voice": true  },  "agents": {    "agent_workspace": false,    "aw_self_serve_migration_enabled": true,    "focus_mode": false  },  "api": {    "accepted_api_agreement": true,    "api_password_access": "true",    "api_token_access": "true"  },  "apps": {    "create_private": true,    "create_public": false,    "use": true  },  "billing": {    "backend": "zuora"  },  "branding": {    "favicon_url": null,    "header_color": "78A300",    "header_logo_url": null,    "page_background_color": "333333",    "tab_background_color": "7FA239",    "text_color": "FFFFFF"  },  "brands": {    "default_brand_id": 1873,    "require_brand_on_new_tickets": false  },  "cdn": {    "cdn_provider": "default",    "fallback_cdn_provider": "cloudfront",    "hosts": [      {        "name": "default",        "url": "https://p18.zdassets.com"      },      {        "name": "cloudfront",        "url": "https://d2y9oszrd3dhjh.cloudfront.net"      }    ]  },  "chat": {    "available": true,    "enabled": false,    "integrated": true,    "maximum_request_count": 1,    "welcome_message": "Hi there. How can I help today?"  },  "cross_sell": {    "show_chat_tooltip": true,    "xsell_source": null  },  "gooddata_advanced_analytics": {    "enabled": true  },  "google_apps": {    "has_google_apps": false,    "has_google_apps_admin": false  },  "groups": {    "check_group_name_uniqueness": true  },  "limits": {    "attachment_size": 52428800  },  "localization": {    "locale_ids": [      1042    ]  },  "lotus": {    "pod_id": 999,    "prefer_lotus": true,    "reporting": true  },  "metrics": {    "account_size": "100-399"  },  "onboarding": {    "checklist_onboarding_version": 2,    "onboarding_segments": null,    "product_sign_up": null  },  "rule": {    "macro_most_used": true,    "macro_order": "alphabetical",    "skill_based_filtered_views": [],    "using_skill_based_routing": false  },  "screencast": {    "enabled_for_tickets": false,    "host": null,    "tickets_recorder_id": null  },  "statistics": {    "forum": true,    "rule_usage": true,    "search": true  },  "ticket_form": {    "raw_ticket_forms_instructions": "Please choose your issue below",    "ticket_forms_instructions": "Please choose your issue below"  },  "ticket_sharing_partners": {    "support_addresses": [      "[email protected]"    ]  },  "tickets": {    "accepted_new_collaboration_tos": false,    "agent_collision": true,    "agent_ticket_deletion": false,    "allow_group_reset": true,    "assign_tickets_upon_solve": true,    "auto_updated_ccs_followers_rules": false,    "collaboration": true,    "comments_public_by_default": true,    "email_attachments": false,    "emoji_autocompletion": true,    "follower_and_email_cc_collaborations": false,    "is_first_comment_private_enabled": true,    "light_agent_email_ccs_allowed": false,    "list_empty_views": true,    "list_newest_comments_first": true,    "markdown_ticket_comments": false,    "maximum_personal_views_to_list": 8,    "private_attachments": false,    "rich_text_comments": true,    "status_hold": false,    "tagging": true,    "using_skill_based_routing": false  },  "twitter": {    "shorten_url": "optional"  },  "user": {    "agent_created_welcome_emails": true,    "end_user_phone_number_validation": false,    "have_gravatars_enabled": true,    "language_selection": true,    "multiple_organizations": false,    "tagging": true,    "time_zone_selection": true  },  "voice": {    "agent_confirmation_when_forwarding": true,    "agent_wrap_up_after_calls": true,    "enabled": true,    "logging": true,    "maximum_queue_size": 5,    "maximum_queue_wait_time": 1,    "only_during_business_hours": false,    "outbound_enabled": true,    "recordings_public": true,    "uk_mobile_forwarding": true  }}

Show Settings

  • GET /api/v2/account/settings

Shows the settings that are available for the account.

Allowed For

  • Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/account/settings.json \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "settings": {    "active_features": {      "advanced_analytics": false,      "agent_forwarding": false,      "allow_ccs": true,      "allow_email_template_customization": true,      "automatic_answers": false,      "bcc_archiving": false,      "benchmark_opt_out": false,      "business_hours": false,      "chat": false,      "chat_about_my_ticket": false,      "csat_reason_code": false,      "custom_dkim_domain": true,      "customer_context_as_default": false,      "customer_satisfaction": false,      "dynamic_contents": false,      "explore": true,      "explore_on_support_ent_plan": false,      "explore_on_support_pro_plan": false,      "facebook": false,      "facebook_login": false,      "fallback_composer": false,      "forum_analytics": true,      "good_data_and_explore": false,      "google_login": false,      "insights": false,      "is_abusive": false,      "light_agents": false,      "markdown": false,      "on_hold_status": false,      "rich_content_in_emails": true,      "sandbox": false,      "satisfaction_prediction": false,      "screencasts": false,      "suspended_ticket_notification": false,      "ticket_forms": true,      "ticket_tagging": true,      "topic_suggestion": false,      "twitter": true,      "twitter_login": false,      "user_org_fields": true,      "user_tagging": true,      "voice": true    },    "agents": {      "agent_workspace": false,      "aw_self_serve_migration_enabled": true,      "focus_mode": false    },    "api": {      "accepted_api_agreement": true,      "api_password_access": "true",      "api_token_access": "true"    },    "apps": {      "create_private": true,      "create_public": false,      "use": true    },    "billing": {      "backend": "zuora"    },    "branding": {      "favicon_url": null,      "header_color": "78A300",      "header_logo_url": null,      "page_background_color": "333333",      "tab_background_color": "7FA239",      "text_color": "FFFFFF"    },    "brands": {      "default_brand_id": 1873,      "require_brand_on_new_tickets": false    },    "cdn": {      "cdn_provider": "default",      "fallback_cdn_provider": "cloudfront",      "hosts": [        {          "name": "default",          "url": "https://p18.zdassets.com"        },        {          "name": "cloudfront",          "url": "https://d2y9oszrd3dhjh.cloudfront.net"        }      ]    },    "chat": {      "available": true,      "enabled": false,      "integrated": true,      "maximum_request_count": 1,      "welcome_message": "Hi there. How can I help today?"    },    "cross_sell": {      "show_chat_tooltip": true,      "xsell_source": null    },    "gooddata_advanced_analytics": {      "enabled": true    },    "google_apps": {      "has_google_apps": false,      "has_google_apps_admin": false    },    "groups": {      "check_group_name_uniqueness": true    },    "limits": {      "attachment_size": 52428800    },    "localization": {      "locale_ids": [        1042      ]    },    "lotus": {      "pod_id": 999,      "prefer_lotus": true,      "reporting": true    },    "metrics": {      "account_size": "100-399"    },    "onboarding": {      "checklist_onboarding_version": 2,      "onboarding_segments": null,      "product_sign_up": null    },    "rule": {      "macro_most_used": true,      "macro_order": "alphabetical",      "skill_based_filtered_views": [],      "using_skill_based_routing": false    },    "screencast": {      "enabled_for_tickets": false,      "host": null,      "tickets_recorder_id": null    },    "statistics": {      "forum": true,      "rule_usage": true,      "search": true    },    "ticket_form": {      "raw_ticket_forms_instructions": "Please choose your issue below",      "ticket_forms_instructions": "Please choose your issue below"    },    "ticket_sharing_partners": {      "support_addresses": [        "[email protected]"      ]    },    "tickets": {      "accepted_new_collaboration_tos": false,      "agent_collision": true,      "agent_ticket_deletion": false,      "allow_group_reset": true,      "assign_tickets_upon_solve": true,      "auto_updated_ccs_followers_rules": false,      "collaboration": true,      "comments_public_by_default": true,      "email_attachments": false,      "emoji_autocompletion": true,      "follower_and_email_cc_collaborations": false,      "is_first_comment_private_enabled": true,      "light_agent_email_ccs_allowed": false,      "list_empty_views": true,      "list_newest_comments_first": true,      "markdown_ticket_comments": false,      "maximum_personal_views_to_list": 8,      "private_attachments": false,      "rich_text_comments": true,      "status_hold": false,      "tagging": true,      "using_skill_based_routing": false    },    "twitter": {      "shorten_url": "optional"    },    "user": {      "agent_created_welcome_emails": true,      "end_user_phone_number_validation": false,      "have_gravatars_enabled": true,      "language_selection": true,      "multiple_organizations": false,      "tagging": true,      "time_zone_selection": true    },    "voice": {      "agent_confirmation_when_forwarding": true,      "agent_wrap_up_after_calls": true,      "enabled": true,      "logging": true,      "maximum_queue_size": 5,      "maximum_queue_wait_time": 1,      "only_during_business_hours": false,      "outbound_enabled": true,      "recordings_public": true,      "uk_mobile_forwarding": true    }  }}

Update Account Settings

  • PUT /api/v2/account/settings

Updates settings for the account. See JSON Format above for the settings you can update.

Allowed For

  • Admins

Using curl

curl https://{subdomain}.zendesk.com/api/v2/account/settings.json \  -H "Content-Type: application/json" -X PUT \  -d '{ "settings": { "active_features": { "customer_satisfaction": false }}}' \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "settings": {    "active_features": {      "advanced_analytics": false,      "agent_forwarding": false,      "allow_ccs": true,      "allow_email_template_customization": true,      "automatic_answers": false,      "bcc_archiving": false,      "benchmark_opt_out": false,      "business_hours": false,      "chat": false,      "chat_about_my_ticket": false,      "csat_reason_code": false,      "custom_dkim_domain": true,      "customer_context_as_default": false,      "customer_satisfaction": false,      "dynamic_contents": false,      "explore": true,      "explore_on_support_ent_plan": false,      "explore_on_support_pro_plan": false,      "facebook": false,      "facebook_login": false,      "fallback_composer": false,      "forum_analytics": true,      "good_data_and_explore": false,      "google_login": false,      "insights": false,      "is_abusive": false,      "light_agents": false,      "markdown": false,      "on_hold_status": false,      "rich_content_in_emails": true,      "sandbox": false,      "satisfaction_prediction": false,      "screencasts": false,      "suspended_ticket_notification": false,      "ticket_forms": true,      "ticket_tagging": true,      "topic_suggestion": false,      "twitter": true,      "twitter_login": false,      "user_org_fields": true,      "user_tagging": true,      "voice": true    },    "agents": {      "agent_workspace": false,      "aw_self_serve_migration_enabled": true,      "focus_mode": false    },    "api": {      "accepted_api_agreement": true,      "api_password_access": "true",      "api_token_access": "true"    },    "apps": {      "create_private": true,      "create_public": false,      "use": true    },    "billing": {      "backend": "zuora"    },    "branding": {      "favicon_url": null,      "header_color": "78A300",      "header_logo_url": null,      "page_background_color": "333333",      "tab_background_color": "7FA239",      "text_color": "FFFFFF"    },    "brands": {      "default_brand_id": 1873,      "require_brand_on_new_tickets": false    },    "cdn": {      "cdn_provider": "default",      "fallback_cdn_provider": "cloudfront",      "hosts": [        {          "name": "default",          "url": "https://p18.zdassets.com"        },        {          "name": "cloudfront",          "url": "https://d2y9oszrd3dhjh.cloudfront.net"        }      ]    },    "chat": {      "available": true,      "enabled": false,      "integrated": true,      "maximum_request_count": 1,      "welcome_message": "Hi there. How can I help today?"    },    "cross_sell": {      "show_chat_tooltip": true,      "xsell_source": null    },    "gooddata_advanced_analytics": {      "enabled": true    },    "google_apps": {      "has_google_apps": false,      "has_google_apps_admin": false    },    "groups": {      "check_group_name_uniqueness": true    },    "limits": {      "attachment_size": 52428800    },    "localization": {      "locale_ids": [        1042      ]    },    "lotus": {      "pod_id": 999,      "prefer_lotus": true,      "reporting": true    },    "metrics": {      "account_size": "100-399"    },    "onboarding": {      "checklist_onboarding_version": 2,      "onboarding_segments": null,      "product_sign_up": null    },    "rule": {      "macro_most_used": true,      "macro_order": "alphabetical",      "skill_based_filtered_views": [],      "using_skill_based_routing": false    },    "screencast": {      "enabled_for_tickets": false,      "host": null,      "tickets_recorder_id": null    },    "statistics": {      "forum": true,      "rule_usage": true,      "search": true    },    "ticket_form": {      "raw_ticket_forms_instructions": "Please choose your issue below",      "ticket_forms_instructions": "Please choose your issue below"    },    "ticket_sharing_partners": {      "support_addresses": [        "[email protected]"      ]    },    "tickets": {      "accepted_new_collaboration_tos": false,      "agent_collision": true,      "agent_ticket_deletion": false,      "allow_group_reset": true,      "assign_tickets_upon_solve": true,      "auto_updated_ccs_followers_rules": false,      "collaboration": true,      "comments_public_by_default": true,      "email_attachments": false,      "emoji_autocompletion": true,      "follower_and_email_cc_collaborations": false,      "is_first_comment_private_enabled": true,      "light_agent_email_ccs_allowed": false,      "list_empty_views": true,      "list_newest_comments_first": true,      "markdown_ticket_comments": false,      "maximum_personal_views_to_list": 8,      "private_attachments": false,      "rich_text_comments": true,      "status_hold": false,      "tagging": true,      "using_skill_based_routing": false    },    "twitter": {      "shorten_url": "optional"    },    "user": {      "agent_created_welcome_emails": true,      "end_user_phone_number_validation": false,      "have_gravatars_enabled": true,      "language_selection": true,      "multiple_organizations": false,      "tagging": true,      "time_zone_selection": true    },    "voice": {      "agent_confirmation_when_forwarding": true,      "agent_wrap_up_after_calls": true,      "enabled": true,      "logging": true,      "maximum_queue_size": 5,      "maximum_queue_wait_time": 1,      "only_during_business_hours": false,      "outbound_enabled": true,      "recordings_public": true,      "uk_mobile_forwarding": true    }  }}