Custom Agent Roles

Zendesk Support enterprise accounts have the option of providing a more granular access to their agents. This is done using custom roles, which is a specialization of the agent role. This API provides access to list the specialized roles available on the account.

JSON Format

Custom roles have the below attributes

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned upon creation
name string no yes Name of this custom role
description string no no A description of the role
role_type integer yes yes The value 0
configuration Configuration no no A detailed configuration of the role
created_at date yes no The time the record was created
updated_at date yes no The time the record was last updated
Configuration

Configuration for custom roles have the below attributes, which are all optional

Name Type Read-only Comment
chat_access boolean yes
manage_business_rules boolean no
manage_dynamic_content boolean no
manage_extensions_and_channels boolean no
manage_facebook boolean no
organization_editing boolean no
organization_notes_editing boolean yes
ticket_deletion boolean no
view_deleted_tickets boolean no
ticket_tag_editing boolean no
twitter_search_access boolean no
forum_access_restricted_content boolean no
end_user_list_access string no Allowed values: 'full', 'none'
ticket_access string no Allowed values: 'all', 'assigned-only', 'within-groups', 'within-organization'
ticket_comment_access string no Allowed values: 'public', 'none'
voice_access boolean no
moderate_forums boolean yes
group_access boolean yes
light_agent boolean yes
end_user_profile_access string no Allowed values: 'edit', 'edit-within-org', 'full', 'readonly'
explore_access string no Allowed values: 'edit', 'full', 'none', 'readonly'
forum_access string no Allowed values: 'edit-topics', 'full', 'readonly'
macro_access string no Allowed values: 'full', 'manage-group', 'manage-personal', 'readonly'
report_access string no Allowed values: 'full', 'none', 'readonly'
ticket_editing boolean no
ticket_merge boolean no
view_access string no Allowed values: 'full', 'manage-group', 'manage-personal', 'playonly', 'readonly'
user_view_access string no Allowed values: 'full', 'manage-group', 'manage-personal', 'none', 'readonly'
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":                "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.json

Availability
  • Accounts on the Enterprise plan
  • Accounts on the Professional plan with the Light Agents add-on
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": [
    {
      "id":             16,
      "name":           "Advisor",
      "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.",
      "created_at":     "2012-03-12T16:32:22Z",
      "updated_at":     "2012-03-12T16:32:22Z",
      "configuration": {
        "chat_access":                     true,
        ...
        "user_view_access":                "full"
      },
    },
    {
      "id":             6,
      "name":           "Staff",
      "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.",
      "created_at":     "2011-07-20T04:31:29Z",
      "updated_at":     "2012-02-02T10:32:59Z",
      "configuration": {
        "chat_access":                     true,
        ...
        "user_view_access":                "full"
      },
    }
  ]
}

Show Custom Role

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

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

{
"custom_role": {
  "id": 10127,
  "name": "sample role",
  "description": "sample description",
  "role_type": 0,
  "created_at": "2018-09-21T18:12:32Z",
  "updated_at": "2018-09-21T18:12:32Z",
  "configuration": {
    "chat_access": true,
    ...
    "user_view_access": "readonly"
  }
}

Create Custom Role

POST /api/v2/custom_roles.json

Availability
  • Accounts on the Enterprise plan
  • Accounts on the Professional plan with the Light Agents add-on
Allowed For
  • Administrators
Using curl
curl https://{subdomain}.zendesk.com/api/v2/custom_roles.json \
  -v -u {email_address}:{password} \
  -H "Content-Type: application/json" \
  -d '{ "custom_role": {
    "name": "sample role",
    "description": "sample description",
    "configuration": {
      "chat_access": true,
      ...
      "user_view_access": "readonly"
    }
  }}'
Example Response
Status: 200 OK

{
"custom_role": {
  "id": 10127,
  "name": "sample role",
  "description": "sample description",
  "role_type": 0,
  "created_at": "2018-09-21T18:12:32Z",
  "updated_at": "2018-09-21T18:12:32Z",
  "configuration": {
    "chat_access": true,
    ...
    "user_view_access": "readonly"
  }
}

Update Custom Role

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

Availability
  • Accounts on the Enterprise plan
  • Accounts on the Professional plan with the Light Agents add-on
Allowed For
  • Administrators
Using curl
curl https://{subdomain}.zendesk.com/api/v2/custom_roles/{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": {
  "id": 10127,
  "name": "updated sample role",
  "description": "sample description",
  "role_type": 0,
  "created_at": "2018-09-21T18:12:32Z",
  "updated_at": "2018-09-21T18:12:32Z",
  "configuration": {
    "chat_access": true,
    ...
    "user_view_access": "readonly"
  }
}

Delete Custom Role

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

Availability
  • Accounts on the Enterprise plan
  • Accounts on the Professional plan with the Light Agents add-on
Allowed For
  • Administrators
Using curl
curl https://{subdomain}.zendesk.com/api/v2/custom_roles/{id}.json \
  -v -u {email_address}:{password} \
  -X DELETE
Example Response
Status: 204 No Content