Users in your help desk are assigned one of the following roles:

Role	value
End user	0
Administrator	2
Agent	4

In the Enterprise version of Zendesk, agent users can also be assigned to an Enterprise agent role. See Enterprise agent roles below.

Administrators always have Agent privileges, in addition to Administrator privileges.

Additionally, you can define ticket access restrictions for end-users and agents:

Restricted to:	Value	Applicable for end-users	Applicable for agents
All tickets	0		x
Tickets in member groups	1		x
Tickets in member organization	2	x	x
Assigned tickets	3		x
Tickets requested by user	4	x

Show

GET /users/#{id}.xml
GET /users/current.xml
Returns a single user. Using /users/current in lieu of a user ID returns the currently authenticated user’s XML.

Response

Status: 200

<user>
  <created-at>2007-05-15T18:07:57Z</created-at>
  <email>aljohson@yourcompany.dk</email>
  <id>88</id>
  <is-active>true</is-active>
  <is-verified>true</is-verified>
  <name>Al Johnson</name>
  <roles>2</roles>
  <restriction-id>1</restriction-id>
  <time-format>0</time-format>
  <locale-id type="integer">1</locale-id>
  <time-zone>(GMT +01:00) Brussels, Copenhagen, Madrid, Paris</time-zone>
  <updated-at>2007-07-06T12:46:12Z</updated-at>
  <organization-id>2143</organization-id>
  <current-tags>tag_a tab_b tag_c</current-tags>
  <groups>
    <group>
      <id>13</id>
      <is-active>true</is-active>
      <name>Support</name>
    </group>
    <group>
      <id>3</id>
      <is-active>true</is-active>
      <name>Sales</name>
    </group>
  </groups>
</user>

This user is an agent, and is a member of 2 groups with access to tickets in member groups only.

List All

GET /users.xml
GET /organizations/#{organization_id}/users.xml
GET /groups/#{group_id}/users.xml
Returns all users in your help desk. The list is paginated using offsets. If 100 elements are returned (the page limit), use ?page=2 to check for the next 100 and so on. You can narrow down the list to only show the users in an organization by requesting /organizations/#{organization_id}/users.xml. Likewise, you can get the users in a group by requesting /groups/#{group_id}/users.xml.

Response

Status: 200 

<users>
  <user>
  ...
  </user>
  <user>
  ...
  </user>
</users>

List by search term

Get /users.xml?query=John&role=2
Returns a collection of users that has a name matching the query passed in through the URL. The list is paginated using offsets. If 100 elements are returned (the page limit), use ?page=2 to check for the next 100 and so on.

Response

Status: 200 

<users>
  <user>
    ...
    <name>John Smith</name>
    <role>2</role>
  </user>
  <user>
    ...
    <name>Alexander Johnson</name>
    <role>2</role>
  </user>
</users>

Create

POST /users.xml
Creates a new user. The XML for the new user is returned on a successful request with the timestamps recorded and user id. If the account doesn’t allow for more users to be created, a “507 Insufficient Storage” response will be returned.

Request

<user>
  <email>aljohson@yourcompany.dk</email>
  <name>Al Johnson</name>
  <remote-photo-url>http://www.example.com/directory/image.png</remote-photo-url>
  <roles>4</roles>
  <restriction-id>1</restriction-id>
  <current-tags>tag_a tab_b tag_c</current-tags>
  <groups type='array'>
    <group>2</group>
    <group>3</group>
  </groups>
</user>

Note that, if a remote photo url is provided, it must be a direct URL which is not behind authentication. The API does not follow redirects.

Response

Status: 201 Location: {new-user-id}.xml

Update

PUT /users/#{id}.xml
Updates an existing user with new details from the submitted XML.

Request

<user>
  <name>Albert Johnson</name>
  <remote-photo-url>http://www.example.com/directory/image.png</remote-photo-url>
  <current-tags>tag_a tab_b tag_c</current-tags>
  <groups type='array'>
    <group>2</group>
  </groups>
</user>

Note that if you do not submit a groups array, the user does not get unassigned from his groups. If you submit an empty group array, the user gets unassigned from all groups:

