Articles

Organizations

Permission Groups

Sections

Ticket Comments

POST requests only. Users to add as cc's when creating a ticket. See Setting Collaborators

Tickets

User Segments

Whether or not the user is a chat-only agent

A custom role if the user is an agent on the Enterprise plan or above

Any details you want to store about the user, such as an address

The user's primary email address. *Writeable on create only. On update, a secondary email is added. See Email Address

A unique identifier from another system. The API treats the id as case insensitive. Example: "ian1" and "IAN1" are the same value.

Automatically assigned when the user is created

Last time the user signed in to Zendesk Support or made an API request using an API token or basic authentication

Designates whether the user has forum moderation capabilities

Any notes you want to store about the user

true if the user can only create private comments

The id of the user's organization. If the user has more than one organization memberships, the id of the user's default organization. If updating, see Organization ID

The user's primary phone number. See Phone Number below

The user's profile picture represented as an Attachment object

A URL pointing to the user's profile picture.

This parameter is inert and has no effect. It may be deprecated in the future. Previously, this parameter determined whether a user could access a CSV report in a legacy Guide dashboard. This dashboard has been removed. See Announcing Guide legacy reporting upgrade to Explore

If the agent has any restrictions; false for admins and unrestricted agents, true for other agents

The user's role. Possible values are "end-user", "agent", or "admin"

The user's role id. 0 for a custom agent, 1 for a light agent, 2 for a chat agent, 3 for a chat agent added to the Support account as a contributor (Chat Phase 4), 4 for an admin, and 5 for a billing admin

If the user is shared from a different Zendesk Support instance. Ticket sharing accounts only

If the user is a shared agent from a different Zendesk Support instance. Ticket sharing accounts only

Whether the phone number is shared or not. See Phone Number below

The user's signature. Only agents and admins can have signatures

If the agent is suspended. Tickets from suspended users are also suspended, and these users cannot sign in to the end user portal

Specifies which tickets the user has access to. Possible values are: "organization", "groups", "assigned", "requested", null. "groups" and "assigned" are valid only for agents. If you pass an invalid value to an end user (for example, "groups"), they will be assigned to "requested", regardless of their previous access

Values of custom fields in the user's profile. See User Fields

Any of the user's identities is verified. See User Identities

User Fields

Users

Zendesk

Shows the settings that are available for the account.

#### Allowed For

* Agents


Show Settings

