Custom Agent Roles

Zendesk Support accounts on the Enterprise plan or above can provide more granular access to their agents by defining custom agent roles. For more information, see Creating custom roles and assigning agents in the Support Help Center.

JSON Format

Custom Agent Roles are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
configuration object false false Configuration settings for the role. See Configuration
created_at string true false The time the record was created
description string false false A description of the role
id integer true false Automatically assigned on creation
name string false true Name of the custom role
role_type integer true true The value 0
updated_at string true false The time the record was last updated
Configuration

The configuration object has the following properties, which are all optional.

Name Type Read-only Comment
chat_access boolean yes Whether or not the agent has access to Chat
end_user_list_access string no Whether or not the agent can view lists of user profiles. Allowed values: "full", "none"
end_user_profile_access string no What the agent can do with end-user profiles. Allowed values: "edit", "edit-within-org", "full", "readonly"
explore_access string no Allowed values: "edit", "full", "none", "readonly"
forum_access string no The kind of access the agent has to Guide. Allowed values: "edit-topics", "full", "readonly"
forum_access_restricted_content boolean no
group_access boolean yes Whether or not the agent can add or modify groups
light_agent boolean yes
macro_access string no What the agent can do with macros. Allowed values: "full", "manage-group", "manage-personal", "readonly"
manage_business_rules boolean no Whether or not the agent can manage business rules
manage_dynamic_content boolean no Whether or not the agent can access dynamic content
manage_extensions_and_channels boolean no Whether or not the agent can manage channels and extensions
manage_facebook boolean no Whether or not the agent can manage facebook pages
moderate_forums boolean yes
organization_editing boolean no Whether or not the agent can add or modify organizations
organization_notes_editing boolean yes Whether or not the agent can add or modify organization notes
report_access string no What the agent can do with reports. Allowed values: "full", "none", "readonly"
ticket_access string no What kind of tickets the agent can access. Allowed values: "all", "assigned-only", "within-groups", "within-organization"
ticket_comment_access string no What type of comments the agent can make. Allowed values: "public", "none"
ticket_deletion boolean no Whether or not the agent can delete tickets
ticket_editing boolean no Whether or not the agent can edit ticket properties
ticket_merge boolean no Whether or not the agent can merge tickets
ticket_tag_editing boolean no Whether or not the agent can edit ticket tags
twitter_search_access boolean no
user_view_access string no What the agent can do with customer lists. Allowed values: "full", "manage-group", "manage-personal", "none", "readonly"
view_access string no What the agent can do with views. Allowed values: "full", "manage-group", "manage-personal", "playonly", "readonly"
view_deleted_tickets boolean no Whether or not the agent can view deleted tickets
voice_access boolean no Whether or not the agent has access to Talk
Example
{
  "id":           35436,
  "name":         "Partner",
  "description":  "Can only make private comments on assigned tickets",
  "created_at":   "2012-02-20T22:55:29Z",
  "updated_at":   "2012-02-20T22:55:29Z",
  "configuration": {
    "chat_access":                     true,
    "end_user_profile_access":                "readonly",
    "explore_access":                  "edit",
    "forum_access":                    "readonly",
    "forum_access_restricted_content": false,
    "light_agent":                     false,
    "macro_access":                    "full",
    "manage_business_rules":           true,
    "manage_dynamic_content":          false,
    "manage_extensions_and_channels":  true,
    "manage_facebook":                 false,
    "organization_editing":            false,
    "organization_notes_editing":      false,
    "report_access":                   "none",
    "ticket_access":                   "within-groups",
    "ticket_comment_access":           "none",
    "ticket_deletion":                 false,
    "view_deleted_tickets":            false,
    "ticket_editing":                  true,
    "ticket_merge":                    false,
    "ticket_tag_editing":              true,
    "twitter_search_access":           true,
    "view_access":                     "full",
    "voice_access":                    true
  }
}

List Custom Roles

  • GET /api/v2/custom_roles
Availability
  • Accounts on the Enterprise plan or above
Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/custom_roles.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "custom_roles": [
    {
      "configuration": {
        "chat_access": true,
        "end_user_profile_access": "readonly",
        "explore_access": "edit",
        "forum_access": "readonly",
        "forum_access_restricted_content": false,
        "light_agent": false,
        "macro_access": "full",
        "manage_business_rules": true,
        "manage_dynamic_content": false,
        "manage_extensions_and_channels": true,
        "manage_facebook": false,
        "organization_editing": false,
        "organization_notes_editing": false,
        "report_access": "none",
        "ticket_access": "within-groups",
        "ticket_comment_access": "none",
        "ticket_deletion": false,
        "ticket_editing": true,
        "ticket_merge": false,
        "ticket_tag_editing": true,
        "twitter_search_access": true,
        "user_view_access": "full",
        "view_access": "full",
        "view_deleted_tickets": false,
        "voice_access": true
      },
      "created_at": "2012-03-12T16:32:22Z",
      "description": "Advisors manage the workflow and configure the help desk. They create or manage automations, macros, triggers, views, and SLA targets. They also set up channels and extensions. Advisors don't solve tickets, they can only make private comments.",
      "id": 16,
      "name": "Advisor",
      "role_type": 0,
      "updated_at": "2012-03-12T16:32:22Z"
    },
    {
      "configuration": {
        "chat_access": true,
        "end_user_profile_access": "readonly",
        "explore_access": "edit",
        "forum_access": "readonly",
        "forum_access_restricted_content": false,
        "light_agent": false,
        "macro_access": "full",
        "manage_business_rules": true,
        "manage_dynamic_content": false,
        "manage_extensions_and_channels": true,
        "manage_facebook": false,
        "organization_editing": false,
        "organization_notes_editing": false,
        "report_access": "none",
        "ticket_access": "within-groups",
        "ticket_comment_access": "none",
        "ticket_deletion": false,
        "ticket_editing": true,
        "ticket_merge": false,
        "ticket_tag_editing": true,
        "twitter_search_access": true,
        "user_view_access": "full",
        "view_access": "full",
        "view_deleted_tickets": false,
        "voice_access": true
      },
      "created_at": "2011-07-20T04:31:29Z",
      "description": "A Staff agent's primary role is to solve tickets. They can edit tickets within their groups, view reports, and add or edit personal views and macros.",
      "id": 6,
      "name": "Staff",
      "role_type": 0,
      "updated_at": "2012-02-02T10:32:59Z"
    }
  ]
}

