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

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

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

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 15 elements are returned (the page limit), use ?page=2 to check for the next 15 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 15 elements are returned (the page limit), use ?page=2 to check for the next 15 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>https://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>https://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