Updates settings for the account. See [JSON Format](#json-format) above for the settings you can update.

#### Allowed For

* Admins


Update Account Settings

Create Trial Account

Zendesk Support credentials are not required to access this endpoint. You can use any Zendesk Support subdomain.

Returns "true" if the subdomain is available.


Verify Subdomain Availability

Lists ticket activities in the last 30 days affecting the agent making the request.
Also sideloads the following arrays of user records:

- actors - All actors involved in the listed activities
- users - All users involved in the listed activities

#### Pagination

- Cursor pagination (recommended)
- Offset pagination

See [Pagination](/api-reference/introduction/pagination/).

Returns a maximum of 100 records per page.

#### Allowed For

* Agents


List Activities

Lists a specific activity.

#### Allowed For

* Agents


Show Activity

Returns an approximate count of ticket activities in the last 30 days affecting the agent making the request. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours.

The `count[refreshed_at]` property is a timestamp that indicates 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

Count Activities

Shows attachment details. You can get the value of the `attachment_id` parameter by listing the ticket's comments.
See [List Comments](/api-reference/ticketing/tickets/ticket_comments/#list-comments). Each comment
in the list has an `attachments` list that specifies an `id` for each attachment.


 #### Allowed for

 * Agents


Show Attachment

Toggles enabling or restricting agent access to attachments with detected malware.

#### Allowed For

* Admins


Update Attachment for Malware

#### Allowed For

* Admins on accounts that have audit log access

#### Pagination

* Cursor pagination (recommended)
* Offset pagination

See [Pagination](/api-reference/introduction/pagination/).

Returns a maximum of 100 records per page.


List Audit Logs

#### Allowed For

* Admins on accounts that have audit-log access


Show Audit Log

#### Allowed For

* Admins on accounts that have audit log access


Export Audit Logs

Lists all automations for the current account.

#### Allowed For

* Agents

#### Available Parameters

You can pass in any combination of the following optional filters:

| Name       | Type    | Comment
| ---------- | ------- | -------
| active     | boolean | Only active automations if true, inactive automations if false
| sort_by    | string  | Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". Defaults to "position"
| sort_order | string  | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others

#### Sideloads

The following sideloads are supported. The usage sideloads are only supported on the Support Professional or Suite Growth plan or above.

| Name             | Will sideload
| ---------------- | -------------
| app_installation | The app installation that requires each automation, if present
| permissions      | The permissions for each automation
| usage_1h         | The number of times each automation has been used in the past hour
| usage_24h        | The number of times each automation has been used in the past day
| usage_7d         | The number of times each automation has been used in the past week
| usage_30d        | The number of times each automation has been used in the past thirty days

#### Pagination

- Cursor pagination (recommended)
- Offset pagination

See [Pagination](/api-reference/introduction/pagination/).

Returns a maximum of 100 records per page.


List Automations

Creates an automation.

New automations must be unique and have at least one condition that is true only once or an action that nullifies at least one of the conditions. Active automations can have overlapping conditions but can't be identical.

The request must include the following conditions in the `all` array:

- At least one time-based condition
- At least one condition that checks one of the following fields: `status`, `type`, `group_id`, `assignee_id`, or `requester_id`.

#### Allowed For

* Agents


Create Automation

Lists all active automations.

#### Allowed For

* Agents

#### Available Parameters

You can pass in any combination of the following optional filters:

| Name       | Type   | Comment
| ---------- | ------ | -------
| sort_by    | string | Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". Defaults to "position"
| sort_order | string | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others

#### Sideloads

The following sideloads are supported:

| Name             | Will sideload
| ---------------- | -------------
| app_installation | The app installation that requires each automation, if present
| permissions      | The permissions for each automation
| usage_1h         | The number of times each automation has been used in the past hour
| usage_24h        | The number of times each automation has been used in the past day
| usage_7d         | The number of times each automation has been used in the past week
| usage_30d        | The number of times each automation has been used in the past thirty days


List Active Automations

Deletes the automations corresponding to the provided comma-separated list of IDs.

**Note**: You might be restricted from deleting some default automations. If included in a bulk deletion, the unrestricted automations will be deleted.

#### Allowed For

* Agents

#### Request Parameters

The DELETE request takes one parameter, an `ids` object that lists the automations to delete.

| Name | Description
| ---- | -----------
| ids  | The IDs of the automations to delete

#### Example request

```js
{
  "ids": "25,23,27,22"
}
```


Bulk Delete Automations

#### Pagination

* Offset pagination only

See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination).

#### Allowed For

* Agents

#### Sideloads

The following sideloads are supported. For more information, see [Side-loading](/documentation/ticketing/using-the-zendesk-api/side_loading/).

| Name             | Will sideload
| ---------------- | -------------
| app_installation | The app installation that requires each automation, if present
| permissions      | The permissions for each automation
| usage_1h         | The number of times each automation has been used in the past hour
| usage_24h        | The number of times each automation has been used in the past day
| usage_7d         | The number of times each automation has been used in the past week
| usage_30d        | The number of times each automation has been used in the past thirty days


Search Automations

**Note**: You might be restricted from updating some default automations. If included in a bulk update, the unrestricted automations will be updated.

#### Allowed For

* Agents

#### Request Parameters

The PUT request expects an `automations` object that lists the automations to update.

Each automation may have the following properties:

| Name     | Mandatory | Description
| -------- | --------- | -----------
| id       | yes       | The ID of the automation to update
| position | no        | The new position of the automation
| active   | no        | The active status of the automation (true or false)

#### Example Request

```js
{
  "automations": [
    {"id": 25, "position": 3},
    {"id": 23, "position": 5},
    {"id": 27, "position": 9},
    {"id": 22, "position": 7}
  ]
}
```


Update Many Automations

Show Automation

Updates an automation.

Updated automations must be unique and have at least one condition that is true only once or an action that nullifies at least one of the conditions. Active automations can have overlapping conditions but can't be identical.

The request must include the following conditions in the `all` array:
- At least one time-based condition
- At least one condition that checks one of the following fields: 'status', 'type', 'group_id', 'assignee_id', or 'requester_id'

**Note**: Updating a condition or action updates both the `conditions` and `actions` arrays, clearing all existing values of both arrays. Include all your conditions and actions when updating any condition or action.
**Note**: You might be restricted from updating some default automations.

#### Allowed For

* Agents


Update Automation

**Note**: You might be restricted from deleting some default automations.

#### Allowed For

* Agents


Delete Automation

List Bookmarks

Create Bookmark

#### Allowed For
- Agents (own bookmarks only)

If the bookmark already exists with a specified ticket id, the response status will be `http Status: 200 OK`.

Delete Bookmark

Returns a list of all brands for your account sorted by name.

#### Allowed for

* Admins, Agents

List Brands

Create Brand

Returns a JSON object determining whether a host mapping is valid for a given subdomain.

#### Allowed for

* Admins

Check Host Mapping Validity

Returns a brand for your account.

#### Allowed for

* Admins, Agents

Show a Brand

Returns an updated brand.

#### Allowed for
* Admins

#### Updating a Brand's Image
A brand image can be updated by uploading a local file using the update brand endpoint. See the **Using curl** sections below for more information.

Update a Brand

Deletes a brand.

#### Allowed for
- Admins

Delete a Brand

Returns a JSON object determining whether a host mapping is valid for the given brand.

#### Allowed for
- Admins

Check Host Mapping Validity for an Existing Brand

#### Allowed For
* Agents

### Creating tickets

#### Introduction

Creating tickets using Talk Partner Edition follows the same conventions as the Create Ticket endpoint. See [Create Ticket](/api-reference/ticketing/tickets/tickets/#create-ticket).

#### Request parameters

The POST request takes a mandatory `ticket` object that lists the values to set when the ticket is created.
You may also include an optional `display_to_agent` value such as the ID of the agent that will see the newly created ticket.

Tickets created using this endpoint must have a `via_id` parameter. See the following
section for possible values.

#### Zendesk Talk Integration Via IDs

Tickets created using this endpoint must have one of the following `via_id` parameters:

| ID       | Description
| ---------| -------------
| 44       | Voicemail
| 45       | Phone call (inbound)
| 46       | Phone call (outbound)

### Creating voicemail tickets
#### Request parameters

The POST request takes a mandatory `ticket` object that lists the values to set when the ticket is created.
The ticket must have a `voice_comment` with the following values:

| Name               | Type                  | Comment
| ------------------ | ----------------------| -------
| from               | string                | Incoming phone number
| to                 | string                | Dialed phone number
| recording_url      | string                | URL of the recording
| started_at         | date                  | [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) timestamp of the call starting time
| call_duration      | integer               | Duration in seconds of the call
| answered_by_id     | integer               | The agent who answered the call
| transcription_text | string                | Transcription of the call (optional)
| location           | string                | Location of the caller (optional)

Create Ticket or Voicemail Ticket

Allows you to instruct an agent's browser to open a ticket.

When the message is successfully delivered to an agent's browser:

```http
Status: 200 OK
```

When `agent_id` or `ticket_id` is invalid:

```http
Status: 404 Not Found
```

#### Allowed For
* Agents

Open Ticket in Agent's Browser

Allows you to instruct an agent's browser to open a user's profile.

When the message is successfully delivered to an agent's browser:

```http
Status: 200 OK
```

When `agent_id` or `ticket_id` is invalid:

```http
Status: 404 Not Found
```

#### Allowed For
* Agents

Open a User's Profile in an Agent's Browser

#### Availability

* Accounts on the Enterprise plan or above

#### Allowed For

* Agents


List Custom Roles

#### Availability

* Accounts on the Enterprise plan or above

#### Allowed For

* Administrators


Create Custom Role

Show Custom Role

#### Availability

* Accounts on the Enterprise plan or above

#### Allowed Forx

* Administrators


Update Custom Role

Delete Custom Role

Lists all undeleted custom ticket statuses for the account. No pagination is provided.

You can't have more than 300 custom ticket statuses at a time.

#### Allowed For

* End Users


List Custom Ticket Statuses

Takes a `custom_status` object that specifies the custom ticket status properties to create.

#### Allowed For

* Admins


Create Custom Ticket Status

Returns the custom ticket status object.

#### Allowed For

* End Users


Show Custom Ticket Status

Takes a `custom_status` object that specifies the properties to update.

#### Allowed For

* Admins


Update Custom Ticket Status

Returns a maximum of 100 deleted tickets per page. See [Pagination](/api-reference/introduction/pagination/).

The results includes all deleted (and not yet archived) tickets that
have not yet been [scrubbed](https://support.zendesk.com/hc/en-us/articles/4408845703194#topic_fv5_w51_sdb) in the past 30 days. Archived tickets are
not included in the results. See [About archived tickets](https://support.zendesk.com/hc/en-us/articles/203657756)
in the Support Help Center.

The tickets are ordered chronologically by created date, from oldest to newest.
The first ticket listed may not be the oldest ticket in your
account due to [ticket archiving](https://support.zendesk.com/hc/en-us/articles/203657756).

#### Pagination

- Cursor pagination (recommended)
- Offset pagination

See [Pagination](/api-reference/introduction/pagination/).

Returns a maximum of 100 records per page.

#### Allowed For

* Agents

#### Rate Limit

You can make 10 requests every 1 minute using this endpoint.
When making requests beyond page 100, you can make 5 requests every 1 minute.
The rate limiting mechanism behaves as described in
[Monitoring your request activity](/api-reference/ticketing/account-configuration/usage_limits/#monitoring-your-request-activity) in the API introduction.

List deleted tickets

Permanently deletes up to 100 soft-deleted tickets. See [Soft delete](https://support.zendesk.com/hc/en-us/articles/4408834005530#topic_zrm_wbj_1db)
in the Zendesk GDPR docs. To soft delete tickets, use the [Bulk Delete Tickets](#bulk-delete-tickets) endpoint.

This endpoint accepts a comma-separated list of up to 100 ticket ids. It enqueues
a ticket deletion job and returns a payload with the jobs status.

If one ticket fails to be deleted, the endpoint still attempts to delete the others. If the job succeeds,
the tickets that were successfully deleted are permanently deleted. This operation can't be undone.

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.

#### Allowed For

* Agents

Delete multiple tickets permanently

Restore previously deleted tickets in bulk

Permanently deletes a soft-deleted ticket. See [Soft delete](https://support.zendesk.com/hc/en-us/articles/4408834005530#topic_zrm_wbj_1db)
in the Zendesk GDPR docs. To soft delete a ticket, use the [Delete Ticket](#delete-ticket) endpoint.

This endpoint enqueues a ticket deletion job and returns a payload with the jobs status.

If the job succeeds, the ticket is permanently deleted. This operation can't be undone.

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.

#### Allowed For

* Agents

Delete ticket permanently

Restore a previously deleted ticket

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


List Deleted Users

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


Count Deleted Users

Returns users that have been deleted but not permanently yet. See [Permanently Delete User](#permanently-delete-user).

#### Allowed For:

* Agents


Show Deleted User

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

* Agents, with restrictions on certain actions


Permanently Delete User

Returns all the variants of the specified dynamic content item.

#### Allowed For

* Admins
* Agents who have permission to manage dynamic content


List Variants

You can only create one variant for each locale id. If a locale variant already exists, the request is rejected.

#### Allowed For

* Admins, Agents


Create Variant

Create Many Variants

Updates one or more variants. See [Update Variant](/api-reference/ticketing/ticket-management/dynamic_content_item_variants/#update-variant).

You must specify the variants by id in the body. To get the variant ids, see [List Variants](/api-reference/ticketing/ticket-management/dynamic_content_item_variants/#list-variants).

#### Allowed For

* Admins, Agents


Update Many Variants

Show Variant

Updates the specified variant. You don't need to include all the properties. If you just want to update content, for example, then include just that.

You can't switch the active state of the default variant of an item. Similarly, you can't switch the default to false if the variant is the default. You must make another variant default instead.

#### Allowed For

* Admins, Agents


Update Variant

Delete Variant

Returns a list of all dynamic content items for your account if accessed as an admin or agents who have permission to manage dynamic content.

#### Allowed For

* Admins, Agents


List Items

Create a new content item, with one or more variants in the item's `variants` array. See [Specifying item variants](#specifying-item-variants).

The `default_locale_id` and variant `locale_id` values must be one of the locales the account has active. You can get the list with the [List Locales](/api-reference/ticketing/account-configuration/locales/#list-locales) endpoint.

#### Allowed For

* Admins, Agents


Create Item

#### Stability

* Development

#### Allowed For

* Admins, Agents


Show Many Items

Show Item

The only attribute you can change is the name.

To add a variant to the item, or to update or delete the variants of the item, use the [Item Variants API](/api-reference/ticketing/ticket-management/dynamic_content_item_variants/#update-many-variants).

#### Allowed For

* Admins, Agents


Update Item

Delete Item

#### Pagination

* Cursor pagination (recommended)
* Offset pagination

See [Pagination](/api-reference/introduction/pagination/).

Returns a maximum of 100 records per page.

#### Allowed For:

* Agents


List Memberships

Assigns an agent to a given group.

#### Allowed For

* Admins


Create Membership

Returns a maximum of 100 group memberships per page.

#### Pagination

* Cursor pagination (recommended)
* Offset pagination

See [Pagination](/api-reference/introduction/pagination/).

Returns a maximum of 100 records per page.

#### Allowed For:

* Agents


List Assignable Memberships

Assigns up to 100 agents to given groups.

#### 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.


Bulk Create Memberships

Immediately removes users from groups and schedules a job to unassign all working tickets that are assigned to the given user and group combinations.

#### Allowed For

* Admins


Bulk Delete Memberships

The 'id' is the group membership id, not a group id.

#### Allowed For

* Agents


Show Membership

Immediately removes a user from a group and schedules a job to unassign all working tickets that are assigned to the given user and group combination.

#### Allowed For

* Admins


Delete Membership

#### Pagination

* Cursor pagination (recommended)
* Offset pagination

See [Pagination](/api-reference/introduction/pagination/).

Returns a maximum of 100 records per page.

#### Allowed For

* Admins
* Agents


List Groups

Create Group

List Assignable Groups

Returns an approximate count of groups. If the count exceeds 100,000, it is updated every 24 hours.

The `refreshed_at` property of the `count` object is a timestamp that indicates when the count was last updated.

**Note**: When the count exceeds 100,000, `refreshed_at` may occasionally be null. This indicates that the count is being updated in the background, and the `value` property of the `count` object is limited to 100,000 until the update is complete.

#### Allowed For

* Admins
* Agents


Count Groups

Show Group

Update Group

Delete Group

Ticket Import

Accepts an array of up to 100 ticket objects.

#### Allowed For

* Admins

Ticket Bulk Import

Returns a stream of changes that occurred on routing attribute values.

#### Allowed For

* Admins

#### Parameters

Optional

| Name   | Type   | Comment
| ------ | ------ | -------
| cursor | string | The `cursor` parameter is a non-human-readable argument you can use to move forward or backward in time. The cursor is a read-only URL parameter that's only available in API responses. See [Pagination](#pagination).


Zendesk API Integration Profile

Allowed For

Allowed For

Allowed For

Allowed For

Allowed For

Allowed for

Allowed For

Allowed For

Supercharge your product integrations today