Create Custom Role

  • POST /api/v2/custom_roles
Availability
  • Accounts on the Enterprise plan or above
Allowed For
  • Administrators
Using curl
curl https://{subdomain}.zendesk.com/api/v2/custom_roles.json \
  -v -u {email_address}:{password}
Example Response
Status 201 Created

{
  "custom_role": {
    "configuration": {
      "chat_access": true,
      "end_user_profile_access": "readonly",
      "explore_access": "edit",
      "forum_access": "readonly",
      "forum_access_restricted_content": false,
      "light_agent": false,
      "macro_access": "full",
      "manage_business_rules": true,
      "manage_dynamic_content": false,
      "manage_extensions_and_channels": true,
      "manage_facebook": false,
      "organization_editing": false,
      "organization_notes_editing": false,
      "report_access": "none",
      "ticket_access": "within-groups",
      "ticket_comment_access": "none",
      "ticket_deletion": false,
      "ticket_editing": true,
      "ticket_merge": false,
      "ticket_tag_editing": true,
      "twitter_search_access": true,
      "user_view_access": "readonly",
      "view_access": "full",
      "view_deleted_tickets": false,
      "voice_access": true
    },
    "created_at": "2012-03-12T16:32:22Z",
    "description": "sample description",
    "id": 10127,
    "name": "sample role",
    "role_type": 0,
    "updated_at": "2012-03-12T16:32:22Z"
  }
}

Show Custom Role

  • GET /api/v2/custom_roles/{custom_role_id}
Availability
  • Accounts on the Enterprise plan or above
Allowed For
  • Administrators
Parameters
Name Type In Required Description
custom_role_id integer Path true The ID of the custom agent role
Using curl
curl https://{subdomain}.zendesk.com/api/v2/custom_roles/{custom_role_id}.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "custom_role": {
    "configuration": {
      "chat_access": true,
      "end_user_profile_access": "readonly",
      "explore_access": "edit",
      "forum_access": "readonly",
      "forum_access_restricted_content": false,
      "light_agent": false,
      "macro_access": "full",
      "manage_business_rules": true,
      "manage_dynamic_content": false,
      "manage_extensions_and_channels": true,
      "manage_facebook": false,
      "organization_editing": false,
      "organization_notes_editing": false,
      "report_access": "none",
      "ticket_access": "within-groups",
      "ticket_comment_access": "none",
      "ticket_deletion": false,
      "ticket_editing": true,
      "ticket_merge": false,
      "ticket_tag_editing": true,
      "twitter_search_access": true,
      "user_view_access": "readonly",
      "view_access": "full",
      "view_deleted_tickets": false,
      "voice_access": true
    },
    "created_at": "2012-03-12T16:32:22Z",
    "description": "sample description",
    "id": 10127,
    "name": "sample role",
    "role_type": 0,
    "updated_at": "2012-03-12T16:32:22Z"
  }
}

Update Custom Role

  • PUT /api/v2/custom_roles/{custom_role_id}
Availability
  • Accounts on the Enterprise plan or above
Allowed Forx
  • Administrators
Parameters
Name Type In Required Description
custom_role_id integer Path true The ID of the custom agent role
Using curl
curl https://{subdomain}.zendesk.com/api/v2/custom_roles/{custom_role_id}.json \
  -v -u {email_address}:{password} \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{ "custom_role": {
    "name": "updated sample role",
    "description": "sample description",
    "configuration": {
      "chat_access": true,
      "user_view_access": "readonly"
    }
  }}'
Example Response
Status 200 OK

{
  "custom_role": {
    "configuration": {
      "chat_access": true,
      "end_user_profile_access": "readonly",
      "explore_access": "edit",
      "forum_access": "readonly",
      "forum_access_restricted_content": false,
      "light_agent": false,
      "macro_access": "full",
      "manage_business_rules": true,
      "manage_dynamic_content": false,
      "manage_extensions_and_channels": true,
      "manage_facebook": false,
      "organization_editing": false,
      "organization_notes_editing": false,
      "report_access": "none",
      "ticket_access": "within-groups",
      "ticket_comment_access": "none",
      "ticket_deletion": false,
      "ticket_editing": true,
      "ticket_merge": false,
      "ticket_tag_editing": true,
      "twitter_search_access": true,
      "user_view_access": "readonly",
      "view_access": "full",
      "view_deleted_tickets": false,
      "voice_access": true
    },
    "created_at": "2012-03-12T16:32:22Z",
    "description": "sample description",
    "id": 10127,
    "name": "sample role",
    "role_type": 0,
    "updated_at": "2012-03-12T16:32:22Z"
  }
}

Delete Custom Role

  • DELETE /api/v2/custom_roles/{custom_role_id}
Availability
  • Accounts on the Enterprise plan or above
Allowed For
  • Administrators
Parameters
Name Type In Required Description
custom_role_id integer Path true The ID of the custom agent role
Using curl
curl https://{subdomain}.zendesk.com/api/v2/custom_roles/{custom_role_id}.json \
  -v -u {email_address}:{password} \
  -X DELETE
Example Response
Status 204 No Content