openapi: 3.1.0
info:
version: '1.0'
title: Zendesk Account Account Settings Users API
description: Needs a description.
tags:
- name: Users
paths:
/api/v2/users/autocomplete:
get:
operationId: AutocompleteUsers
tags:
- Users
summary: Zendesk Get Api V2 Users Autocomplete
description: '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: name
in: query
description: 'The name to search for the user.
'
required: true
schema:
type: string
example: gil
- $ref: '#/components/parameters/LookupRelationshipAutocompleteFieldIdFragment'
- $ref: '#/components/parameters/LookupRelationshipAutocompleteSourceFragment'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/UsersResponse'
examples:
default:
$ref: '#/components/examples/SearchUsersResponseExample'
/api/v2/deleted_users:
get:
operationId: ListDeletedUsers
tags:
- Users
summary: Zendesk Get Api V2 Deleted_users
description: '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](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Agents
'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/DeletedUsersResponse'
examples:
default:
$ref: '#/components/examples/DeletedUsersResponseExample'
/api/v2/deleted_users/{deleted_user_id}:
parameters:
- $ref: '#/components/parameters/DeletedUserId'
get:
operationId: ShowDeletedUser
tags:
- Users
summary: Zendesk Get Api V2 Deleted_users Deleted_user_id
description: 'Returns users that have been deleted but not permanently yet. See [Permanently Delete User](#permanently-delete-user).
#### Allowed For:
* Agents
'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/DeletedUserResponse'
examples:
default:
$ref: '#/components/examples/DeletedUserResponseExample'
delete:
operationId: PermanentlyDeleteUser
tags:
- Users
summary: Zendesk Delete Api V2 Deleted_users Deleted_user_id
description: 'Before permanently deleting a user, you must delete the user first. See [Delete User](/api-reference/ticketing/users/users/#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](/api-reference/introduction/rate-limits/#monitoring-your-request-activity) in the API introduction.
Zendesk recommends that you obey the Retry-After header values.
#### Allowed For
* Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage end users or team members
'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/DeletedUserResponse'
examples:
default:
$ref: '#/components/examples/DeletedUserResponseExample'
/api/v2/deleted_users/count:
get:
operationId: CountDeletedUsers
tags:
- Users
summary: Zendesk Get Api V2 Deleted_users Count
description: '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
'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CountResponse'
examples:
default:
$ref: '#/components/examples/DeletedUsersCountResponseExample'
/api/v2/users/search:
get:
operationId: SearchUsers
tags:
- Users
summary: Zendesk Get Api V2 Users Search
description: 'Returns an array of users who meet the search criteria.
Returns up to 100 records per page to a maximum of 10,000 records per query. See [Using offset pagination](/api-reference/introduction/pagination/#using-offset-pagination).
#### Pagination
* Offset pagination only
See [Using Offset Pagination](/api-reference/introduction/pagination/#using-offset-pagination).
#### Allowed For
* Agents
'
parameters:
- name: query
in: query
description: '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](/api-reference/ticketing/ticket-management/search/).
'
schema:
type: string
example: jdoe
- name: external_id
in: query
description: 'The `external_id` parameter does not support the search syntax. It only accepts ids.
'
schema:
type: string
example: abc124
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/UsersResponse'
examples:
default:
$ref: '#/components/examples/SearchUsersResponseExample'
/api/v2/users:
get:
operationId: ListUsers
tags:
- Users
summary: Zendesk Get Api V2 Users
description: '#### Pagination
* Cursor pagination (recommended)
* Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Admins, Agents and Light Agents
'
parameters:
- $ref: '#/components/parameters/UserRoleFilter'
- $ref: '#/components/parameters/UserRolesFilter'
- $ref: '#/components/parameters/UserPermissionSetFilter'
- $ref: '#/components/parameters/UserExternalIdFilter'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/UsersResponse'
examples:
default:
$ref: '#/components/examples/UsersResponseExample'
post:
operationId: CreateUser
tags:
- Users
summary: Zendesk Post Api V2 Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserRequest'
examples:
default:
$ref: '#/components/examples/UserRequestExample'
responses:
'201':
description: Created response
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
examples:
default:
$ref: '#/components/examples/UserCreateResponseExample'
/api/v2/users/{user_id}:
parameters:
- $ref: '#/components/parameters/UserId'
get:
operationId: ShowUser
tags:
- Users
summary: Zendesk Get Api V2 Users User_id
description: '#### Allowed For
* Agents
'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
examples:
default:
$ref: '#/components/examples/UserResponseExample'
put:
operationId: UpdateUser
tags:
- Users
summary: Zendesk Put Api V2 Users User_id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserRequest'
examples:
default:
$ref: '#/components/examples/UpdateUserRequestExample'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
examples:
default:
$ref: '#/components/examples/UpdateUserResponseExample'
delete:
operationId: DeleteUser
tags:
- Users
summary: Zendesk Delete Api V2 Users User_id
description: 'Deletes the user and associated records from the account.
**Warning**:
* Deleted users are not recoverable.
* Both agents and administrators can soft delete users in the agent interface in Zendesk Support. Agents with permission can delete end users, while administrators can delete all users except the account owner.
To comply with GDPR, a further step is needed. See [Permanently Delete User](/api-reference/ticketing/users/users/#permanently-delete-user).
#### Allowed For
* Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage end users or team members
'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
examples:
default:
$ref: '#/components/examples/DeleteUserResponseExample'
/api/v2/users/{user_id}/compliance_deletion_statuses:
parameters:
- $ref: '#/components/parameters/UserId'
get:
operationId: ShowUserComplianceDeletionStatuses
tags:
- Users
summary: Zendesk Get Api V2 Users User_id Compliance_deletion_statuses
description: "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.\n\nIf the user is not in the account, the request returns a 404 status.\n\n```http\nStatus: 404\n{\n \"error\":\"RecordNotFound\",\n \"description\":\"Not found\"\n}\n```\n\n#### Allowed For\n\n* Agents, with restrictions\n\n#### Pagination\n\n* Cursor pagination (recommended)\n* Offset pagination\n\nSee [Pagination](/api-reference/introduction/pagination/).\n"
parameters:
- name: application
in: query
description: Area of compliance
schema:
type: string
example: chat
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ComplianceDeletionStatusesResponse'
examples:
default:
$ref: '#/components/examples/ComplianceDeletionStatusesResponseExample'
/api/v2/users/{user_id}/merge:
parameters:
- $ref: '#/components/parameters/UserId'
put:
operationId: MergeEndUsers
tags:
- Users
summary: Zendesk Put Api V2 Users User_id Merge
description: '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.
To be eligible for merging, the user in the path parameter must be a requester on 10,000 or fewer tickets. Otherwise, the merge will be blocked.
Agents, admins, and users with more than 10,000 requested tickets cannot be merged.
For more information about how user data is merged, see [Merging a user''s duplicate account](https://support.zendesk.com/hc/en-us/articles/4408887695898) in Zendesk help.
#### Allowed For
* Admins or agents with permission to edit end users
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserRequest'
examples:
default:
$ref: '#/components/examples/MergeEndUsersRequestExample'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
examples:
default:
$ref: '#/components/examples/UserResponseExample'
/api/v2/users/{user_id}/related:
parameters:
- $ref: '#/components/parameters/UserId'
get:
operationId: ShowUserRelated
tags:
- Users
summary: Zendesk Get Api V2 Users User_id Related
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/UserRelatedResponse'
examples:
default:
$ref: '#/components/examples/UserRelatedResponseExample'
/api/v2/users/count:
get:
operationId: CountUsers
tags:
- Users
summary: Zendesk Get Api V2 Users Count
description: '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:
- $ref: '#/components/parameters/UserRoleFilter'
- $ref: '#/components/parameters/UserRolesFilter'
- $ref: '#/components/parameters/UserPermissionSetFilter'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CountResponse'
examples:
default:
$ref: '#/components/examples/UserCountResponseExample'
/api/v2/users/create_many:
post:
operationId: CreateManyUsers
tags:
- Users
summary: Zendesk Post Api V2 Users Create_many
description: 'Accepts an array of up to 100 user objects.
**Note**: To protect the data in your Zendesk account, bulk user imports are not enabled by default in Zendesk accounts. The account owner must contact [Zendesk Customer Support](https://support.zendesk.com/hc/en-us/articles/4408843597850) to enable the imports. A 403 Forbidden
error is returned if data imports are not enabled.
#### Allowed For
* Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage end users or team members
#### 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](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job''s completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UsersRequest'
examples:
default:
$ref: '#/components/examples/UsersCreateManyRequestExample'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/JobStatusResponse'
examples:
default:
$ref: '#/components/examples/JobStatusResponseExample'
/api/v2/users/create_or_update:
post:
operationId: CreateOrUpdateUser
tags:
- Users
summary: Zendesk Post Api V2 Users Create_or_update
description: '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 `"skip_verify_email": true` property in the body.
#### External ID Case Sensitivity
When providing an external id to identify an existing user to update, the search for the user record is not case sensitive.
However, if an existing user is found, the system will update the user''s external id to match the case of the external id used to find the user.
#### 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
* Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage end users or team members
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserRequest'
examples:
default:
$ref: '#/components/examples/UserRequestExample'
responses:
'200':
description: Successful response, when user exits
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
examples:
default:
$ref: '#/components/examples/UserCreateResponseExample'
'201':
description: Created response, when user is new
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
examples:
default:
$ref: '#/components/examples/UserCreateResponseExample'
/api/v2/users/create_or_update_many:
post:
operationId: CreateOrUpdateManyUsers
tags:
- Users
summary: Zendesk Post Api V2 Users Create_or_update_many
description: "Accepts an array of up to 100 user objects. For each user, the user is created if it does not\nalready exist, or the existing user is updated.\n\n**Note**: To protect the data in your Zendesk account, bulk user imports are not enabled by default in Zendesk accounts. The account owner must contact [Zendesk Customer Support](https://support.zendesk.com/hc/en-us/articles/4408843597850) to enable the imports. A 403 Forbidden\nerror is returned if data imports are not enabled. \n\nEach individual user object can identify an existing user by `email` or by `external_id`.\n\nThis endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information.\n\n#### Allowed For\n\n* Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage end users or team members\n"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UsersRequest'
examples:
default:
$ref: '#/components/examples/UsersRequestExample'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/JobStatusResponse'
examples:
default:
$ref: '#/components/examples/JobStatusResponseExample'
/api/v2/users/destroy_many:
delete:
operationId: DestroyManyUsers
tags:
- Users
summary: Zendesk Delete Api V2 Users Destroy_many
description: 'Accepts a comma-separated list of up to 100 user ids.
The request takes an `ids` or an `external_ids` query parameter.
#### Allowed for
- Admins
#### Response
This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job''s completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information.
'
parameters:
- name: ids
in: query
description: Id of the users to delete. Comma separated
schema:
type: string
example: 1,2,3
- name: external_ids
in: query
description: External Id of the users to delete. Comma separated
schema:
type: string
example: abc,def,ghi
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/JobStatusResponse'
examples:
default:
$ref: '#/components/examples/JobStatusBulkDeleteResponseExample'
/api/v2/users/logout_many:
post:
operationId: LogoutManyUsers
tags:
- Users
summary: Zendesk Post Api V2 Users Logout_many
description: 'Accepts a comma-separated list of up to 100 user ids.
#### Allowed For:
* Admins
'
parameters:
- name: ids
in: query
description: 'Accepts a comma-separated list of up to 100 user ids.
'
schema:
type: string
example: 1,2
responses:
'202':
description: Accepted response
content:
application/json:
schema:
type: string
description: Empty response
example: ''
example: ''
/api/v2/users/me:
get:
operationId: ShowCurrentUser
tags:
- Users
summary: Zendesk Get Api V2 Users Me
description: "The endpoint returns [user information](/api-reference/ticketing/users/users/) and an `authenticity_token`. \n\n#### Allowed For\n\n* Anonymous users\n\n#### Authenticity Token\n\nZendesk API calls made by end users from a Zendesk help center must include `authenticity_token` in the `X-CSRF-Token` HTTP header. This helps prevent [cross-site request forgery (CSRF)](https://en.wikipedia.org/wiki/Cross-site_request_forgery) attacks.\n\nFor an example using an authenticity token, see the AJAX request in the [Upgrading from Templating API v1](https://developer.zendesk.com/documentation/help_center/help-center-templates/v1#jquery) documentation.\n"
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CurrentUserResponse'
examples:
default:
$ref: '#/components/examples/CurrentUserResponseExample'
/api/v2/users/request_create:
post:
operationId: RequestUserCreate
tags:
- Users
summary: Zendesk Post Api V2 Users Request_create
description: 'Sends the owner a reminder email to update their subscription so more agents can be created.
#### Allowed For
* Agents
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserRequest'
examples:
default:
$ref: '#/components/examples/RequestUserCreateRequestExample'
responses:
'200':
description: description
content:
application/json:
schema:
type: string
description: Empty response
example: ''
example: ''
/api/v2/users/show_many:
get:
operationId: ShowManyUsers
tags:
- Users
summary: Zendesk Get Api V2 Users Show_many
description: 'Accepts a comma-separated list of up to 100 user ids or external ids.
#### Allowed For:
* Agents
'
parameters:
- name: ids
in: query
description: 'Accepts a comma-separated list of up to 100 user ids.
'
schema:
type: string
example: 1,2
- name: external_ids
in: query
description: 'Accepts a comma-separated list of up to 100 external ids.
'
schema:
type: string
example: abc,def
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/UsersResponse'
examples:
default:
$ref: '#/components/examples/ShowManyUsersResponseExample'
/api/v2/users/update_many:
put:
operationId: UpdateManyUsers
tags:
- Users
summary: Zendesk Put Api V2 Users Update_many
parameters:
- name: ids
in: query
description: Id of the users to update. Comma separated
schema:
type: string
example: 1,2,3
- name: external_ids
in: query
description: External Id of the users to update. Comma separated
schema:
type: string
example: abc,def,ghi
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UserRequest'
- $ref: '#/components/schemas/UsersRequest'
additionalProperties: true
examples:
default:
$ref: '#/components/examples/UpdateManyUsersRequestExample'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/JobStatusResponse'
examples:
default:
$ref: '#/components/examples/JobStatusResponseExample'
/users:
get:
operationId: listUsers
summary: Zendesk List Users
description: Returns a paginated list of all users in the account, including end users, agents, and admins. Supports filtering by role and permission set.
tags:
- Users
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/PerPageParam'
- name: role
in: query
description: Filter by user role.
schema:
type: string
enum:
- end-user
- agent
- admin
example: end-user
- name: permission_set
in: query
description: For custom roles, filter by the permission set ID.
schema:
type: integer
example: 10
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/User'
next_page:
type: string
format: uri
nullable: true
previous_page:
type: string
format: uri
nullable: true
count:
type: integer
examples:
Listusers200Example:
summary: Default listUsers 200 response
x-microcks-default: true
value:
users:
- id: abc123
url: https://www.example.com
name: Example Title
email: user@example.com
phone: example_value
photo:
id: abc123
file_name: example_value
content_url: https://www.example.com
content_type: example_value
size: 10
thumbnails: {}
locale_id: '500123'
locale: example_value
time_zone: example_value
organization_id: '500123'
role: end-user
custom_role_id: '500123'
verified: true
external_id: '500123'
tags:
- {}
alias: example_value
active: true
shared: true
shared_agent: true
shared_phone_number: true
signature: example_value
details: example_value
notes: example_value
restricted_agent: true
suspended: true
default_group_id: '500123'
report_csv: true
only_private_comments: true
ticket_restriction: organization
moderator: true
chat_only: true
two_factor_auth_enabled: true
user_fields: example_value
last_login_at: '2026-01-15T10:30:00Z'
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zendesk/refs/heads/main/openapi/zendesk-users-api-openapi.yml