Users
Zendesk Support has three types of users: end users (your customers), agents, and administrators.
End users
End users request support through tickets. End users have access to Help Center where they can view knowledge base articles and community content, access their ticket history, and submit new tickets.
Agents
Agents work in Zendesk Support to solve tickets. Agents can be divided into multiple groups and can also belong to multiple groups. Agents don't have access to administrative configuration in Zendesk Support such as business rules or automations, but can configure their own macros and views.
Administrators
Administrators have all the abilities of agents, plus administrative abilities. Accounts on the Enterprise plan and above can configure custom roles to give agents varying degrees of administrative access.
Listing Requested Tickets and CC'ed Tickets
Use the Tickets API to list: x * tickets requested by a user * tickets on which a user is cc'ed
Listing Help Center Content by a User
Use the Help Center API to list:
- articles and article comments created by a user
- community posts and post comments created by a user
JSON Format
Users are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
active | boolean | true | false | false if the user has been deleted |
alias | string | false | false | An alias displayed to end users |
chat_only | boolean | true | false | Whether or not the user is a chat-only agent |
created_at | string | true | false | The time the user was created |
custom_role_id | integer | false | false | A custom role if the user is an agent on the Enterprise plan or above |
default_group_id | integer | false | false | The id of the user's default group |
details | string | false | false | Any details you want to store about the user, such as an address |
string | false | false | The user's primary email address. *Writeable on create only. On update, a secondary email is added. See Email Address | |
external_id | string | false | false | A unique identifier from another system. The API treats the id as case insensitive. Example: "ian1" and "Ian1" are the same user |
iana_time_zone | string | true | false | The time zone for the user |
id | integer | true | false | Automatically assigned when the user is created |
last_login_at | string | true | false | The last time the user signed in to Zendesk Support |
locale | string | false | false | The user's locale. A BCP-47 compliant tag for the locale. If both "locale" and "locale_id" are present on create or update, "locale_id" is ignored and only "locale" is used. |
locale_id | integer | false | false | The user's language identifier |
moderator | boolean | false | false | Designates whether the user has forum moderation capabilities |
name | string | false | true | The user's name |
notes | string | false | false | Any notes you want to store about the user |
only_private_comments | boolean | false | false | true if the user can only create private comments |
organization_id | integer | false | false | The id of the user's organization. If the user has more than one organization memberships, the id of the user's default organization |
phone | string | false | false | The user's primary phone number. See Phone Number below |
photo | object | false | false | The user's profile picture represented as an Attachment object |
report_csv | boolean | true | false | Whether or not the user can access the CSV report on the Search tab of the Reporting page in the Support admin interface. See Analyzing Help Center search results in Help Center. Only available on the Support Professional or Suite Growth plan or above. |
restricted_agent | boolean | false | false | If the agent has any restrictions; false for admins and unrestricted agents, true for other agents |
role | string | false | false | The user's role. Possible values are "end-user", "agent", or "admin" |
role_type | integer | true | false | The user's role id. 0 for custom agents, 1 for light agent, 2 for chat agent, and 3 for chat agent added to the Support account as a contributor (Chat Phase 4) |
shared | boolean | true | false | If the user is shared from a different Zendesk Support instance. Ticket sharing accounts only |
shared_agent | boolean | true | false | If the user is a shared agent from a different Zendesk Support instance. Ticket sharing accounts only |
shared_phone_number | boolean | true | false | Whether the phone number is shared or not. See Phone Number below |
signature | string | false | false | The user's signature. Only agents and admins can have signatures |
suspended | boolean | false | false | If the agent is suspended. Tickets from suspended users are also suspended, and these users cannot sign in to the end user portal |
tags | array | false | false | The user's tags. Only present if your account has user tagging enabled |
ticket_restriction | string | false | false | Specifies which tickets the user has access to. Possible values are: "organization", "groups", "assigned", "requested", null |
time_zone | string | false | false | The user's time zone. See Time Zone |
two_factor_auth_enabled | boolean | true | false | If two factor authentication is enabled |
updated_at | string | true | false | The time the user was last updated |
url | string | true | false | The user's API url |
user_fields | object | false | false | Values of custom fields in the user's profile. See User Fields |
verified | boolean | false | false | Any of the user's identities is verified. See User Identities |
Email Address
You can specify a user's primary email address when you create the user. See Specifying email and verified attributes.
To update a user's primary email address, use the Make Identity Primary endpoint.
Time Zone
A time_zone
name consists of a string such as "Eastern Time (US & Canada)".
For a list of valid names, see the Time zone list menu on the Localization page
in the Support admin interface (Admin > Account > Localization).
For example, if the menu lists "(GMT+02:00) Berlin", then use "Berlin" as the
time_zone
name.
Request body in User API:
{
"user": {
"id": 35436,
"name": "Johnny Agent",
"time_zone": "Berlin",
...
}
}
User Fields
You can use the user_fields
object to set the value of one or more custom fields in the user's profile.
Specify field keys as the properties to set. Example:
"user_fields": {
"membership_level": "silver",
"membership_expires": "2019-07-23T00:00:00Z"
}
For more information, see User Fields and Adding custom fields to users.
Phone Number
The phone number should comply with the E.164 international telephone numbering plan. Example +15551234567
.
E164 numbers are international numbers with a country dial prefix, usually an area code and a subscriber number.
A valid E.164 phone number must include a country calling code.
A phone number can be one of the following types:
- A direct line linked to a single user, which is indicated by a
shared_phone_number
attribute of false. A direct line can be used as a user identity - A shared number linked to multiple users, indicated by a
shared_phone_number
attribute of true. A shared number can not be used as a user identity
See Understanding how phone numbers are linked to end-user profiles in the Support Help Center.
JSON Format for End Users
When an end user makes the request, the user is returned with the following attributes:
Name | Type | Read-only | Mandatory | Comment |
---|---|---|---|---|
id | integer | yes | no | Automatically assigned when creating users |
string | no | no | The primary email address of this user | |
name | string | no | yes | The name of the user |
created_at | date | yes | no | The time the user was created |
locale | string | yes | no | The locale for this user |
locale_id | integer | no | no | The language identifier for this user |
organization_id | integer | no | no | The id of the user's organization. If the user has more than one organization memberships, the id of the user's default organization |
phone | string | no | no | The primary phone number of this user. See Phone Number in the Users API |
shared_phone_number | boolean | yes | no | Whether the phone number is shared or not. See Phone Number in the Users API |
photo | Attachment | no | no | The user's profile picture represented as an Attachment object |
role | string | no | no | The role of the user. Possible values: "end-user", "agent", "admin" |
time_zone | string | no | no | The time-zone of this user |
updated_at | date | yes | no | The time of the last update of the user |
url | string | yes | no | The API url of this user |
verified | boolean | no | no | Any of the user's identities is verified. See User Identities |
Responses will vary depending on the role of the client making the request. The following example is a response for an end-user role.
Example
{
"id": 35436,
"url": "https://company.zendesk.com/api/v2/end_users/35436.json",
"name": "Johnny End User",
"created_at": "2009-07-20T22:55:29Z",
"updated_at": "2011-05-05T10:38:52Z",
"time_zone": "Copenhagen",
"email": "[email protected]",
"phone": "+15551234567",
"locale": "en-US",
"locale_id": 1,
"organization_id": 57542,
"role": "end-user",
"verified": true,
"photo": {
"id": 928374,
"name": "my_funny_profile_pic.png",
"content_url": "https://company.zendesk.com/photos/my_funny_profile_pic.png",
"content_type": "image/png",
"size": 166144,
"thumbnails": [
{
"id": 928375,
"name": "my_funny_profile_pic_thumb.png",
"content_url": "https://company.zendesk.com/photos/my_funny_profile_pic_thumb.png",
"content_type": "image/png",
"size": 58298
}
]
}
}
This example is a response for an admin or agent request.
Example
{
"active": true,
"alias": "Mr. Johnny",
"created_at": "2009-07-20T22:55:29Z",
"custom_role_id": 9373643,
"details": "",
"email": "[email protected]",
"external_id": "sai989sur98w9",
"iana_time_zone": "Pacific/Pago_Pago",
"id": 35436,
"last_login_at": "2011-05-05T10:38:52Z",
"locale": "en-US",
"locale_id": 1,
"moderator": true,
"name": "Johnny Agent",
"notes": "Johnny is a nice guy!",
"only_private_comments": false,
"organization_id": 57542,
"phone": "+15551234567",
"photo": {
"content_type": "image/png",
"content_url": "https://company.zendesk.com/photos/my_funny_profile_pic.png",
"id": 928374,
"name": "my_funny_profile_pic.png",
"size": 166144,
"thumbnails": [
{
"content_type": "image/png",
"content_url": "https://company.zendesk.com/photos/my_funny_profile_pic_thumb.png",
"id": 928375,
"name": "my_funny_profile_pic_thumb.png",
"size": 58298
}
]
},
"restricted_agent": true,
"role": "agent",
"role_type": 0,
"shared": false,
"shared_agent": false,
"signature": "Have a nice day, Johnny",
"suspended": true,
"tags": [
"enterprise",
"other_tag"
],
"ticket_restriction": "assigned",
"time_zone": "Copenhagen",
"updated_at": "2011-05-05T10:38:52Z",
"url": "https://company.zendesk.com/api/v2/users/35436.json",
"user_fields": {
"user_date": "2012-07-23T00:00:00Z",
"user_decimal": 5.1,
"user_dropdown": "option_1"
},
"verified": true
}
List Deleted Users
GET /api/v2/deleted_users
Returns deleted users, including permanently deleted users.
If the results contains permanently deleted users, the users' properties
that normally contain personal data, such as email
and phone
,
are null. The name
property is "Permanently Deleted User".
Pagination
- Cursor pagination (recommended)
- Offset pagination
See Pagination.
Returns a maximum of 100 records per page.
Allowed For
- Agents
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/deleted_users.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"deleted_users": [
{
"active": false,
"created_at": "2019-08-26T02:10:24Z",
"email": null,
"id": 189304711533,
"locale": "en-US",
"locale_id": 1,
"name": "David",
"organization_id": null,
"phone": null,
"photo": null,
"role": "end-user",
"shared_phone_number": null,
"time_zone": "Eastern Time (US \u0026 Canada)",
"updated_at": "2019-08-26T02:10:27Z",
"url": "https://{subdomain}.zendesk.com/api/v2/deleted_users/189304711533"
},
{
"active": false,
"created_at": "2019-08-26T02:10:28Z",
"email": null,
"id": 12204720593,
"locale": "en-US",
"locale_id": 1,
"name": "Linda",
"organization_id": null,
"phone": null,
"photo": null,
"role": "end-user",
"shared_phone_number": null,
"time_zone": "Eastern Time (US \u0026 Canada)",
"updated_at": "2019-08-26T02:10:29Z",
"url": "https://{subdomain}.zendesk.com/api/v2/deleted_users/12204720593"
}
]
}
Count Deleted Users
GET /api/v2/deleted_users/count
Returns an approximate count of deleted users, including permanently deleted users. If the count exceeds 100,000, it is updated every 24 hours.
The response includes a refreshed_at
property in a count
object that contains a timestamp indicating when the count was last updated.
Note: When the count exceeds 100,000, count[refreshed_at]
may occasionally be null.
This indicates that the count is being updated in the background, and count[value]
is limited to 100,000 until the update is complete.
Allowed For
- Agents
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/deleted_users/count.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"count": {
"refreshed_at": "2020-04-06T02:18:17Z",
"value": 13
}
}
Show Deleted User
GET /api/v2/deleted_users/{deleted_user_id}
Returns users that have been deleted but not permanently yet. See Permanently Delete User.
Allowed For:
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
deleted_user_id | integer | Path | true | The ID of the deleted user |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/deleted_users/{deleted_user_id}.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"deleted_user": {
"active": false,
"created_at": "2019-08-26T02:10:24Z",
"email": null,
"id": 189304711533,
"locale": "en-US",
"locale_id": 1,
"name": "David",
"organization_id": null,
"phone": null,
"photo": null,
"role": "end-user",
"shared_phone_number": null,
"time_zone": "Eastern Time (US \u0026 Canada)",
"updated_at": "2019-08-26T02:10:27Z",
"url": "https://{subdomain}.zendesk.com/api/v2/deleted_users/189304711533"
}
}
Permanently Delete User
DELETE /api/v2/deleted_users/{deleted_user_id}
Before permanently deleting a user, you must delete the user first. See Delete User.
WARNING: Permanently deleting a user deletes all of their information. This information is not recoverable.
Permanent user deletion rate limit
You can permanently delete 700 users every 10 minutes. The rate limiting mechanism behaves as described in Rates Limits in the API introduction. Zendesk recommends that you obey the Retry-After header values.
Allowed For
- Agents, with restrictions on certain actions
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
deleted_user_id | integer | Path | true | The ID of the deleted user |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/deleted_users/{id}.json \
-v -u {email_address}:{password} \
-X DELETE
Example Response
Status 200 OK
{
"deleted_user": {
"active": false,
"created_at": "2019-08-26T02:10:24Z",
"email": null,
"id": 189304711533,
"locale": "en-US",
"locale_id": 1,
"name": "David",
"organization_id": null,
"phone": null,
"photo": null,
"role": "end-user",
"shared_phone_number": null,
"time_zone": "Eastern Time (US \u0026 Canada)",
"updated_at": "2019-08-26T02:10:27Z",
"url": "https://{subdomain}.zendesk.com/api/v2/deleted_users/189304711533"
}
}
List Users
GET /api/v2/users
GET /api/v2/groups/{group_id}/users
GET /api/v2/organizations/{organization_id}/users
Pagination
- Cursor pagination (recommended)
- Offset pagination
See Pagination.
Returns a maximum of 100 records per page.
Allowed For
- Admins, Agents and Light Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
permission_set | integer | Query | false | For custom roles which is available on the Enterprise plan and above. You can only filter by one role ID per request |
role | string | Query | false | Filters the results by role. Possible values are "end-user", "agent", or "admin". Allowed values are "end-user", "agent", or "admin". |
role[] | string | Query | false | Filters the results by more than one role using the format role[]={role}&role[]={role} |
Using cURL
# List Users
curl https://{subdomain}.zendesk.com/api/v2/users.json \
-v -u {email_address}:{password}
# with role filtering
# **Note**: If filtering by multiple roles in curl, make sure to include
# the `-g` flag to prevent curl from interpreting the square brackets
# as globbing characters. Also enclose the URL in quotes. Example:
curl -g 'https://{subdomain}.zendesk.com/api/v2/users.json?role[]=admin&role[]=end-user' \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"users": [
{
"id": 223443,
"name": "Johnny Agent"
},
{
"id": 8678530,
"name": "James A. Rosen"
}
]
}
Create User
POST /api/v2/users
Skip verification email
If you need to create users without sending out a verification email, include a "verified": true
property.
User role
If you don't specify a role
parameter, the new user is assigned the role of end user.
If you need to create agents with a specific role, the role
property only accepts three possible values: "end-user", "agent", and
"admin". Therefore, set role
to "agent" as well as add a new
property called custom_role_id
and give it the actual desired
role ID from your Zendesk Support account. This applies to the
built-in light agent role of Zendesk Support as well.
Create User with Multiple Identities
If you have a user with multiple identities, such as email addresses and Twitter accounts, you can also include
these values at creation time by including an identities
array where each identity in the array has a type
and value
property. Example: {"type": "email", "value": "[email protected]"}
. This is especially useful when importing users from another system.
Allowed For
- Agents, with restrictions on certain actions
Example Body
{
"user": {
"custom_role_id": 123456,
"email": "[email protected]",
"identities": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "twitter",
"value": "tester84"
}
],
"name": "Roger Wilco",
"organization": {
"name": "VIP Customers"
},
"role": "agent"
}
}
Using cURL
# with role
curl https://{subdomain}.zendesk.com/api/v2/users.json \
-d '{"user": {"name": "Roger Wilco", "email": "[email protected]", "role": "agent", "custom_role_id": 123456}}' \
-H "Content-Type: application/json" -X POST \
-v -u {email_address}:{password}
# with organization
curl https://{subdomain}.zendesk.com/api/v2/users/users.json \
-d '{"user": {"name": "Roger Wilco", "email": "[email protected]", "organization": {"name": "VIP Customers"}}}' \
-H "Content-Type: application/json" -X POST \
-v -u {email_address}:{password}
# with identities
curl https://{subdomain}.zendesk.com/api/v2/users.json \
-d '{"user": {"name": "Roger Wilco", "identities": [{ "type": "email", "value": "[email protected]"}, {"type": "twitter", "value": "tester84" }]}}' \
-H "Content-Type: application/json" -X POST \
-v -u {email_address}:{password}
Example Response
Status 201 Created
{
"user": {
"custom_role_id": 123456,
"email": "[email protected]",
"id": 9873843,
"name": "Roger Wilco",
"organization_id": 57542,
"role": "agent",
"role_type": 0
}
}
Autocomplete Users
GET /api/v2/users/autocomplete?name={name}
Returns an array of users whose name starts with the value specified in the name
parameter.
It only returns users with no foreign identities.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
name | string | Query | true | The name to search for the user. |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/autocomplete.json?name=gil \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"users": [
{
"id": 35436,
"name": "Robert Jones",
"notes": "sigil issue"
},
{
"id": 9873843,
"name": "Terry Gilliam"
}
]
}
Count Users
GET /api/v2/users/count
GET /api/v2/groups/{group_id}/users/count
GET /api/v2/organizations/{organization_id}/users/count
Returns an approximate count of users. If the count exceeds 100,000, it is updated every 24 hours.
The response includes a refreshed_at
property in a count
object that contains a timestamp indicating when the count was last updated.
Note: When the count exceeds 100,000, the refreshed_at
property may occasionally be null.
This indicates that the count is being updated in the background. The count
object's value
property is limited to 100,000 until the update is complete.
Allowed For
- Admins, Agents and Light Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
permission_set | integer | Query | false | For custom roles which is available on the Enterprise plan and above. You can only filter by one role ID per request |
role | string | Query | false | Filters the results by role. Possible values are "end-user", "agent", or "admin". Allowed values are "end-user", "agent", or "admin". |
role[] | string | Query | false | Filters the results by more than one role using the format role[]={role}&role[]={role} |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/count.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"count": {
"refreshed_at": "2020-04-06T02:18:17Z",
"value": 102
}
}
Create Many Users
POST /api/v2/users/create_many
Accepts an array of up to 100 user objects.
Note: Access to this endpoint is limited. You may not be able to use it to bulk-import users or organizations. If you're unable, a 403 Forbidden error is returned. If you need access and can't use this endpoint, contact us at [email protected] for assistance.
Allowed For
- Agents, with restrictions on certain actions
Specifying an organization
You can assign a user to an existing organization by setting an
organization_id
property in the user object.
Response
This endpoint returns a job_status
JSON object and queues a background job to do the work.
Use the Show Job Status endpoint to check for the job's completion.
Example Body
{
"users": [
{
"email": "[email protected]",
"name": "Roger Wilco",
"organization_id": 567812345,
"role": "agent"
},
{
"email": "[email protected]",
"name": "Woger Rilco",
"role": "admin"
}
]
}
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/create_many.json \
-d '{"users": [{"name": "Roger Wilco", "email": "[email protected]", "role": "agent"}, {"name": "Woger Rilco", "email": "[email protected]", "role": "admin"}]}' \
-H "Content-Type: application/json" -X POST \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"job_status": {
"id": "82de0b044094f0c67893ac9fe64f1a99",
"message": "Completed at 2018-03-08 10:07:04 +0000",
"progress": 2,
"results": [
{
"action": "update",
"id": 244,
"status": "Updated",
"success": true
},
{
"action": "update",
"id": 245,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"
}
}
Create Or Update User
POST /api/v2/users/create_or_update
Creates a user if the user does not already exist, or updates an existing user identified by e-mail address or external ID.
If you don't specify a role parameter, the new user is assigned the role of end user.
If you need to create users without sending out a verification email, include a "verified": true
property in the body.
Response Status Code
- If the user exists in Zendesk, a successful request returns a 200 status code with "Location: /api/v2/users/{user_id}.json".
- If the user does not exist in Zendesk, a successful request returns a 201 status code with "Location: /api/v2/users/{new_user_id}.json".
Allowed For
- Agents, with restrictions on certain actions
Example Body
{
"user": {
"custom_role_id": 123456,
"email": "[email protected]",
"identities": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "twitter",
"value": "tester84"
}
],
"name": "Roger Wilco",
"organization": {
"name": "VIP Customers"
},
"role": "agent"
}
}
Using cURL
# Existing user identified by e-mail address:
curl https://{subdomain}.zendesk.com/api/v2/users/create_or_update.json \
-d '{"user": {"name": "Roger Wilco", "email": "[email protected]"}}' \
-H "Content-Type: application/json" -X POST \
-v -u {email_address}:{password}
# Existing user identified by external ID:
curl https://{subdomain}.zendesk.com/api/v2/users/create_or_update.json \
-d '{"user": {"external_id": "account_12345", "name": "Roger Wilco", "email": "[email protected]"}}' \
-H "Content-Type: application/json" -X POST \
-v -u {email_address}:{password}
# The user can also be added to a named organization.
curl https://{subdomain}.zendesk.com/api/v2/users/create_or_update.json \
-d '{"user": {"name": "Roger Wilco", "email": "[email protected]", "organization": {"name": "VIP Customers"}}}' \
-H "Content-Type: application/json" -X POST \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"user": {
"custom_role_id": 123456,
"email": "[email protected]",
"id": 9873843,
"name": "Roger Wilco",
"organization_id": 57542,
"role": "agent",
"role_type": 0
}
}
Create Or Update Many Users
POST /api/v2/users/create_or_update_many
Accepts an array of up to 100 user objects. For each user, the user is created if it does not already exist, or the existing user is updated.
Each individual user object can identify an existing user by email
or by external_id
.
This endpoint returns a job_status
JSON object and queues a background job to do the work.
Use the Show Job Status endpoint to check for the job's completion.
Allowed For
- Agents, with restrictions on certain actions
Example Body
{
"users": [
{
"custom_role_id": 123456,
"email": "[email protected]",
"identities": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "twitter",
"value": "tester84"
}
],
"name": "Roger Wilco",
"organization": {
"name": "VIP Customers"
},
"role": "agent"
},
{
"email": "[email protected]",
"external_id": "account_54321",
"name": "Woger Rilco",
"role": "admin"
}
]
}
Using cURL
# Existing user identified by e-mail address:
curl https://{subdomain}.zendesk.com/api/v2/users/create_or_update_many.json \
-d '{"users": [{"name": "Roger Wilco", "email": "[email protected]", "role": "agent"}, {"external_id": "account_54321", "name": "Woger Rilco", "email": "[email protected]", "role": "admin"}]}' \
-H "Content-Type: application/json" -X POST \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"job_status": {
"id": "82de0b044094f0c67893ac9fe64f1a99",
"message": "Completed at 2018-03-08 10:07:04 +0000",
"progress": 2,
"results": [
{
"action": "update",
"id": 244,
"status": "Updated",
"success": true
},
{
"action": "update",
"id": 245,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"
}
}
Bulk Deleting Users
DELETE /api/v2/users/destroy_many
Accepts a comma-separated list of up to 100 user ids.
The request takes an ids
or an external_ids
query parameter.
Response
This endpoint returns a job_status
JSON object and queues a background job to do the work.
Use the Show Job Status endpoint to check for the job's completion.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
external_ids | string | Query | false | External Id of the users to delete. Comma separated |
ids | string | Query | false | Id of the users to delete. Comma separated |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/destroy_many.json?ids=1,2,3 \
-v -u {email_address}:{password} -X DELETE
Example Response
Status 200 OK
{
"job_status": {
"id": "82de0b044094f0c67893ac9fe64f1a99",
"message": "Completed at 2018-03-08 10:07:04 +0000",
"progress": 2,
"results": [
{
"action": "update",
"id": 244,
"status": "Updated",
"success": true
},
{
"action": "update",
"id": 245,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"
}
}
Show Self
GET /api/v2/users/me
Allowed For
- Anonymous users
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/me.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"user": {
"id": 35436,
"name": "Johnny Agent"
}
}
Merge Self With Another User
PUT /api/v2/users/me/merge
Merges the user making the request into the specified existing user.
Allowed For
- Verified end users
Example Body
{
"user": {
"email": "[email protected]",
"password": "foo1234"
}
}
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/me/merge.json \
-d '{"user": {"password": "foo1234", "email": "[email protected]"}}' \
-H "Content-Type: application/json" -X PUT \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"user": {
"id": 9873843,
"name": "Roger Wilco"
}
}
Request User Create
POST /api/v2/users/request_create
Sends the owner a reminder email to update their subscription so more agents can be created.
Allowed For
- Agents
Example Body
{
"user": {
"email": "[email protected]",
"name": "Roger Wilco"
}
}
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/request_create.json \
-d '{"user": {"name": "Roger Wilco", "email": "[email protected]"}}' \
-H "Content-Type: application/json" \
-X POST -v -u {email_address}:{password}
Example Response
Status 200 OK
Search Users
GET /api/v2/users/search
Returns an array of users who meet the search criteria.
Allowed For
- Admins, Agents and Light Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
external_id | string | Query | false | The external_id parameter does not support the search syntax. It only accepts ids. |
query | string | Query | false | The query parameter supports the Zendesk search syntax for more advanced user searches. It can specify a partial or full value of any user property, including name, email address, notes, or phone. Example: query="jdoe" . See the Search API. |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/search.json?query=gil \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"users": [
{
"id": 35436,
"name": "Robert Jones",
"notes": "sigil issue"
},
{
"id": 9873843,
"name": "Terry Gilliam"
}
]
}
Show Many Users
GET /api/v2/users/show_many
Accepts a comma-separated list of up to 100 user ids or external ids.
Allowed For:
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
external_ids | string | Query | false | Accepts a comma-separated list of up to 100 external ids. |
ids | string | Query | false | Accepts a comma-separated list of up to 100 user ids. |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/show_many.json?ids=345678,901234 \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"users": [
{
"id": 345678,
"name": "Johnny Appleseed"
},
{
"id": 901234,
"name": "Rupert Root"
}
]
}
Update Many Users
PUT /api/v2/users/update_many
PUT /api/v2/users/update_many?ids={ids}
PUT /api/v2/users/update_many?external_ids={external_ids}
Bulk or batch updates up to 100 users.
Bulk update
To make the same change to multiple users, use the following endpoint and data format:
https://{subdomain}.zendesk.com/api/v2/users/update_many.json?ids=1,2,3
{
"user": {
"organization_id": 1
}
}
Batch update
To make different changes to multiple users, use the following endpoint and data format:
https://{subdomain}.zendesk.com/api/v2/users/update_many.json
{
"users": [
{ "id": 10071, "name": "New Name", "organization_id": 1 },
{ "id": 12307, "verified": true }
]
}
Allowed For
- Agents, with restrictions
Agents can only update end users. Administrators can update end users, agents, and administrators.
Response
This endpoint returns a job_status
JSON object and queues a background job to do the work.
Use the Show Job Status endpoint to check for the job's completion.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
external_ids | string | Query | false | External Id of the users to update. Comma separated |
ids | string | Query | false | Id of the users to update. Comma separated |
Example Body
{
"user": {
"organization_id": 1
}
}
Using cURL
# Bulk update
curl https://{subdomain}.zendesk.com/api/v2/users/update_many.json?ids=1,2,3 \
-d '{"user": {"organization_id": 1}}' \
-H "Content-Type: application/json" -X PUT \
-v -u {email_address}:{password}
# Batch update
curl https://{subdomain}.zendesk.com/api/v2/users/update_many.json \
-d '{"users": [{"id": 10071, "name": "New Name", "organization_id": 1}, {"external_id": "123", "verified": true}]}' \
-H "Content-Type: application/json" -X PUT \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"job_status": {
"id": "82de0b044094f0c67893ac9fe64f1a99",
"message": "Completed at 2018-03-08 10:07:04 +0000",
"progress": 2,
"results": [
{
"action": "update",
"id": 244,
"status": "Updated",
"success": true
},
{
"action": "update",
"id": 245,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"
}
}
Show User
GET /api/v2/users/{user_id}
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
user_id | integer | Path | true | The ID of the user |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"user": {
"id": 35436,
"name": "Johnny Agent"
}
}
Update User
PUT /api/v2/users/{user_id}
Specifying email and verified attributes
- If both
email
andverified
attributes are provided, the provided email is added to the user as a secondary email with theverified
property set to the specified value. The primary email remains unmodified - If only
email
is provided, the provided email is added to the user as a secondary email with theverified
property set property set to false. The primary email remains unmodified - If only
verified
is provided, theverified
property of the primary email identity is set to the given value
Suspending a user
You can suspend a user by setting its suspended
attribute to true.
When a user is suspended, the user is not allowed to sign in to Help Center and all further tickets are suspended.
Updating a user's profile image
You can update a user's profile image by uploading a local file or by referring to an image hosted on a different website. The second option may take a few minutes to process.
Allowed For
- Agents, with restrictions on certain actions
Agents can only update end users. Administrators can update end users, agents, and administrators.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
user_id | integer | Path | true | The ID of the user |
Example Body
{
"user": {
"name": "Roger Wilco II"
}
}
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}.json \
-d '{"user": {"name": "Roger Wilco II"}}' \
-H "Content-Type: application/json" -X PUT \
-v -u {email_address}:{password}
# Suspending an user
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}.json \
-d '{"user": {"suspended": true}}' \
-H "Content-Type: application/json" -X PUT \
-v -u {email_address}:{password}
# Uploading a local file to user
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}.json \
-F "user[photo][uploaded_data][email protected]/path/to/profile/image.jpg" \
-v -u {email_address}:{password} -X PUT
# Setting a remote image URL:
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}.json \
-d '{"user": {"remote_photo_url": "http://link.to/profile/image.png"}}' \
-H "Content-Type: application/json" \
-v -u {email_address}:{password} -X PUT
Example Response
Status 200 OK
{
"user": {
"id": 9873843,
"name": "Roger Wilco II"
}
}
Delete User
DELETE /api/v2/users/{user_id}
Deletes the user and associated records from the account.
Warning: Deleted users are not recoverable.
To comply with GDPR, a further step is needed. See Permanently Delete User.
Allowed For
- Agents, with restrictions on certain actions
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
user_id | integer | Path | true | The ID of the user |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}.json \
-v -u {email_address}:{password} \
-X DELETE
Example Response
Status 200 OK
{
"user": {
"active": false,
"id": 9873843,
"name": "Roger Wilco II"
}
}
Show Compliance Deletion Statuses
GET /api/v2/users/{user_id}/compliance_deletion_statuses
Returns the GDPR status for each user per area of compliance. A Zendesk area of compliance is typically a product like "support/explore" but can be more fine-grained for areas within the product lines.
If the user is not in the account, the request returns a 404 status.
Status: 404 { "error":"RecordNotFound", "description":"Not found" }
Allowed For
- Agents, with restrictions
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
application | string | Query | false | Area of compliance |
user_id | integer | Path | true | The ID of the user |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/{id}/compliance_deletion_statuses.json?application=chat \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"compliance_deletion_statuses": [
{
"account_subdomain": "accountABC",
"action": "request_deletion",
"application": "all",
"created_at": "2009-07-20T22:55:23Z",
"executer_id": 2000,
"user_id": 1
},
{
"account_subdomain": "accountABC",
"action": "started",
"application": "support",
"created_at": "2009-07-20T22:55:29Z",
"executer_id": null,
"user_id": 1
},
{
"account_subdomain": "accountABC",
"action": "complete",
"application": "support",
"created_at": "2009-07-20T22:57:02Z",
"executer_id": null,
"user_id": 1
},
{
"account_subdomain": "accountABC",
"action": "started",
"application": "chat",
"created_at": "2009-07-21T02:51:18Z",
"executer_id": null,
"user_id": 1
}
]
}
Merge End Users
PUT /api/v2/users/{user_id}/merge
Merges the end user specified in the path parameter into the existing end user specified in the request body.
Any two end users can be merged with the exception of end users created by sharing agreements.
Agents and admins cannot be merged.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
user_id | integer | Path | true | The ID of the user |
Example Body
{
"user": {
"id": 1234
}
}
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/merge.json \
-d '{"user": {"id": 1234}}' \
-H "Content-Type: application/json" -X PUT \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"user": {
"id": 35436,
"name": "Johnny Agent"
}
}
Show User Related Information
GET /api/v2/users/{user_id}/related
JSON Format
The JSON returned by this endpoint includes the following properties.
Note: Depending on the user's permissions, the count results may not match the actual number of tickets returned.
Name | Type | Comment |
---|---|---|
assigned_tickets | integer | Count of assigned tickets |
requested_tickets | integer | Count of requested tickets |
ccd_tickets | integer | Count of collaborated tickets |
organization_subscriptions | integer | Count of organization subscriptions |
It also includes the following additional properties about the Web portal, the self-help solution offered by Zendesk before Help Center. The Web portal is deprecated but the API still returns data about the user's activity if they used it. See the Help Center API to get comparable data for Help Center. Articles, posts, comments, subscriptions, and votes each have a list-by-user endpoint.
Name | Type | Comment |
---|---|---|
topics | integer | Count of topics (Web portal only) |
topic_comments | integer | Count of comments on topics (Web portal only) |
votes | integer | Count of votes (Web portal only) |
subscriptions | integer | Count of subscriptions (Web portal only) |
entry_subscriptions | integer | Count of entry subscriptions (Web portal only) |
forum_subscriptions | integer | Count of forum subscriptions (Web portal only) |
Allowed For:
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
user_id | integer | Path | true | The ID of the user |
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/related.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"user_related": {
"assigned_tickets": 5,
"ccd_tickets": 3,
"entry_subscriptions": 1,
"forum_subscriptions": 2,
"organization_subscriptions": 1,
"requested_tickets": 10,
"subscriptions": 4,
"topic_comments": 7,
"topics": 2,
"votes": 3
}
}