<user>
  <name>The man with no groups</name>
  <groups type='array'></groups>
</user>

Response

Status: 200

Updates the user and sets the user to be a member of group 2 only. Omit the part, if you do not wish to change the users’ group status.

You’re able to set a users preferred language via the API, either during CREATE or UPDATE. You’re able to achieve this by simply setting <locale-id>1</locale-id> where the value is the ID of the corresponding locale. You can find a listing of your currently enabled languages with GET /account/translations.xml and a full list of the existent languages with GET /i18n/translations.xml. This will only work if you have multiple languages selected, and the locale-id being referenced is turned on in your account (Account -> Personalize your zendesk -> Additional Languages). This is only applicable to End-Users, and for accounts on the Plus+ plan.

Destroy

DELETE /users/#{id}.xml
Destroys the user at the referenced URL.

The user is not actually deleted from the system, but is set inactive and can no longer be assigned or submit tickets and entries.

Response

Status: 200

LIST USER IDENTITIES

GET /users/#{user_id}/user_identities.xml
Returns all user identities of the given user.

Response

<records>
  <record>
    ...
    <value>2222222</value>
    <identity-type>twitter_handle</identity-type>
    <screen-name>the_handle</screen-name>
    ...
  </record>
  <record>
    ...
    <value>aljohson@yourcompany.dk</value>
    <identity-type>email</identity-type>
    ...
  </record>
  ...
</records>

Add an Email address to a User

POST /users/#{user_id}/user_identities.xml
Adds an email address for the user specified in the URL.

Request

<email>address@example.com</email>

Response

Status: 201

Add a Twitter handle to a User

POST /users/#{user_id}/user_identities.xml
Adds a Twitter handle for the user specified in the URL.

Request

<twitter>a_twitter_handle</twitter>

Response

Status: 201

Make a given User Identity the primary for that User

POST /users/#{user_id}/user_identities/#{id}/make_primary

Response

Status: 200

Delete a given User Identity

DELETE /users/#{user_id}/user_identities/#{id}

Response

Status: 200

Enterprise agent roles

In the Enterprise version of Zendesk, you can assign your agents additional pre-defined agent roles or create your own custom agent roles. Unlike the standard end-user, administrator, and agents roles, the Enterprise roles do not have fixed values that are used for all Zendesk accounts. Instead, the Enterprise agent roles have values that are unique to your account. To assign an agent to an Enterprise role using the API, you need to first discover your unique enterprise agent role values using the following API command.

GET /roles.xml (or GET /roles.json)

XML Response

<permission-sets type="array" count="4">
   <permission-set>
      <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.
      </description>
      <id type="integer">8882</id>
      <name>Advisor</name>
   </permission-set>
   <permission-set>
      <description>
      Light agents can view, be CC'd on, and add private comments to
      ticket accessible to them. They can also view reports of all
      tickets within the help desk. Light agents cannot be assigned
      to or edit tickets. You can add an unlimited number of light
      agents at no charge.
      </description>
      <id type="integer">8887</id>
      <name>Light Agent</name>
   </permission-set>
   <permission-set>
      <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.
      </description>
      <id type="integer">8872</id>
      <name>Staff</name>
   </permission-set>
   <permission-set>
      <description>
      Team leaders have greater access to the help desk than staff agents.
      They can read and edit all tickets, moderate forums, and create and
      edit end-users, groups, and organizations.
      </description>
      <id type="integer">8877</id>
      <name>Team Leader</name>
   </permission-set>
</permission-sets>

The response example above lists all the predefined agent roles. If you’ve created custom agent roles, these will be listed as well.

<permission-set>
   <description>
   This is the description for my custom agent role.
   </description>
   <id type="integer">8890</id>
   <name>My custom agent role</name>
</permission-set>

Once you’ve discovered the role IDs for your Enterprise agent roles, you can assign these roles to your agents via the API.

Note: The Enterprise agent roles can only be assigned to agents (users with their role set to 4).

PUT /users/#{id}.xml

Updates an agent’s profile to include the Enterprise agent role specified in the submitted XML.

Request

<user><custom_role_id>8877</custom_role_id></user>

Response

Status: 200