Skip to content
Changelog

Report a bug

Zendesk integration: operations for AI agents

Zendesk connects to Type.com as an integration. This page lists the 672 operations documented for Claude and Codex in Type.com: 353 read, 122 write, 197 destructive.

About Zendesk

Zendesk Support API v2: 672 current authoritative endpoint references with explicit transport, authentication and account limits.

Categories: Sales & CRM

How to connect Zendesk to Type.com

Connect
Direct OAuth or composed email/token Basic credentials; managed Pipedream OAuth alternative.
Access
Organization connection: one shared account for the workspace.

To add the connection, follow the steps in Space connections.

Documented operations

672 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.

672 operations listed.

Lookup Relationships

  • Read

    Get sources by target

    Returns a list of source objects whose values are populated with the id of a related target object. For example, if you have a lookup field called "Success Manager" on a ticket, this endpoint can answer the question, "What tickets (sources) is this user (found by `target_type` and `target_id`) assigned as the 'Success Manager' (field referenced by `field_id`)?" This endpoint also resolves [multi-lookup fields](/api-reference/ticketing/lookup_relationships/lookup_relationships/#about-multi-lookup-relationship-fields). Pass the multi-lookup field's id as `field_id` and "zen:ticket" as `source_type` to list the tickets that reference a target record through the field. Multi-lookup reverse lookups are resolved through search, so tickets the requesting agent can't view are excluded. #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination For a multi-lookup `field_id`, only cursor pagination applies. Offset pagination parameters are ignored and the response uses cursor pagination. See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/{target_type}/{target_id}/relationship_fields/{field_id}/{source_type}

  • Read

    Filter Definitions

    Returns filter definitions based on the given target type. Target types include users (zen:user), tickets (zen:ticket), organizations (zen:organization), or custom objects (zen:custom_object:CUSTOM_OBJECT_KEY). The returned filter definitions are the options that you can use to build a custom field or ticket field's `relationship_filter`.

    GET /api/v2/relationships/definitions/{target_type}

Account Settings

  • Read

    Show Email Settings

    Returns the email settings for the account. #### Allowed For * Admins * Agents with extensions_and_channel_management permission

    GET /api/v2/account/email_settings

  • Read

    Show Settings

    Shows the settings that are available for the account. #### Allowed For * Agents

    GET /api/v2/account/settings

  • Destructive

    Update Email Settings

    Updates email settings for the account. #### Allowed For * Admins * Agents with extensions_and_channel_management permission

    PUT /api/v2/account/email_settings

  • Destructive

    Update Account Settings

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

    PUT /api/v2/account/settings

Reseller

  • Read

    Verify Subdomain Availability

    Zendesk Support credentials are not required to access this endpoint. You can use any Zendesk Support subdomain. Returns "true" if the subdomain is available.

    GET /api/v2/accounts/available

  • Write

    Create Trial Account

    Create Trial Account. See the pinned request/response schema and parameters for the authoritative contract.

    POST /api/v2/accounts

Activity Stream

  • Read

    List Activities

    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

    GET /api/v2/activities

  • Read

    Show Activity

    Lists a specific activity. #### Allowed For * Agents

    GET /api/v2/activities/{activity_id}

  • Read

    Count Activities

    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

    GET /api/v2/activities/count

Channel Framework

  • Read

    Validate Token

    #### Allowed For * Admins #### Request parameters The POST request takes a JSON object parameter which contains the token to be validated. | Name | Type | Required | Comments | ------------------ | ----------| --------- | ------------------- | instance_push_id | string | yes | The ID of the account to which data will be pushed. This was passed to the integration service when the administrator set up the account | request_id | string | no | A unique identifier for the push request #### Response format The response body is empty.

    POST /api/v2/any_channel/validate_token

  • Write

    Report Channelback Error to Zendesk

    #### Allowed For * Admins #### Request parameters The POST request takes a JSON object parameter which contains information about the problematic [channelback](/documentation/channel_framework/understanding-the-channel-framework/channelback/). | Name | Type | Required | Comments | ------------------ | ----------| --------- | ------------------- | instance_push_id | string | yes | The ID of the account to which data will be pushed. This was passed to the integration service when the administrator set up the account | external_id | string | yes | Unique identifier of the external resource from the original channelback (string) | description | string | no | A human readable description of the error | request_id | string | no | A unique identifier for the request #### Response format The response does not include a response body

    POST /api/v2/any_channel/channelback/report_error

  • Write

    Push Content to Support

    Pushes Channel framework content to Zendesk. #### Allowed For * Admins #### Request parameters The POST request takes a JSON object parameter which contains data about all the resources that the client is pushing. | Name | Type | Required | Comments | ------------------ | ----------| --------- | ------------------- | instance_push_id | string | yes | The account ID where data will be pushed. This was passed to the integration service when the administrator set up the account | request_id | string | no | A unique identifier for the push request | external_resources | array | yes | The [resources](#external_resource-object) to push #### external_resource object | Name | Type | Max length | Mandatory | Comments |------------------- | ---------------------------------- |------------| --------- | ---------- | external_id | string | 255 | yes | Unique identifier of the external resource. Must be ASCII characters | internal_note | boolean | | no | If true creates a new internal note comment | message | string | 65535 | yes | Text to be converted to a ticket or comment | html_message | string | 65535 | no | HTML version of message | parent_id | string | 511 | no | Unique identifier of the external resource for which this is a response. Used to choose the correct thread. Responses may include `parent_id` or `thread_id`, but not both. See [Conversation threads](/documentation/channel_framework/understanding-the-channel-framework/pull_endpoint/#conversation-threads) | thread_id | string | 255 | no | Arbitrary identifier of the thread to which this item should belong. Responses may include `parent_id` or `thread_id`, but not both. See [Conversation threads](/documentation/channel_framework/understanding-the-channel-framework/pull_endpoint/#conversation-threads) | created_at | string | | yes | When the resource was created in the origin system, as an ISO 8601 extended format date-time. Example: '2015-09-08T22:48:09Z' | author | object | | yes | See [author object](#author-object) below | display_info | array | | no | Array of integration-specific data used by apps to modify the agent UI. See [display_info object](#display_info-object) below | allow_channelback | boolean | | no | If false, prevents the agent from making additional comments on the message in the Zendesk interface | fields | array | | no | Array of ticket fields to set in Zendesk and their values. See [fields array](#fields-array) | file_urls | array | 10 | no | Array of files to be imported into Zendesk. See [file urls](/documentation/channel_framework/understanding-the-channel-framework/pull_endpoint/#file-urls) in the Channel framework docs #### author object | Name | Type | Max chars | Mandatory | Comments |------------ | ------ |---------- |---------- |----------- | external_id | string | 255 | yes | Unique identifier of the user in the origin service | name | string | 255 | no | If not supplied, defaults to external id | image_url | string | 255 | no | URL to an image for the user | locale | String | 255 | no | The user's locale. Must be one of the supported [locales](/api-reference/ticketing/account-configuration/locales/#list-available-public-locales) in Zendesk | fields | array | | no | Array of items containing user field identifier ('id') and value of field ('value'.) For system fields ('notes' or 'details'), the identifier is the English name. For custom fields, the identifier may be the ID or the name #### display_info object | Name | Type | Max chars | Mandatory | Comments |----- | ------ |---------- |---------- |----------- | type | string | 255 | yes | Globally unique type identifier defined by the integration origin service. Examples: a GUID or URI | data | string | 65535 | yes | JSON data containing display hints #### fields array The `fields` array lists ticket fields to set in Zendesk and their values. Each item consists of a field identifier (`id`) and a value (`value`) for the field. For Zendesk system fields such as `subject`, the identifier is the English name. For custom fields, the identifier may be a field ID or a name. See [Ticket Fields](/api-reference/ticketing/tickets/ticket_fields/). The `fields` array can only set ticket values on ticket creation, not on ticket updates. #### Response format The response is a JSON object containing a single key: | Name | Type | Comments | --------- | -------- | ------------------- | results | array | An array of [result objects](#result-object) The `results` array contains an entry for each item in the incoming `external_resources` array, in the same order. For example, if you call `push` with 3 external resources, a successful response will include `results` with three entries, corresponding to your 3 resources. #### result object | Name | Type | Comments | -------------------- | ------------------------------ | ------------------- | external_resource_id | string | The external ID of the resource, as passed in | status | object | The status of the import for the indicated resource. See [status object](#status-object) #### status object | Name | Type | Comments | ----------- | ------ | ------------------- | code | string | A code indicating the status of the import of the resource, as described in [status codes](#status-codes) | description | string | In the case of an exception, a description of the exception. Otherwise, not present. #### status codes | Key | Description | ----------------------------------------- | ---------------- | success | The external resource was successfully converted to a ticket or comment | already_imported | Reimport of the external resource was skipped due to a pre-existing ticket or comment for the resource | could_not_locate_parent_external_resource | The parent resource, as identified by parent_id in the [request](#request-parameters), could not be found. The unrecognized parent ID is returned in the description of the [status](#status-object) | processing_error | An internal exception occurred while processing the resource. See `description` in the [status object](#status-object) | halted | This resource was not processed because processing of previous resources failed

    POST /api/v2/any_channel/push

API Tokens

  • Read

    List API Tokens (deprecated)

    Lists the API tokens for the account. Token values are truncated in the response — see the `visible_token` property. **Deprecated.** API tokens are being removed as a supported authentication method for API requests. This endpoint is scheduled for removal on April 30, 2027. #### Allowed For * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission

    GET /api/v2/api_tokens

  • Write

    Create API Token (deprecated)

    Creates a new API token for the account. The response includes the full, unencrypted token value in the `token` property. This is the only time the full value is returned — store it securely, as it can't be retrieved again. On every subsequent request, the token is represented by its truncated `visible_token` value instead. **Deprecated.** API tokens are being removed as a supported authentication method for API requests. This endpoint is scheduled for removal on April 30, 2027. #### Allowed For * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission

    POST /api/v2/api_tokens

  • Destructive

    Update API Token (deprecated)

    Updates the description of an API token, or activates or deactivates it. Setting `active` to false deactivates the token, preventing it from being used to authenticate future API requests without deleting it. **Deprecated.** API tokens are being removed as a supported authentication method for API requests. This endpoint is scheduled for removal on April 30, 2027. #### Allowed For * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission

    PUT /api/v2/api_tokens/{id}

  • Destructive

    Delete API Token (deprecated)

    Permanently deletes an API token. An active token can't be deleted — it must be deactivated first by setting `active` to false on the Update API Token request. **Deprecated.** API tokens are being removed as a supported authentication method for API requests. This endpoint is scheduled for removal on April 30, 2027. #### Allowed For * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission

    DELETE /api/v2/api_tokens/{id}

Approval Requests

  • Read

    Show Approval Clarification Flow Messages

    Returns the clarification flow thread (comments exchanged between the requester and the approver) for an approval request. #### Allowed For * Agents * End users who can view the approval request's ticket, or who are its assignee

    GET /api/v2/approval_clarification_flow_messages/{approval_request_id}

  • Read

    List Approval Requests

    Lists all approval requests for the current account with optional filtering by status and assignee. #### Allowed For * Admins #### Query Parameters | Name | Type | Description |---------------------------|--------|-------------------------------------------------------------------------------------------- | filter[status] | string | Filter by a comma-separated list of one or more approval statuses. Values: active, approved, rejected, withdrawn | filter[assignee_user_id] | string | Filter by a comma-separated list of assigned user ids. Maximum 100 ids | filter[assignee_group_id] | string | Filter by a comma-separated list of assigned group ids. Maximum 100 ids | include | string | Comma-separated list of extra fields to sideload. Supports `deeplinks` — adds a `deeplink` field to each approval request, resolving to that request's agent-facing or Help Center decision page. Omitting `include` leaves the response unchanged. `include=deeplinks` requires the `approvals_api_parity` feature to be enabled for the account. When it isn't, `include=deeplinks` is silently ignored: no `deeplink` field is added, and the rest of the response is unaffected. #### Filtering Logic - When multiple values are provided for a filter, `or` logic is used. For example, `filter[status]=active,approved` is evaluated as `status=active OR status=approved`. - If multiple filters are applied to a single request, `AND` logic is used. For example, `filter[status]=active AND filter[assignee_user_id]=123`. - Each filter parameter supports a maximum 100 values. - Numeric ids must be valid integers. #### Pagination This endpoint supports cursor-based pagination. Use `after_cursor` and `before_cursor` parameters to navigate through results.

    GET /api/v2/approval_requests

  • Read

    Show Approval Request

    Shows a single approval request nested under its approval workflow instance. #### Allowed For * Agents assigned to the approval request

    GET /api/v2/approval_workflow_instances/{workflow_instance_id}/approval_requests/{id}

  • Write

    Create Approval Clarification Flow Message

    Adds a message to the clarification flow thread for an approval request and returns the full, updated thread. #### Allowed For * The approval request's assignee or creator, the ticket assignee, or a member of the assigned group * Any user who can view the ticket when the `approvals_allow_comments_from_ticket_viewers` feature is enabled

    POST /api/v2/approval_clarification_flow_messages

  • Write

    Create Approval Request

    Creates one or more approval requests for a ticket. When manual approval requests are turned off for the account, approval requests can still be created through this API. Approval requests created by the API have a `Sent by` value of `API`. #### Allowed For * System users (flowstate) * Agents #### Single approval request To create a single approval request, supply a top-level `assignee_user_id` or `assignee_group_id`. This is helpful when only one approval is required or approvals need to be received in a specific order. The response returns the created request under the `approval_request` key. See the **Example body** and **Example response(s)** sections below for the single-request request and response shapes. #### Parallel approval requests To create multiple approval requests at once, for the approvers to review and respond to in parallel, supply an `approval_requests` array. The approval request's `subject` and `message` are set once at the top level and apply to every individual approval request in the array. The approval requests are created atomically as an array under the `approval_requests` key, and all share the same `approval_workflow_instance_id`. If any of the approval request entries are invalid, none of the requests are created. To avoid invalid entries, do the following: * Specify exactly one `assignee_user_id` or `assignee_group_id` for each entry in the `approval_requests` array. * Make sure you don't combine a top-level `assignee_user_id` or `assignee_group_id` with the `approval_requests` array. Doing so returns a `422`. Example request: ```bash curl https://{subdomain}.zendesk.com/api/v2/approval_requests \ -H "Content-Type: application/json" -X POST \ -d '{"ticket_id": 123, "subject": "Budget Approval", "message": "Please approve the Q1 budget", "approval_requests": [{"assignee_user_id": 101}, {"assignee_group_id": 202}]}' \ -v -u {email_address}/token:{api_token} ``` Example response: ```json { "approval_requests": [ { "id": "01KFP3S9EVXF9CKAYY080NV98C", "approval_workflow_instance_id": "01KFP3S9EVXF9CKAYY080NV98D", "subject": "Budget Approval", "message": "Please approve the Q1 budget", "status": "active", "created_at": "2026-01-23T19:02:36Z", "created_by_id": 789, "assignee_user_id": 101, "assignee_group_id": null, "ticket_id": 123, "origination_type": "API_ORIGINATION" }, { "id": "01KFP3S9EVXF9CKAYY080NV98E", "approval_workflow_instance_id": "01KFP3S9EVXF9CKAYY080NV98D", "subject": "Budget Approval", "message": "Please approve the Q1 budget", "status": "active", "created_at": "2026-01-23T19:02:36Z", "created_by_id": 789, "assignee_user_id": null, "assignee_group_id": 202, "ticket_id": 123, "origination_type": "API_ORIGINATION" } ] } ```

    POST /api/v2/approval_requests

  • Write

    Decide Approval Request

    Records a decision (approve, reject, or withdraw) on an approval request, with optional notes. #### Allowed For * The user or a member of the group assigned to review the approval request The ticket requester, the ticket assignee, and the user who created the approval request are not allowed to decide on it, even when they are also the assignee.

    PATCH /api/v2/approval_workflow_instances/{workflow_instance_id}/approval_requests/{id}/decision

  • Write

    Withdraw Approval Workflow Instance

    Withdraws every non-withdrawn approval request in the given workflow instance and marks the workflow instance as withdrawn. Works for both parallel and non-parallel workflow instances. #### Allowed For * Agents who can manage approval requests and edit the associated ticket, and who are either the approval request's requester or the ticket's assignee

    PATCH /api/v2/approval_workflow_instances/{workflow_instance_id}/withdraw

Attachments

  • Read

    Show Attachment

    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

    GET /api/v2/attachments/{attachment_id}

  • Write

    Upload Files

    Uploads a file that can be attached to a ticket comment. It doesn't attach the file to the comment. For details and examples, see [Attaching ticket comments with the API](/documentation/ticketing/managing-tickets/adding-ticket-attachments-with-the-api/). The endpoint has a required `filename` query parameter. The parameter specifies what the file will be named when attached to the ticket comment (to give the agent more context about the file). The parameter does not specify the file on the local system to be uploaded. While the two names can be different, their file extensions must be the same. If they don't match, the agent's browser or file reader could give an error when attempting to open the attachment. The `Content-Type` header must contain a recognized MIME type that correctly describes the type of the uploaded file. Failing to send a recognized, correct type may cause undesired behavior. For example, in-browser audio playback may be interrupted by the browser's security mechanisms for MP3s uploaded with an incorrect type. Adding multiple files to the same upload is handled by splitting requests and passing the API token received from the first request to each subsequent request. The token is valid for 60 minutes. **Note**: Even if [private attachments](https://support.zendesk.com/hc/en-us/articles/8435939957914) are enabled in the Zendesk Support instance, uploaded files are visible to any authenticated user at the `content_URL` specified in the [JSON response](#json-format) until the upload token is consumed. Once a file is associated with a ticket or post, visibility is restricted to users with access to the ticket or post with the attachment. #### Allowed For * End users

    POST /api/v2/uploads

  • Destructive

    Update Attachment for Malware

    Toggles enabling or restricting agent access to attachments with detected malware. #### Allowed For * Admins

    PUT /api/v2/attachments/{attachment_id}

  • Destructive

    Delete Attachment

    Deletes the attachment. #### Allowed for * Agents

    DELETE /api/v2/attachments/{attachment_id}

  • Destructive

    Redact Comment Attachment

    Redaction allows you to permanently remove attachments from an existing comment on a ticket. Once removed from a comment, the attachment is replaced with an empty "redacted.txt" file. The redaction is permanent. It is not possible to undo redaction or see what was removed. Once a ticket is closed, redacting its attachments is no longer possible. Also, if you want to redact an inline attachment, you can use the `include_inline_images` parameter in the [List Comments](/api-reference/ticketing/tickets/ticket_comments/#list-comments) operation to obtain the inline attachment ID, and use it in the request URL. #### Allowed For * Admins * Agents when [deleting tickets is enabled for agents on professional accounts](https://support.zendesk.com/hc/en-us/articles/4408832689818) * Agents assigned to a custom role with permissions to redact ticket content (Enterprise only)

    PUT /api/v2/tickets/{ticket_id}/comments/{comment_id}/attachments/{attachment_id}/redact

  • Destructive

    Delete Upload

    #### Allowed for * End Users

    DELETE /api/v2/uploads/{token}

Audit Logs

  • Read

    List Audit Logs

    #### 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. #### Filtering by multiple values To filter by multiple values for the same field, repeat the filter parameter and append empty square brackets "[]" to the name of each repeated parameter. For example, to return audit logs where `action` is "create", "update", or "destroy": `/api/v2/audit_logs?filter[action][]=create&filter[action][]=update&filter[action][]=destroy`

    GET /api/v2/audit_logs

  • Read

    Show Audit Log

    #### Allowed For * Admins on accounts that have audit-log access

    GET /api/v2/audit_logs/{audit_log_id}

  • Write

    Export Audit Logs

    #### Allowed For * Admins on accounts that have audit log access #### Limits This endpoint's rate limit is different from the account-wide rate limit. The rate limit is one request per minute per account. When this limit is reached, you'll get a `429 Too Many Requests` response code. ##### Headers API responses include usage limit information in the headers for this endpoint. ``` Zendesk-RateLimit-audit-logs-export: total={number}; remaining={number}; resets={number} ``` Within this header, “Total” signifies the initial allocation, “Remaining” indicates the remaining allowance for the current interval, and “Resets” denotes the wait time in seconds before the limit refreshes. You can see the Total, and Interval values in the below table. ##### Details The rate limit is one request per minute per account. If you exceed this, you'll receive the following error: "Rate limit for Audit log CSV Export exceeded. Please wait 1 minute and try again."

    POST /api/v2/audit_logs/export

Tags

  • Read

    Search Tags

    Returns an array of registered and recent tag names that start with the characters specified in the `name` query parameter. This includes tags where any word within the tag (separated by underscores, hyphens, spaces, or other punctuation) starts with the specified characters. You must specify at least 2 characters. #### How tag matching works When tags contain delimiters like underscores, hyphens, or spaces, each word is indexed separately. A tag matches if the tag itself or any word within it starts with your search term. For example, searching for `trig` will match the tag `set_by_this_trigger` because one of its words ("trigger") starts with "trig". However, searching for `rigger` won't match this tag because neither the full tag nor any of its individual words ("set", "by", "this", "trigger") start with "rigger". #### Autocomplete limitations Autocomplete returns up to 15 suggestions from the most commonly used ticket tags in the last 60 days. Tags that match the prefix but aren't in that top set won't appear in the results. #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/introduction/pagination/#using-offset-pagination). #### Allowed For * Agents

    GET /api/v2/autocomplete/tags

  • Read

    Search Tags by Request Body

    Returns an array of registered and recent tag names that start with the characters specified in the `name` parameter. This includes tags where any word within the tag (separated by underscores, hyphens, spaces, or other punctuation) starts with the specified characters. You must specify at least 2 characters. This endpoint accepts the same parameters as the [GET method](#search-tags) but they are specified in the request body instead of the query string. #### How tag matching works When tags contain delimiters like underscores, hyphens, or spaces, each word is indexed separately. A tag matches if the tag itself or any word within it starts with your search term. For example, searching for `trig` will match the tag `set_by_this_trigger` because one of its words ("trigger") starts with "trig". However, searching for `rigger` won't match this tag because neither the full tag nor any of its individual words ("set", "by", "this", "trigger") start with "rigger". #### Autocomplete limitations Autocomplete returns up to 15 suggestions from the most commonly used ticket tags in the last 60 days. Tags that match the prefix but aren't in that top set won't appear in the results. #### Allowed For * Agents

    POST /api/v2/autocomplete/tags

  • Read

    List Organization Tags

    #### Allowed For * Agents

    GET /api/v2/organizations/{organization_id}/tags

  • Read

    List Tags

    Lists up to the 20,000 most popular tags in the last 60 days, in decreasing popularity. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents

    GET /api/v2/tags

  • Read

    Count Tags

    Returns an approximate count of tags. 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, the `refreshed_at` property in the `count` object may occasionally be null. This indicates that the count is being updated in the background and the `value` property in the `count` object is limited to 100,000 until the update is complete. #### Allowed For * Agents

    GET /api/v2/tags/count

  • Read

    List Resource Tags

    #### Allowed For * Agents

    GET /api/v2/tickets/{ticket_id}/tags

  • Read

    List User Tags

    #### Allowed For * Agents

    GET /api/v2/users/{user_id}/tags

  • Write

    Set Organization Tags

    #### Allowed For * Agents

    POST /api/v2/organizations/{organization_id}/tags

  • Write

    Set Tags

    #### Allowed For * Agents

    POST /api/v2/tickets/{ticket_id}/tags

  • Write

    Set User Tags

    #### Allowed For * Agents

    POST /api/v2/users/{user_id}/tags

  • Destructive

    Add Organization Tags

    #### Allowed For * Agents

    PUT /api/v2/organizations/{organization_id}/tags

  • Destructive

    Remove Organization Tags

    #### Allowed For * Agents

    DELETE /api/v2/organizations/{organization_id}/tags

  • Destructive

    Add Tags

    You can also add tags to multiple tickets with the [Update Many Tickets](/api-reference/ticketing/tickets/tickets/#update-many-tickets) endpoint. #### Safe Update If the same ticket is updated by multiple API requests at the same time, some tags could be lost because of ticket update collisions. Include `updated_stamp` and `safe_update` properties in the request body to make a safe update. For `updated_stamp`, retrieve and specify the ticket's latest `updated_at` timestamp. The tag update only occurs if the `updated_stamp` timestamp matches the ticket's actual `updated_at` timestamp at the time of the request. If the timestamps don't match (in other words, if the ticket was updated since you retrieved the ticket's last `updated_at` timestamp), the request returns a 409 Conflict error. #### Example ```js { "tags": ["customer"], "updated_stamp":"2019-09-12T21:45:16Z", "safe_update":"true" } ``` For details, see [Protecting against ticket update collisions](/api-reference/ticketing/tickets/tickets/#protecting-against-ticket-update-collisions). #### Allowed For * Agents

    PUT /api/v2/tickets/{ticket_id}/tags

  • Destructive

    Remove Tags

    You can also delete tags from multiple tickets with the [Update Many Tickets](/api-reference/ticketing/tickets/tickets/#update-many-tickets) endpoint. This endpoint supports safe updates. See [Safe Update](/api-reference/ticketing/ticket-management/tags/#safe-update). #### Allowed For * Agents

    DELETE /api/v2/tickets/{ticket_id}/tags

  • Destructive

    Add User Tags

    #### Allowed For * Agents

    PUT /api/v2/users/{user_id}/tags

  • Destructive

    Remove User Tags

    #### Allowed For * Agents

    DELETE /api/v2/users/{user_id}/tags

Automations

  • Read

    List Automations

    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 tickets processed by an automation in the past hour | usage_24h | The number of tickets processed by an automation in the past day | usage_7d | The number of tickets processed by an automation in the past week | usage_30d | The number of tickets processed by an automation 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.

    GET /api/v2/automations

  • Read

    Show Automation

    #### Allowed For * Agents

    GET /api/v2/automations/{automation_id}

  • Read

    List Active Automations

    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 tickets processed by an automation in the past hour | usage_24h | The number of tickets processed by an automation in the past day | usage_7d | The number of tickets processed by an automation in the past week | usage_30d | The number of tickets processed by an automation in the past thirty days

    GET /api/v2/automations/active

  • Read

    Search Automations

    #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/introduction/pagination/#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 tickets processed by an automation in the past hour | usage_24h | The number of tickets processed by an automation in the past day | usage_7d | The number of tickets processed by an automation in the past week | usage_30d | The number of tickets processed by an automation in the past thirty days

    GET /api/v2/automations/search

  • Write

    Create Automation

    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

    POST /api/v2/automations

  • Destructive

    Update 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

    PUT /api/v2/automations/{automation_id}

  • Destructive

    Delete Automation

    **Note**: You might be restricted from deleting some default automations. #### Allowed For * Agents

    DELETE /api/v2/automations/{automation_id}

  • Destructive

    Bulk Delete 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" } ```

    DELETE /api/v2/automations/destroy_many

  • Destructive

    Update Many 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} ] } ```

    PUT /api/v2/automations/update_many

Bookmarks

  • Read

    List Bookmarks

    Archived tickets are not included in the response. See [About archived tickets](https://support.zendesk.com/hc/en-us/articles/4408887617050) in Zendesk help. #### Allowed For - Agents

    GET /api/v2/bookmarks

  • Write

    Create Bookmark

    #### Allowed For - Agents

    POST /api/v2/bookmarks

  • Destructive

    Delete 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 /api/v2/bookmarks/{bookmark_id}

Brand Agents

  • Read

    List Brand Agent Memberships

    Returns a list of all brand agent memberships for your account. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Admins

    GET /api/v2/brand_agents

  • Read

    Show Brand Agent Membership

    Returns a brand agent membership for your account. #### Allowed For * Admins

    GET /api/v2/brand_agents/{brand_agent_id}

  • Read

    List Agents By Brand

    Returns a list of all agents assigned to a specific brand. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Admins

    GET /api/v2/brands/{brand_id}/agents

  • Read

    List Brand Agent Memberships By User

    Returns a list of all brand agent memberships for a specific user. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Admins

    GET /api/v2/users/{user_id}/brand_agents

  • Read

    Show Brand Agent Membership By User

    Returns a specific brand agent membership for a user. #### Allowed For * Admins

    GET /api/v2/users/{user_id}/brand_agents/{brand_agent_id}

  • Write

    Create Brand Agent Membership

    Creates a brand agent membership, granting the agent access to the brand. Returns `422` if the user is not an agent, the brand does not belong to the account, or a membership for the same user and brand already exists. #### Allowed For: * Admins

    POST /api/v2/brand_agents

  • Destructive

    Delete Brand Agent Membership

    Deletes a brand agent membership, removing the agent's access to the brand. The `brand_agent_id` is the id of the brand agent membership returned by the list and show endpoints, not the id of the brand or the user. #### Allowed For * Admins

    DELETE /api/v2/brand_agents/{brand_agent_id}

Brands

  • Read

    List Brands

    Returns a list of all brands for your account sorted by name. #### Allowed for * Admins * Agents with the `assign_tickets_to_any_brand` permission can list all brands for the account * Agents without the `assign_tickets_to_any_brand` permission can only list brands they are members of #### Pagination * Cursor pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/brands

  • Read

    Show a Brand

    Returns a brand for your account. #### Allowed for * Admins, Agents

    GET /api/v2/brands/{brand_id}

  • Read

    Check Host Mapping Validity for an Existing Brand

    Returns a JSON object determining whether a host mapping is valid for the given brand. #### Allowed for - Admins

    GET /api/v2/brands/{brand_id}/check_host_mapping

  • Read

    Check Host Mapping Validity

    Returns a JSON object determining whether a host mapping is valid for a given subdomain. #### Allowed for * Admins

    GET /api/v2/brands/check_host_mapping

  • Write

    Create Brand

    Creates a brand. To attach a logo, make a follow-up request to `PUT /api/v2/brands/{brand_id}/logo`. #### Allowed for - Admins

    POST /api/v2/brands

  • Destructive

    Update a Brand

    Returns an updated brand. #### Allowed for * Admins #### Updating a Brand's Image Use `PUT /api/v2/brands/{brand_id}/logo` to set or replace the brand logo, and `DELETE /api/v2/brands/{brand_id}/logo` to remove it.

    PUT /api/v2/brands/{brand_id}

  • Destructive

    Delete a Brand

    Deletes a brand. #### Allowed for - Admins

    DELETE /api/v2/brands/{brand_id}

X Channel

  • Read

    List Monitored X Handles

    #### Allowed For * Admins * Agents

    GET /api/v2/channels/twitter/monitored_twitter_handles

  • Read

    Show Monitored X Handle

    #### Allowed For * Admins * Agents

    GET /api/v2/channels/twitter/monitored_twitter_handles/{monitored_twitter_handle_id}

  • Read

    List Ticket statuses

    #### Allowed For * Agents

    GET /api/v2/channels/twitter/tickets/{comment_id}/statuses

  • Write

    Create Ticket from Tweet

    Turns a tweet into a ticket. You must provide the tweet id as well as the id of a monitored X (formerly Twitter) handle configured for your account. The submitter of the ticket is set to be the user submitting the API request. #### Allowed For * Agents

    POST /api/v2/channels/twitter/tickets

Basics

  • Write

    Open Ticket in Agent's Browser

    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

    POST /api/v2/channels/voice/agents/{agent_id}/tickets/{ticket_id}/display

  • Write

    Open a User's Profile in an 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 `user_id` is invalid: ```http Status: 404 Not Found ``` #### Allowed For * Agents

    POST /api/v2/channels/voice/agents/{agent_id}/users/{user_id}/display

  • Write

    Create Ticket or Voicemail Ticket

    #### 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. The `display_to_agent` is validated before creating the ticket, returning a 422 error if it is invalid. 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 | recording_type | string | Type of recording (call, voicemail, or ai) | 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)

    POST /api/v2/channels/voice/tickets

WhatsApp Templates

  • Read

    List WhatsApp Templates

    Returns the WhatsApp message templates synced from SunCo for the account's WhatsApp integrations. Only templates approved by WhatsApp are synced. Listing triggers a freshness check per integration. If local data is missing or stale, a background sync is started and the `syncing` flag is set in the response. The list may be incomplete while that flag is set, so poll until it clears. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). #### Allowed For * Agents

    GET /api/v2/channels/whatsapp_templates

  • Read

    List WhatsApp Template Languages

    Returns the distinct languages present across the account's synced WhatsApp message templates. Use it to populate a language filter for [List WhatsApp Templates](#list-whatsapp-templates). #### Allowed For * Agents

    GET /api/v2/channels/whatsapp_templates/languages

  • Destructive

    Toggle WhatsApp Template

    Enables or disables a single WhatsApp message template for the account. Activation is controlled by admins and is never overwritten by a sync from SunCo. #### Allowed For * Admins

    PUT /api/v2/channels/whatsapp_templates/{template_id}/toggle

  • Destructive

    Bulk Toggle WhatsApp Templates

    Enables or disables several WhatsApp message templates in one request. All templates are set to the same `is_active` value. The update is applied only if every supplied `template_id` exists on the account. #### Allowed For * Admins

    PUT /api/v2/channels/whatsapp_templates/toggle_many

Ticket Comments

  • Read

    List Comments

    Returns the comments added to the ticket. Each comment may include a `content_url` for an attachment or a `recording_url` for a voice comment that points to a file that may be hosted externally. For security reasons, take care not to inadvertently send Zendesk authentication credentials to third parties when attempting to access these files. See [Working with url properties](/documentation/api-basics/best-practices/working-with-url-properties/). #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Sorting By default, comments are sorted by creation date in ascending order. When using cursor pagination, use the following parameter to change the sort order: | Name | Type | Required | Comments | ------ | ------ | -------- | -------- | `sort` | string | no | Possible values are "created_at" (ascending order) or "-created_at" (descending order) When using offset pagination, use the following parameters to change the sort order: | Name | Type | Required | Comments | ------------ | ------ | -------- | -------- | `sort_order` | string | no | One of `asc`, `desc`. Defaults to `asc` #### Allowed For * Agents

    GET /api/v2/tickets/{ticket_id}/comments

  • Read

    Count Ticket Comments

    Returns an approximate count of the comments added to the ticket. 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

    GET /api/v2/tickets/{ticket_id}/comments/count

  • Destructive

    Redact Chat Comment Attachment

    Permanently removes one or more chat attachments from a chat ticket. **Note**: This does not work on active chats. For chat tickets that predate March 2020, consider using [Redact Ticket Comment In Agent Workspace](#redact-ticket-comment-in-agent-workspace). #### Allowed For - Agents [Agent Workspace](https://support.zendesk.com/hc/en-us/articles/4408821259930) must enabled for the account. Deleting tickets must be enabled for agents. #### Request Body Properties | Name | Type | Required | Description | | ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | chat_id | string | true | The `chat_id` in the `ChatStartedEvent` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits) | | chat_indexes | array | false | The array of `chat_index` in the `ChatFileAttachment` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits). Mandatory if `message_ids` is not used | | message_ids | array | false | The array of `message_id` in the `ChatFileAttachment` event in the ticket audit that is part of a `ChatStartedEvent` history. Used when redacting a ChatFileAttachment that is part of a conversation history. Mandatory if `chat_indexes` is not used | To get the required body properties, make a request to the [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits) endpoint. Example response: ```http Status 200 OK { "audits": [ "events": [ { "id": 1932802680168, "type": "ChatStartedEvent", "value": { "visitor_id": "10502823-16EkM3T6VNq7KMd", "chat_id": "2109.10502823.Sjuj2YrBpXwei", "history": [ { "chat_index": 0, "type": "ChatFileAttachment", "filename": "image1.jpg" }, { "chat_index": 1, "type": "ChatFileAttachment", "filename": "image2.jpg" } ] } } ] ] } ```

    PUT /api/v2/chat_file_redactions/{ticket_id}

  • Destructive

    Redact Chat Comment

    Permanently removes words or strings from a chat ticket's comment. Wrap `<redact>` tags around the content in the chat comment you want redacted. Example: ```json { "text": "My ID number is <redact>847564</redact>!" } ``` The characters contained in the tag will be replaced by the ▇ symbol. **Note**: This does not work on active chats. For chat tickets that predate March 2020, consider using [Redact Ticket Comment In Agent Workspace](#redact-ticket-comment-in-agent-workspace). **Limitations**: - Redaction is a synchronous process. For archived tickets, only one redaction request can be processed at a time per ticket. Concurrent redaction requests on the same archived ticket will receive a 409 Conflict response with a `Retry-After` header indicating how many seconds to wait before retrying (up to 30 seconds). The lock is released immediately when the redaction completes. This limit does not apply to requests from the Zendesk UI. #### Allowed For - Agents [Agent Workspace](https://support.zendesk.com/hc/en-us/articles/4408821259930) must enabled for the account. Deleting tickets must be enabled for agents. #### Request Body Properties | Name | Type | Required | Description | | ------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | chat_id | string | true | The `chat_id` in the `ChatStartedEvent` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits) | | chat_index | integer | false | The `chat_index` in the `ChatMessage` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits). Mandatory if `message_id` is not used | | message_id | string | false | The `message_id` of the `ChatMessage` event in the ticket audit that is part of a `ChatStartedEvent` history. Used when redacting a ChatMessage that is part of a conversation history. Mandatory if `chat_index` is not used | | text | string | true | The `message` in the `ChatMessage` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits). Wrap `message` with `<redact>` tags | To get the required body properties, make a request to the [Ticket Audit](/api-reference/ticketing/tickets/ticket_audits) endpoint. Example response: ```http Status 200 OK { "audits": [ "events": [ { "id": 1932802680168, "type": "ChatStartedEvent", "value": { "visitor_id": "10502823-16EkM3T6VNq7KMd", "chat_id": "2109.10502823.Sjuj2YrBpXwei", "history": [ { "chat_index": 0, "type": "ChatMessage", "message": "My ID number is 847564!" } ] } } ] ] } ```

    PUT /api/v2/chat_redactions/{ticket_id}

  • Destructive

    Redact Ticket Comment In Agent Workspace

    Redaction allows you to permanently remove words, strings, or attachments from a ticket comment. In the `html_body` of the comment, wrap the content you want redacted in `<redact>` tags. Example: ```json { "html_body": "<div class=\"zd-comment\" dir=\"auto\">My ID number is <redact>847564</redact>!</div>", "ticket_id":100 } ``` The characters in the redact tag will be replaced by the ▇ symbol. To redact HTML elements such inline images, anchor tags, and links, add the `redact` tag attribute to the element as well as the `<redact>` tag to inner text, if any. Example: `<a href="http://example.com" redact><redact>some link</redact></a>` The `redact` attribute only redacts the tag. Any inner text will be left behind if not enclosed in a `<redact>` tag. Redaction is permanent and can not be undone. Data is permanently deleted from Zendesk servers with no way to recover it. This endpoint provides all the same functionality that the [Redact String in Comment](/api-reference/ticketing/tickets/ticket_comments/#redact-string-in-comment) endpoint provides, plus: - Redaction of comments in closed tickets - Redaction of comments in archived tickets - Redaction of formatted text (bold, italics, hyperlinks) **Limitations**: - When content is redacted from an email comment, the content is also redacted from the original email through a background job. It may take a while for the changes to be completed. - Redaction is a synchronous process. For archived tickets, only one redaction request can be processed at a time per ticket. Concurrent redaction requests on the same archived ticket will receive a 409 Conflict response with a `Retry-After` header indicating how many seconds to wait before retrying (up to 30 seconds). The lock is released immediately when the redaction completes. This limit does not apply to requests from the Zendesk UI. **Note**: We recommend using this endpoint instead of the [Redact String in Comment](/api-reference/ticketing/tickets/ticket_comments/#redact-string-in-comment) endpoint, which will eventually be deprecated. #### Allowed For - Agents [Agent Workspace](https://support.zendesk.com/hc/en-us/articles/4408821259930) must be enabled on the account. For professional accounts, deleting tickets must be enabled for agents. On Enterprise accounts, you can assign agents to a custom role with permissions to redact ticket content. #### Rate limits When enabled, this endpoint has a rate limit shared by all agents and tickets in an account. The burst allowance holds up to 400 requests and replenishes at 9 requests per second, up to that capacity. Requests from the Zendesk UI are exempt from this endpoint-specific limit. Applicable account API limits also apply and can reduce throughput. Account API rate-limit headers do not report this endpoint-specific allowance. Requests that exceed this limit receive a 429 Too Many Requests response. Wait for the number of seconds specified in the returned `Retry-After` header before retrying. A retry can still be rate limited. #### Request Body Properties | Name | Type | Required | Description | | -------------------------| ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | ticket_id | integer | true | The ID of the ticket | | html_body | string | false | The `html_body` of the comment containing `<redact>` tags or `redact` attributes | | external_attachment_urls | array | false | Array of attachment URLs belonging to the comment to be redacted. See [`content_url` property of Attachment](/api-reference/ticketing/tickets/ticket-attachments/) |

    PUT /api/v2/comment_redactions/{ticket_comment_id}

  • Destructive

    Make Comment Private

    #### Allowed For * Agents

    PUT /api/v2/tickets/{ticket_id}/comments/{ticket_comment_id}/make_private

  • Destructive

    Redact String in Comment

    Permanently removes words or strings from a ticket comment. Specify the string to redact in an object with a `text` property. Example: `'{"text": "987-65-4320"}'`. The characters of the word or string are replaced by the ▇ symbol. If the comment was made by email, the endpoint also attempts to redact the string from the original email retained by Zendesk for audit purposes. **Note**: If you use the rich text editor, support for redacting formatted text (bold, italics, hyperlinks) is limited. Redaction is permanent. You can't undo the redaction or see *what* was removed. Once a ticket is closed, you can no longer redact strings from its comments. To use this endpoint, the "Agents can delete tickets" option must be enabled in the Zendesk Support admin interface at **Admin** > **Settings** > **Agents**. #### Allowed For * Agents

    PUT /api/v2/tickets/{ticket_id}/comments/{ticket_comment_id}/redact

Countries

  • Read

    List Countries and Calling Codes

    Returns a list of all countries with their calling codes. This endpoint is publicly accessible and does not require authentication. #### Allowed For * Anyone

    GET /api/v2/countries.json

  • Read

    Show Country

    Returns details for a specific country by ID. This endpoint is publicly accessible and does not require authentication. #### Allowed For * Anyone

    GET /api/v2/countries/{id}.json

Custom Objects

  • Read

    List Custom Objects

    Lists all undeleted custom objects for the account #### Allowed For * Agents

    GET /api/v2/custom_objects

  • Read

    Show Custom Object

    Returns an object with the specified key #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}

  • Read

    Custom Objects Limit

    List the current count and the limit for custom objects #### Allowed For * Admins

    GET /api/v2/custom_objects/limits/object_limit

  • Write

    Create Custom Object

    Creates an object describing all the properties required to create a custom object record #### Allowed For * Admins

    POST /api/v2/custom_objects

  • Write

    Update Custom Object

    Updates an individual custom object. The updating rules are as follows: * Takes a `custom_object` object that specifies the properties to update * The `key` property cannot be updated #### Allowed For * Admins

    PATCH /api/v2/custom_objects/{custom_object_key}

  • Destructive

    Delete Custom Object

    Permanently deletes the custom object with the specified key #### Allowed For * Admins

    DELETE /api/v2/custom_objects/{custom_object_key}

Custom Object Permissions

  • Read

    List Access Rules

    Returns a list of access rules for a custom object. Access rules define conditions that restrict which custom object records a role can access. #### Allowed For * Admins

    GET /api/v2/custom_objects/{custom_object_key}/access_rules

  • Read

    Show Access Rule

    Returns a specific access rule for a custom object. #### Allowed For * Admins

    GET /api/v2/custom_objects/{custom_object_key}/access_rules/{id}

  • Read

    List Access Rule Definitions

    Returns the available field definitions and operators that can be used when creating access rules for a custom object. This endpoint helps you understand what fields are available for filtering and what operators can be applied to each field type. #### Allowed For * Admins

    GET /api/v2/custom_objects/{custom_object_key}/access_rules/definitions

  • Read

    List Permission Policies

    Returns a list of permission policies for a custom object. Permission policies define what actions (create, read, update, delete) different roles can perform on custom object records. #### Allowed For * Admins

    GET /api/v2/custom_objects/{custom_object_key}/permission_policies

  • Read

    Show Permission Policy

    Returns a permission policy for a specific role on a custom object. The policy ID can be: - `custom-role-{custom_role_id}` for custom roles - `end-user` for the end user system role #### Allowed For * Admins

    GET /api/v2/custom_objects/{custom_object_key}/permission_policies/{id}

  • Write

    Create Access Rule

    Creates a new access rule for a custom object. Access rules define conditions that restrict which records a role can access based on field values or relationships. #### Allowed For * Admins

    POST /api/v2/custom_objects/{custom_object_key}/access_rules

  • Write

    Update Access Rule

    Updates an existing access rule for a custom object. #### Allowed For * Admins

    PATCH /api/v2/custom_objects/{custom_object_key}/access_rules/{id}

  • Write

    Update Permission Policy

    Updates a permission policy for a specific role on a custom object. Define what actions (create, read, update, delete) the role can perform and optionally specify access rules. #### Allowed For * Admins

    PATCH /api/v2/custom_objects/{custom_object_key}/permission_policies/{id}

  • Destructive

    Delete Access Rule

    Permanently deletes an access rule for a custom object. #### Allowed For * Admins

    DELETE /api/v2/custom_objects/{custom_object_key}/access_rules/{id}

Custom Object Fields

  • Read

    List Custom Object Fields

    Lists all undeleted custom fields for the specified object. #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/custom_objects/{custom_object_key}/fields

  • Read

    Show Custom Object Field

    Returns a custom field for a specific object using a provided key or id of the field. #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id}

  • Read

    Custom Object Fields Limit

    List the current count and the limit for a custom object's fields #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/limits/field_limit

  • Write

    Create Custom Object Field

    Creates any of the following custom field types: * text (default when no "type" is specified) * textarea * checkbox * currency * date * integer * decimal * regexp * dropdown * lookup * multiselect * parent Additionally, you can create a roll-up summary field by specifying an existing type (`integer`, `decimal`, or `date`) with roll-up configuration in the `properties` object. See [About roll-up summary fields](/api-reference/custom-data/custom-objects/custom_object_fields/#about-roll-up-summary-fields). To make a text, integer, regexp, or lookup field require unique values, set `is_unique` to true in the `properties` object. See [About unique fields](/api-reference/custom-data/custom-objects/custom_object_fields/#about-unique-fields). See [About custom field types](https://support.zendesk.com/hc/en-us/articles/4408838961562) in Zendesk help. #### Allowed For * Admins

    POST /api/v2/custom_objects/{custom_object_key}/fields

  • Destructive

    Update Custom Object Field

    Updates individual custom object fields. The updating rules are as follows: * Takes a `custom_object_field` object that specifies the properties to update. * The `key` property cannot be updated. * If updating a standard field, only the `title`, `description`, and `properties` attributes can be updated. * Standard name field is always required. Therefore, the `required` property for standard name field isn't editable. * The `properties` parameter is comprised of four parts and can't be changed if any records exist for the object. * `autoincrement_enabled`: A Boolean that enables and disables autonumbering. Must be false if is_unique is true. * `autoincrement_prefix`: A string value that is used as a prefix to the autogenerated numbers. It can't exceed 30 characters. * `autoincrement_padding`: An integer specifying the starting number of digits in the autogenerated numbers. This value may be between 0-9. However, if you create records in excess of of these digits, additional digits are added as necessary. * `autoincrement_next_sequence`: An integer that will be used as the next number in the autonumbering sequence. It can't be negative or less than the current autonumbering value. * `is_unique`: A Boolean that enforces uniqueness for manually entered record names. When true, custom object record names must be unique. Must be false if autoincrement_enabled is true. * For text, integer, regexp, and lookup fields, `properties` can include `is_unique`, a Boolean that requires each record to have a different value in the field. Unlike the name field's properties, it can be changed when records exist: it can be turned on only if no record has a value for the field, and it can always be turned off. See [About unique fields](#about-unique-fields). #### Updating drop-down field options You can also use the update endpoint to add, update, or remove options in a drop-down custom field. Updating field options for multi-select fields works exactly the same as drop-down field options. **Important**: Unless you want to remove some options, you must specify all existing options in any update request. Omitting an option removes it from the drop-down field, which removes its values from any tickets or macros. Use the `custom_field_options` attribute to update the options. The attribute consists of an array of option objects, with each object consisting of an `id`, `name`, and `value` property. The name and value properties correspond to the "Title" and "Tag" text boxes in the admin interface respectively. For new drop-down options, specify `"id":"null"`. Example request body: ```json {"custom_object_field": { "custom_field_options": [ {"id": "null", "name": "Apple Pie", "value": "apple"}, {"id": "null", "name": "Pecan Pie", "value": "pecan"} ] } } ``` #### Example Request ```bash curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id} -d '{"ticket_field": {"custom_field_options": [{"name": "Apple Pie", "value": "apple"}, {"name": "Pecan Pie", "value": "pecan"}]}}' \ -H "Content-Type: application/json" -X PUT \ -v -H "Authorization: Bearer {access_token}" ``` #### Allowed For * Admins

    PATCH /api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id}

  • Destructive

    Delete Custom Object Field

    Deletes a field with the specified key. Note: You can't delete standard fields. #### Allowed For * Admins

    DELETE /api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id}

  • Destructive

    Reorder Custom Fields of an Object

    Sets a preferred order of custom fields for a specific object by providing field ids in the desired order. #### Allowed For * Admins

    PUT /api/v2/custom_objects/{custom_object_key}/fields/reorder

Custom Object Records

  • Read

    List Custom Object Records

    Lists all undeleted custom object records for the specified object. If the object has a parent field with `cascade_permissions_enabled`, non-admin agents receive a `403 Forbidden` response. Use the [Filtered Search endpoint](#filtered-search-of-custom-object-records) with a filter on the parent field instead. #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/records

  • Read

    Show Custom Object Record

    Returns a custom record for a specific object using a provided id. #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id}

  • Read

    Autocomplete Custom Object Record Search

    Retrieves an array of custom object records that have a field value that matches the value specified in the `name` parameter. If the object has a parent field with `cascade_permissions_enabled`, the request must be made in the context of a cascade parent field using the `field_id` and `source` parameters. #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. * Returns the first 10,000 records sorted by relevancy with page limits. #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/records/autocomplete

  • Read

    Count Custom Object Records

    Returns a total count of records for a specific custom object as well as the time the count was refreshed. If the object has a parent field with `cascade_permissions_enabled`, non-admin agents receive a `403 Forbidden` response. Use the [Filtered Search endpoint](/api-reference/custom-data/custom-objects/custom_object_records/#filtered-search-of-custom-object-records) with a filter on the parent field instead. #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/records/count

  • Read

    Search Custom Object Records

    Returns an array of custom object records where the search query matches the values in Text Fields, Multi Line Text fields, and RegExp fields. To find records in other fields, use the [Filtered Search API](/api-reference/custom-data/custom-objects/custom_object_records/#filtered-search-of-custom-object-records) endpoint. If the object has a parent field with `cascade_permissions_enabled`, non-admin agents receive a `403 Forbidden` response. Use the [Filtered Search endpoint](/api-reference/custom-data/custom-objects/custom_object_records/#filtered-search-of-custom-object-records) with a filter on the parent field instead. #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. * Returns the records sorted by relevancy with page limits. Without a `sort` parameter, only the first 10,000 records are returned. With a `sort` parameter, all records are returned. #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/records/search

  • Read

    Show Custom Object Record by Unique Identifier

    Returns a custom object record identified by its external id, its name, or the value of one of the custom object's unique fields. Send exactly one identifier per request. * To identify the record by name, the `is_unique` property on the custom object's name field must be enabled. * To identify the record by a unique field, send the field's key as the query parameter, for example `?vin=1HGCM82633A004352`. The field's `is_unique` property must be enabled. For a unique lookup field, the value is the id of the record the field references. Returns a `400 Bad Request` if more than one identifier is sent, if `name` is sent and the name field isn't unique, or if no identifier is sent. A parameter that isn't the key of a unique field doesn't count as an identifier. Returns a `404 Not Found` if no record matches. #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/records/show_by_unique_identifier

  • Read

    Custom Object Records Limit

    List the current count and the limit for custom object records #### Allowed For * Agents

    GET /api/v2/custom_objects/limits/record_limit

  • Read

    Incremental Custom Object Record Export, Cursor Based

    Returns the custom object records that changed since the start time. This endpoint supports cursor-based incremental exports for custom object records. This endpoint only supports cursor-based pagination and does not support offset-based pagination. Cursor-based exports provide more consistent performance and response body sizes. For more information, see [Cursor-based incremental exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#cursor-based-incremental-exports) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api). #### Allowed For * Admins * Agents with custom object read permissions #### Rate Limiting You can make up to 10 requests per minute to this endpoint. #### Notes - `start_time` is only required for the initial request for the pages in the record set, then `cursor` is required for all subsequent requests - The `start_time` must be more than 60 seconds ago - Deleted records will have their field values replaced with "[DELETED]" unless excluded via filter - Photo fields are excluded from incremental export responses

    GET /api/v2/incremental/custom_objects/{custom_object_key}/cursor

  • Write

    Custom Object Record Bulk Jobs

    Queues a background job to perform bulk actions on up to 100 custom object records per single request. Takes a `job` object with the following nested fields: * `action`, one of: * `"create"` * `"delete"` * `"delete_by_external_id"` * `"delete_by_unique_field"` * `"create_or_update_by_external_id"` * `"create_or_update_by_name"` * `"create_or_update_by_unique_field"` * `"update"` * `items` * For a `"create"` action, an array of JSON objects representing the custom object records being created * For a `"delete"` action, an array of strings representing Zendesk record ids * For a `"delete_by_external_id"` action, an array of strings representing external ids * For a `"delete_by_unique_field"` action, an array of strings representing values of the unique field named in `unique_field_key` * For a `"create_or_update_by_external_id"` action, an array of JSON objects representing the custom object records being created or updated by external id * For a `"create_or_update_by_name"` action, an array of JSON objects representing the custom object records being created or updated by name. The `is_unique` property on the custom object's name field must be enabled. * For a `"create_or_update_by_unique_field"` action, an array of JSON objects representing the custom object records being created or updated by the unique field named in `unique_field_key`. Each object must include that field's value in `custom_object_fields`. * For an `"update"` action, an array of JSON objects representing the custom object records being updated * `unique_field_key`, required for the `"create_or_update_by_unique_field"` and `"delete_by_unique_field"` actions: the key of the custom object field that identifies the records. The field's `is_unique` property must be enabled. Use the `*_by_name` actions to identify records by name. Note: If autonumbering is selected for the custom object's name field, record names aren't allowed in the request body because they are generated automatically. If uniqueness is enabled, the record names must be unique. #### Identifying records by a unique field Returns a `400 Bad Request` with the error `InvalidUniqueFieldKey` if `unique_field_key` is missing or isn't the key of a unique field on the custom object. In the job status `results`, each item of a `"delete_by_unique_field"` job reports the `unique_field_key` and `value` from the request, along with its `index` and `status` (for example, `"Deleted"`). An item that matches no record fails with "Record not found". Each item in a `"create_or_update_by_unique_field"` job reports the record's `id`, its `index` and `status`. An item without a value for the unique field fails with "Unique field value cannot be blank". If the field's uniqueness is turned off before the job runs, its items fail with "Uniqueness must be enabled on the field to identify records by it". #### Allowed For * Agents #### 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.

    POST /api/v2/custom_objects/{custom_object_key}/jobs

  • Write

    Create Custom Object Record

    Creates a custom object record according to all the properties described by a custom object definition. If `autoincrement_enabled` is true, record names aren't allowed in the request body because they are generated automatically. If `is_unique` is true, record names must be unique. If the custom object has a parent relationship field, the parent field is required and must reference a valid parent record. Set the value in `custom_object_fields` using the parent record's id, external id (`"external_id:value"`), or name (`"name:value"`). #### Allowed For * Agents

    POST /api/v2/custom_objects/{custom_object_key}/records

  • Write

    Create or Update Custom Object Record

    Creates or updates a custom object record based on the provided external id, name, or unique field value. If a record exists for the given identifier, the endpoint updates it. Only the specified attributes are updated. Otherwise, the endpoint creates a new record with the provided identifier and other attributes. Specify only one identifier per request. * The `is_unique` property on the custom object's name field must be enabled in order to update or create by name. * To update or create by a unique field, send the field's key as the query parameter, for example `?vin=1HGCM82633A004352`. The field's `is_unique` property must be enabled. A new record is created with that value in the field. #### Allowed For * Agents

    PATCH /api/v2/custom_objects/{custom_object_key}/records

  • Write

    Update Custom Object Record

    Updates an individual custom object record. The updating rules are as follows: * Takes a `custom_object_record` object that specifies the properties to update * The custom object fields should be nested inside a `custom_object_fields` object #### Allowed For * Agents

    PATCH /api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id}

  • Write

    Filtered Search of Custom Object Records

    Returns an array of custom object records that meet the search and filter criteria. For simple searches limited to only text fields and no complex logic, use the [Search Custom Object Records API](/api-reference/custom-data/custom-objects/custom_object_records/#search-custom-object-records) endpoint. If the object has a parent field with `cascade_permissions_enabled`, non-admin agents must include a filter on the parent field (for example, `"custom_object_fields.parent_field_key": { "$eq": "parent_record_id" }`). Requests without a parent filter return `403 Forbidden`. Filters can contain either an individual [comparison object](#comparison-object) or an array of filter expressions within logical namespaces. Filter expressions can themselves be either comparison objects or `$and` / `$or` groups, so logical operators can be nested to build complex Boolean queries. A filter is a JSON object that has the following properties: | Name | Type | Required | Description | --------- | ------ | -------- | ----------- | ATTRIBUTE | object | no | A [comparison object](#comparison-object) specifying an attribute value condition to be met for records to match.<br/><br/>Examples are marked below. | $and | array | no | Array of filter expressions combined with logical AND. Each element may be a comparison object or a nested `$and` / `$or` group. | $or | array | no | Array of filter expressions combined with logical OR. Each element may be a comparison object or a nested `$and` / `$or` group. Limits for nested `$and` / `$or` groups: * Maximum nesting depth: `5` (outermost `$and` / `$or` counts as level 1). Exceeding it returns `422 Invalid Condition`. * Attribute keys cannot share a level with `$and` / `$or` once the payload contains any `$and` / `$or` nested inside another `$and` / `$or`. The request returns `422 Invalid Condition`; wrap the attribute inside the group instead. ##### Examples ```js { "filter": { "custom_object_fields.field_key": { "$eq": "value" } // ATTRIBUTE } } ``` ```js { "filter": { "$or": [ { "custom_object_fields.field_key": { "$eq": "value" } }, // ATTRIBUTE { "external_id": { "$eq": "Record123" } } // ATTRIBUTE ] } } ``` ```js // Nested $and / $or { "filter": { "$and": [ { "custom_object_fields.contract_term_months": { "$gt": 5 } }, { "$or": [ { "custom_object_fields.status": { "$eq": "active" } }, { "custom_object_fields.status": { "$eq": "pending" } } ] } ] } } ``` #### Comparison Object A comparison object defines a condition a record must meet to be considered a match. The condition is based on an attribute value or object type. A comparison object is a JSON object that has the following properties: | Name | Type | Required | Description | --------- | ------------- | -------- | ----------- | FIELD_KEY | string | yes | When filtering on a custom field, they must be namedspaced with `custom_object_fields.`. ex. `custom_object_fields.field_key`<br/><br/>When filtering on a standard field, no namespace is required. The following fields are considered standard: `created_at`, `updated_at`, `created_by_user`, `updated_by_user`, `name`, `external_id` | OPERATOR | string | yes | [Supported operators](/documentation/custom-data/v2/searching-custom-object-records/) vary by the value's data type | VALUE | string, array | yes | The value you're filtering for * Date values should be in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. * Returns the records sorted by relevancy with page limits. Without a `sort` parameter, only the first 10,000 records are returned. With a `sort` parameter, all records are returned. #### Allowed For * Agents * End users (when an admin [configures](https://support.zendesk.com/hc/en-us/articles/6034260247066) the custom object to be accessible to end users)

    POST /api/v2/custom_objects/{custom_object_key}/records/search

  • Write

    Update Custom Object Record by Unique Identifier

    Updates a custom object record identified by its external id, its name, or the value of one of the custom object's unique fields. Unlike [Create or Update Custom Object Record](#create-or-update-custom-object-record), it never creates a record. Send exactly one identifier per request. * To identify the record by name, the `is_unique` property on the custom object's name field must be enabled. * To identify the record by a unique field, send the field's key as the query parameter, for example `?vin=1HGCM82633A004352`. The field's `is_unique` property must be enabled. For a unique lookup field, the value is the id of the record the field references. The update rules are the same as for [Update Custom Object Record](#update-custom-object-record): * Send a `custom_object_record` object that specifies the properties to update * Nest the custom object fields inside a `custom_object_fields` object Returns a `400 Bad Request` if more than one identifier is sent, if `name` is sent and the name field isn't unique, or if no identifier is sent. A parameter that isn't the key of a unique field doesn't count as an identifier. Returns a `404 Not Found` if no record matches. #### Allowed For * Agents

    PATCH /api/v2/custom_objects/{custom_object_key}/records/update_by_unique_identifier

  • Destructive

    Delete Custom Object Record by External Id Or Name

    Deletes a record with the specified external id, name, or unique field value. Specify only one identifier per request. * The `is_unique` property on the custom object's name field must be enabled in order to delete by name. * To delete by a unique field, send the field's key as the query parameter, for example `?vin=1HGCM82633A004352`. The field's `is_unique` property must be enabled. If the record is a parent in a parent-child relationship, all associated child records are also deleted asynchronously via a background job. #### Allowed For * Agents

    DELETE /api/v2/custom_objects/{custom_object_key}/records

  • Destructive

    Delete Custom Object Record

    Deletes a record with the specified id. If the record is a parent in a parent-child relationship, all associated child records are also deleted asynchronously via a background job. Child records are soft-deleted first and then permanently deleted after a 30-day retention period. The delete request returns immediately; the cascade deletion happens in the background. #### Allowed For * Agents

    DELETE /api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id}

  • Destructive

    Update Custom Object Record by Unique Identifier (PUT)

    Same as [Update Custom Object Record by Unique Identifier](#update-custom-object-record-by-unique-identifier), using PUT. #### Allowed For * Agents

    PUT /api/v2/custom_objects/{custom_object_key}/records/update_by_unique_identifier

Custom Object Record Attachments

  • Read

    List Custom Object Record Attachments

    Lists all attachments associated with a custom object record. #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/records/{record_id}/attachments

  • Read

    Download Custom Object Record Attachment

    Downloads the specified attachment content. Returns a redirect to the attachment's content URL. Access to malicious attachments is controlled by the `malware_access_override` setting. #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/records/{record_id}/attachments/{id}/download

  • Write

    Create Custom Object Record Attachment

    Creates a new attachment associated with a custom object record. The custom object must have the "allows_attachments" setting enabled. #### Allowed For * Agents

    POST /api/v2/custom_objects/{custom_object_key}/records/{record_id}/attachments

  • Destructive

    Update Custom Object Record Attachment for Malware

    Updates malware access settings for the specified attachment. This is typically used to allow access to attachments that were flagged as containing malware. #### Allowed For * Admins

    PUT /api/v2/custom_objects/{custom_object_key}/records/{record_id}/attachments/{id}

  • Destructive

    Delete Custom Object Record Attachment

    Deletes the specified attachment associated with a custom object record. #### Allowed For * Agents

    DELETE /api/v2/custom_objects/{custom_object_key}/records/{record_id}/attachments/{id}

Object Triggers

  • Read

    List Object Triggers

    Lists all triggers for the specified custom object. #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/triggers

  • Read

    Show Object Trigger

    Returns details of a specific object trigger. #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/triggers/{trigger_id}

  • Read

    List Active Object Triggers

    Lists all active object triggers. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Administrators * Agents in custom roles with the `manage_triggers` permission (Enterprise only)

    GET /api/v2/custom_objects/{custom_object_key}/triggers/active

  • Read

    List Object Trigger Action and Condition Definitions

    Lists the conditions and actions of all triggers for the specified custom object. #### Allowed For * Agents

    GET /api/v2/custom_objects/{custom_object_key}/triggers/definitions

  • Read

    Search Object Triggers

    Returns a list of object triggers that meet your filter or search criteria. #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/introduction/pagination/#using-offset-pagination). #### Allowed For * Agents #### Filter Use the `filter` query parameter to filter an object trigger search by one or more attributes. For example, the following `filter` argument filters object triggers by the `title` attribute: ```json { "json": { "title": "test" } } ```

    GET /api/v2/custom_objects/{custom_object_key}/triggers/search

  • Write

    Create Object Trigger

    Creates a new object trigger for a specified object. #### Allowed For * Administrators * Agents in custom roles with the `manage_triggers` permission (Enterprise only)

    POST /api/v2/custom_objects/{custom_object_key}/triggers

  • Destructive

    Update Object Trigger

    Updates a specified object trigger. **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. #### Allowed For * Administrators * Agents in custom roles with the `manage_triggers` permission (Enterprise only)

    PUT /api/v2/custom_objects/{custom_object_key}/triggers/{trigger_id}

  • Destructive

    Delete Object Trigger

    Deletes a specified object trigger. #### Allowed For * Administrators * Agents in custom roles with the `manage_triggers` permission (Enterprise only)

    DELETE /api/v2/custom_objects/{custom_object_key}/triggers/{trigger_id}

  • Destructive

    Delete Many Object Triggers

    Deletes the object triggers corresponding to the provided comma-separated list of ids. **Note**: You can only bulk-delete triggers associated with one object at a time, specified by the `custom_object_key` in the request. #### Allowed For * Administrators * Agents in custom roles with the `manage_triggers` permission (Enterprise only) #### Request Parameters The DELETE request takes an `ids` object that lists the object triggers to delete. All of the specified object trigger `ids` must be associated with a single object. | Name | Description | ---- | ----------- | ids | The ids of the triggers to delete #### Example request ```js { "ids": "25,23,27,22" } ```

    DELETE /api/v2/custom_objects/{custom_object_key}/triggers/destroy_many

  • Destructive

    Update Many Object Triggers

    Updates the position or the active status of multiple object triggers. Any additional properties are ignored. **Note**: You can only bulk-update triggers associated with one object at a time, specified by the `custom_object_key` in the request. #### Allowed For * Administrators * Agents in custom roles with the `manage_triggers` permission (Enterprise only) #### Request Parameters The PUT request expects a `triggers` object that lists the object triggers to update. All of the specified object trigger `ids` must be associated with a single object. You can specify the following properties for each object trigger you're updating: | Name | Mandatory | Description | -------- | --------- | ----------- | id | yes | The ID of the object trigger to update | position | no | The new position of the object trigger | active | no | The active status of the object trigger (true or false) #### Example Request ```js { "triggers": [ {"id": 25, "position": 3}, {"id": 23, "active": true}, {"id": 27, "position": 9, "active": false}, {"id": 22, "position": 7} ] } ```

    PUT /api/v2/custom_objects/{custom_object_key}/triggers/update_many

Custom Roles

  • Read

    List Custom Roles

    #### Availability * Accounts on the Enterprise plan or above #### Allowed For * Agents

    GET /api/v2/custom_roles

  • Read

    Show Custom Role

    #### Availability * Accounts on the Enterprise plan or above #### Allowed for * Agents

    GET /api/v2/custom_roles/{custom_role_id}

  • Write

    Create Custom Role

    #### Availability * Accounts on the Enterprise plan or above #### Allowed for * Administrators * Agents with the `manage_roles` permission

    POST /api/v2/custom_roles

  • Destructive

    Update Custom Role

    #### Availability * Accounts on the Enterprise plan or above #### Allowed for * Administrators Agents with the `manage_roles` permission

    PUT /api/v2/custom_roles/{custom_role_id}

  • Destructive

    Delete Custom Role

    #### Availability * Accounts on the Enterprise plan or above #### Allowed for * Administrators * Agents with the `manage_roles` permission

    DELETE /api/v2/custom_roles/{custom_role_id}

Custom Ticket Statuses

  • Read

    List Custom Ticket Statuses

    Lists all undeleted custom ticket statuses for the account. No pagination is provided. #### Allowed For * End Users

    GET /api/v2/custom_statuses

  • Read

    Show Custom Ticket Status

    Returns the custom ticket status object. #### Allowed For * End Users

    GET /api/v2/custom_statuses/{custom_status_id}

  • Read

    Show Many Custom Ticket Statuses

    Returns the undeleted custom ticket statuses specified by a comma-separated list of ids. Up to 100 ids are accepted. If `ids` is not provided, all undeleted custom ticket statuses for the account are returned. The response payload matches the [List Custom Ticket Statuses](#list-custom-ticket-statuses) response format. #### Allowed For * End Users

    GET /api/v2/custom_statuses/show_many

  • Write

    Create Custom Ticket Status

    Takes a `custom_status` object that specifies the custom ticket status properties to create. #### Allowed For * Admins

    POST /api/v2/custom_statuses

  • Write

    Create Ticket Form Statuses for a Custom Status

    Creates one or many tickets form status associations for a custom status. #### Allowed For * Admins

    POST /api/v2/custom_statuses/{custom_status_id}/ticket_form_statuses

  • Destructive

    Bulk Update Default Custom Ticket Status

    Updates the default values for many custom ticket statuses at once. #### Allowed For * Admins

    PUT /api/v2/custom_status/default

  • Destructive

    Update Custom Ticket Status

    Takes a `custom_status` object that specifies the properties to update. #### Allowed For * Admins

    PUT /api/v2/custom_statuses/{custom_status_id}

  • Destructive

    Delete Custom Ticket Status

    Deletes the custom ticket status. The status must first be unassigned from all active (non-closed) tickets before it can be deleted. #### Allowed For * Admins

    DELETE /api/v2/custom_statuses/{custom_status_id}

Tickets

  • Read

    List Deleted Tickets

    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/4408887617050) 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/4408887617050). #### 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. These rate limits apply to both API calls and actions performed in the Admin Center. 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.

    GET /api/v2/deleted_tickets

  • Read

    List Organization Tickets

    Returns a list of tickets for a specific organization. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). #### Allowed For * Agents

    GET /api/v2/organizations/{organization_id}/tickets

  • Read

    Count Organization Tickets

    Returns an approximate count of tickets for a specific organization. If the count exceeds 100,000, it is updated 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

    GET /api/v2/organizations/{organization_id}/tickets/count

  • Read

    List Ticket Problems

    The response is always ordered by `updated_at` in descending order #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/problems

  • Read

    List Tickets

    List Tickets. See the pinned request/response schema and parameters for the authoritative contract.

    GET /api/v2/tickets

  • Read

    Show Ticket

    Returns a number of ticket properties, but doesn't include the full comment thread. The initial comment is available in the ticket's [description property](/api-reference/ticketing/tickets/tickets/#json-format). To retrieve all the ticket's comments, use [List Comments](/api-reference/ticketing/tickets/ticket_comments/#list-comments). #### Allowed For * Agents

    GET /api/v2/tickets/{ticket_id}

  • Read

    List Collaborators for a Ticket

    #### Allowed For * Agents

    GET /api/v2/tickets/{ticket_id}/collaborators

  • Read

    List Email CCs for a Ticket

    Returns any users cc'd on the ticket. #### Availability The [CCs and Followers](https://support.zendesk.com/hc/en-us/articles/4408822451482) feature must be enabled in Zendesk Support. If the feature is not enabled, the default CC functionality is used. In that case, use [List Collaborators](/api-reference/ticketing/tickets/tickets/#list-collaborators-for-a-ticket) to list the users cc'ed on the ticket. #### Allowed For * Agents

    GET /api/v2/tickets/{ticket_id}/email_ccs

  • Read

    List Followers for a Ticket

    Returns any users who follow the ticket. #### Availability The [CCs and Followers](https://support.zendesk.com/hc/en-us/articles/4408822451482) feature must be enabled in Zendesk Support. #### Allowed For * Agents

    GET /api/v2/tickets/{ticket_id}/followers

  • Read

    List Ticket Incidents

    #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/tickets/{ticket_id}/incidents

  • Read

    Ticket Related Information

    The request returns a data object with the following properties: | Name | Type | Comment | ------------------- | ------- | ------- | topic_id | string | Related topic in the Web portal (deprecated feature) | jira_issue_ids | array | Array of associated jira issues | followup_source_ids | array | Sources to follow up | from_archive | boolean | Is true if the current ticket is archived | incidents | integer | A count of related incident occurrences #### Allowed For * Agents

    GET /api/v2/tickets/{ticket_id}/related

  • Read

    Autocomplete Tickets

    Returns tickets whose subject matches the value specified in the `name` parameter. #### Allowed For * Agents

    GET /api/v2/tickets/autocomplete

  • Read

    Count Tickets

    Returns an approximate count of tickets in the account. If the count exceeds 100,000, it is updated every 24 hours. `ccd` lists tickets that the specified user is cc'd on. 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

    GET /api/v2/tickets/count

  • Read

    Show Ticket by Messaging Conversation ID

    Returns the active ticket associated with the given Sunshine Conversations conversation id. A ticket is considered active when it's open and the messaging session is still in progress. A ticket becomes inactive when any of the following occur: * The ticket is closed * An agent ends the messaging session * A trigger ends the messaging session #### Allowed For * Agents with the `view_private_content` permission

    GET /api/v2/tickets/messaging/conversations/{conversation_id}/ticket

  • Read

    List Recent Tickets

    Lists up to five tickets that the requesting agent recently viewed or created in the agent interface. #### Allowed For * Agents

    GET /api/v2/tickets/recent

  • Read

    Show Multiple Tickets

    Accepts a comma-separated list of ticket ids to return. This endpoint will return up to 100 tickets records. #### Allowed For * Agents

    GET /api/v2/tickets/show_many

  • Read

    List User Assigned Tickets

    Lists tickets assigned to the specified user.

    GET /api/v2/users/{user_id}/tickets/assigned

  • Read

    Count User Assigned Tickets

    Returns an approximate count of tickets assigned to the specified user. If the count exceeds 100,000, it is updated 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

    GET /api/v2/users/{user_id}/tickets/assigned/count

  • Read

    List User CCD Tickets

    Lists tickets where the specified user is CC'd.

    GET /api/v2/users/{user_id}/tickets/ccd

  • Read

    Count User CCD Tickets

    Returns an approximate count of tickets where the specified user is CC'd. If the count exceeds 100,000, it is updated 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

    GET /api/v2/users/{user_id}/tickets/ccd/count

  • Read

    List User Followed Tickets

    Lists tickets the specified user is following.

    GET /api/v2/users/{user_id}/tickets/followed

  • Read

    List User Requested Tickets

    List User Requested Tickets. See the pinned request/response schema and parameters for the authoritative contract.

    GET /api/v2/users/{user_id}/tickets/requested

  • Write

    Autocomplete Problems

    Returns tickets whose type is "problem" and whose subject contains the string specified in the `text` parameter. You can specify the `text` parameter in the request body rather than the query string. Example: `{"text": "fire"}` #### Allowed For * Agents

    POST /api/v2/problems/autocomplete

  • Write

    Create Ticket

    Create Ticket. See the pinned request/response schema and parameters for the authoritative contract.

    POST /api/v2/tickets

  • Write

    Create Many Tickets

    Accepts an array of up to 100 ticket objects. **Note**: Every ticket created with this endpoint may be affected by your business rules, which can include sending email notifications to your end users. If you are importing historical tickets or creating more than 1000 tickets, consider using the [Ticket Bulk Import](/api-reference/ticketing/tickets/ticket_import/#ticket-bulk-import) endpoint. 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. #### Allowed For * Agents

    POST /api/v2/tickets/create_many

  • Destructive

    Delete Ticket Permanently

    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 /api/v2/deleted_tickets/{ticket_id}

  • Destructive

    Restore a Previously Deleted Ticket

    #### Allowed For * Agents

    PUT /api/v2/deleted_tickets/{ticket_id}/restore

  • Destructive

    Delete Multiple Tickets Permanently

    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. 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. #### Allowed For * Agents

    DELETE /api/v2/deleted_tickets/destroy_many

  • Destructive

    Restore Previously Deleted Tickets in Bulk

    #### Allowed For * Agents

    PUT /api/v2/deleted_tickets/restore_many

  • Destructive

    Update Ticket

    Update Ticket. See the pinned request/response schema and parameters for the authoritative contract.

    PUT /api/v2/tickets/{ticket_id}

  • Destructive

    Delete Ticket

    #### Allowed For * Admins * Agents with permission to delete tickets Agent delete permissions are set in Support. See [Deleting tickets](https://support.zendesk.com/hc/en-us/articles/4408883872538) in the Support Help Center. #### Ticket deletion rate limit You can delete 400 tickets every 1 minute using this endpoint. The rate limiting mechanism behaves as described in [Rate limits](/api-reference/introduction/rate-limits/) in the API introduction. Zendesk recommends that you obey the Retry-After header values. To delete many tickets, you may use [Bulk Delete Tickets](/api-reference/ticketing/tickets/tickets/#bulk-delete-tickets).

    DELETE /api/v2/tickets/{ticket_id}

  • Destructive

    Mark Ticket as Spam and Suspend Requester

    #### Allowed For * Agents

    PUT /api/v2/tickets/{ticket_id}/mark_as_spam

  • Destructive

    Merge Tickets into Target Ticket

    Merges one or more tickets into the ticket with the specified id. See [Merging tickets](https://support.zendesk.com/hc/en-us/articles/4408882445594) in the Support Help Center for ticket merging rules. Any attachment to the source ticket is copied to the target ticket. 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. #### Allowed For * Agents Agents in the Enterprise account must have merge permissions. See [Creating custom roles and assigning agents](https://support.zendesk.com/hc/en-us/articles/4408882153882) in Zendesk help. #### Available parameters The request takes a data object with the following properties: | Name | Type | Required | Comments | | ------------------------ | ------- | -------- | ------------------------------------------------------- | | ids | array | yes | Ids of tickets to merge into the target ticket | | target_comment | string | no | Private comment to add to the target ticket. This comment is optional but strongly recommended | | source_comment | string | no | Private comment to add to the source ticket. This comment is optional but strongly recommended | | target_comment_is_public | boolean | no | Whether comments in the target ticket are public or private | | source_comment_is_public | boolean | no | Whether comments in the source tickets are public or private | `target_comment` and `source_comment` can be used to provide a reason for the merge for recordkeeping purposes. If the source ticket has attachments, they are included in `target_comment`. Comments are private and can't be modified in the following cases: * Any of the sources or target tickets are private * Any of the sources or target tickets were created through X (formerly Twitter), Facebook or the Channel framework In any other case, comments default to private but can be modified with the comment privacy parameters.

    POST /api/v2/tickets/{ticket_id}/merge

  • Destructive

    Bulk Delete Tickets

    Accepts a comma-separated list of up to 100 ticket ids. #### Allowed For * Admins * Agents with permission to delete tickets Agent delete permissions are set in Support. See [Deleting tickets](https://support.zendesk.com/hc/en-us/articles/4408883872538) in the Support Help Center. 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.

    DELETE /api/v2/tickets/destroy_many

  • Destructive

    Bulk Mark Tickets as Spam

    Accepts a comma-separated list of up to 100 ticket ids. 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. #### Allowed For * Agents

    PUT /api/v2/tickets/mark_many_as_spam

  • Destructive

    Update Many Tickets

    Accepts an array of up to 100 ticket objects, or a comma-separated list of up to 100 ticket ids.

    PUT /api/v2/tickets/update_many

Users

  • Read

    List 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](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents

    GET /api/v2/deleted_users

  • Read

    Show Deleted User

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

    GET /api/v2/deleted_users/{deleted_user_id}

  • Read

    Count 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

    GET /api/v2/deleted_users/count

  • Read

    List Users By Group

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

    GET /api/v2/groups/{group_id}/users

  • Read

    Count Users By Group

    Returns an approximate count of users in the specified group. 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

    GET /api/v2/groups/{group_id}/users/count

  • Read

    List Organization Users

    Returns a list of users for a specific organization. #### 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

    GET /api/v2/organizations/{organization_id}/users

  • Read

    Count Organization Users

    Returns an approximate count of users for a specific organization. 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

    GET /api/v2/organizations/{organization_id}/users/count

  • Read

    List Users

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

    GET /api/v2/users

  • Read

    Show User

    #### Allowed For * Agents

    GET /api/v2/users/{user_id}

  • Read

    Show 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. ```http Status: 404 { "error":"RecordNotFound", "description":"Not found" } ``` #### Allowed For * Agents, with restrictions #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/users/{user_id}/compliance_deletion_statuses

  • Read

    Get Full User Entitlements

    Returns the full entitlements for all Zendesk products (Explore, Voice, Knowledge, Live Chat) for the specified user. This includes the role name and active status for each product. An entitlement is only considered active if both of the following conditions apply: the user has access and the product is active on the account. #### Allowed For * Agents #### OAuth Scopes Requires one of the following OAuth scopes: `users:read` or `read`

    GET /api/v2/users/{user_id}/entitlements/full

  • Read

    Show User Related Information

    Show User Related Information. See the pinned request/response schema and parameters for the authoritative contract.

    GET /api/v2/users/{user_id}/related

  • Read

    Show a User's Suspension

    Shows the suspension details for a user. #### Allowed For * Agents #### OAuth Scopes Requires one of the following OAuth scopes: `users:read` or `read`

    GET /api/v2/users/{user_id}/suspension

  • Read

    Autocomplete Users

    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

    GET /api/v2/users/autocomplete

  • Read

    Count Users

    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

    GET /api/v2/users/count

  • Read

    Show Self

    The endpoint returns [user information](/api-reference/ticketing/users/users/) and an `authenticity_token`. #### Allowed For * Anonymous users #### Authenticity Token Zendesk 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. For 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.

    GET /api/v2/users/me

  • Read

    Show Current User Settings

    Returns the settings for the currently authenticated user. This includes UI preferences for onboarding, tooltips, keyboard shortcuts, theme preferences, and other feature toggles. #### Allowed For * Agents

    GET /api/v2/users/me/settings

  • Read

    Search Users

    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

    GET /api/v2/users/search

  • Read

    Show Many Users

    Accepts a comma-separated list of up to 100 user ids or external ids. #### Allowed For: * Agents

    GET /api/v2/users/show_many

  • Write

    Create User

    Create User. See the pinned request/response schema and parameters for the authoritative contract.

    POST /api/v2/users

  • Write

    Create a User Suspension

    Creates a suspension record for a user. A user can be suspended on specific channels via `suspended_channels`, when [the messaging channel suspension feature](https://support.zendesk.com/hc/en-us/articles/10575252020250-Announcing-user-suspension-from-messaging-channels-only) is enabled on the account. #### Allowed For * Admins * [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 #### OAuth Scopes Requires one of the following OAuth scopes: `users:write` or `write`

    POST /api/v2/users/{user_id}/suspension

  • Write

    Autocomplete Users by Request Body

    Returns an array of users whose name starts with the value specified in the `name` property in the request body. It only returns users with no foreign identities. This endpoint accepts the same parameters as the [GET method](#autocomplete-users-by-query-string) but they are specified in the request body instead of the query string. #### Allowed For * Agents

    POST /api/v2/users/autocomplete

  • Write

    Create Many Users

    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 or an admin 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.

    POST /api/v2/users/create_many

  • Write

    Logout many users

    Accepts a comma-separated list of up to 100 user ids. #### Allowed For: * Admins

    POST /api/v2/users/logout_many

  • Write

    Request User Create

    Sends the owner a reminder email to update their subscription so more agents can be created. #### Allowed For * Agents

    POST /api/v2/users/request_create

  • Destructive

    Permanently Delete 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 * 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

    DELETE /api/v2/deleted_users/{deleted_user_id}

  • Destructive

    Update User

    Update User. See the pinned request/response schema and parameters for the authoritative contract.

    PUT /api/v2/users/{user_id}

  • Destructive

    Delete User

    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

    DELETE /api/v2/users/{user_id}

  • Destructive

    Merge End Users

    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

    PUT /api/v2/users/{user_id}/merge

  • Destructive

    Update a User's Suspension

    Updates the suspension details for a user. `suspended_channels` can be updated when [the messaging channel suspension feature](https://support.zendesk.com/hc/en-us/articles/10575252020250-Announcing-user-suspension-from-messaging-channels-only) is enabled on the account. #### Allowed For * Admins * [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 #### OAuth Scopes Requires one of the following OAuth scopes: `users:write` or `write`

    PUT /api/v2/users/{user_id}/suspension

  • Destructive

    Delete the User Suspension

    Unsuspends the user by deleting their suspension record. #### Allowed For * Admins * [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 #### OAuth Scopes Requires one of the following OAuth scopes: `users:write` or `write`

    DELETE /api/v2/users/{user_id}/suspension

  • Destructive

    Create Or Update User

    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 already exists in Zendesk, a successful request returns a 200 OK status code. - If the user does not exist in Zendesk and is created, the request returns a 201 Created status code. - In both cases, the API responds with a JSON body containing the full user object, which includes the user's id and the fully-resolved URL to the user resource. Example response: ```json { "user": { "id": 8929981612030, "url": "https://{subdomain}.zendesk.com/api/v2/users/8929981612030", ... } } ``` #### 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

    POST /api/v2/users/create_or_update

  • Destructive

    Create Or Update Many Users

    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. **Note**: To protect the data in your Zendesk account, bulk user imports are not enabled by default in Zendesk accounts. The account owner or an admin 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. Each individual user object can identify an existing user by `email` or by `external_id`. 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. #### 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

    POST /api/v2/users/create_or_update_many

  • Destructive

    Bulk Delete Users

    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.

    DELETE /api/v2/users/destroy_many

  • Destructive

    Update Current User Settings

    Updates the settings for the currently authenticated user. This includes UI preferences for onboarding, tooltips, keyboard shortcuts, theme preferences, and other feature toggles. Settings are grouped into: - **Support**: Support UI preferences (onboarding, tooltips, shortcuts, theme) - **admin_center**: Admin Center UI preferences (navigation, onboarding) - **shared_views_order**: Optional array of view IDs for custom ordering - **agent_home_pinned_views**: Optional ordered array of view IDs pinned in the Agent Home sidebar (max 8) Only the specified settings will be updated. Other settings will remain unchanged. #### Allowed For * Agents

    PUT /api/v2/users/me/settings

  • Destructive

    Update Many Users

    Update Many Users. See the pinned request/response schema and parameters for the authoritative contract.

    PUT /api/v2/users/update_many

Deletion Schedules

  • Read

    List Deletion Schedules

    Lists all deletion schedules for the account. Deletion schedules are used to automatically delete data from the account after a certain period of time. #### Allowed For * Admins

    GET /api/v2/deletion_schedules

  • Read

    Get Deletion Schedule

    Gets a deletion schedule by its id. #### Allowed For * Admins

    GET /api/v2/deletion_schedules/{deletion_schedule_id}

  • Write

    Create Deletion Schedule

    Creates a new deletion schedule. #### Allowed For * Admins

    POST /api/v2/deletion_schedules

  • Destructive

    Update Deletion Schedule

    Updates a deletion schedule by its id. **Note**: Updating a condition updates the conditions array, clearing all existing values of the array. Include all your conditions when updating any condition. #### Allowed For * Admins

    PUT /api/v2/deletion_schedules/{deletion_schedule_id}

  • Destructive

    Delete Deletion Schedule

    Deletes a deletion schedule by its id. #### Allowed For * Admins

    DELETE /api/v2/deletion_schedules/{deletion_schedule_id}

Dynamic Content

  • Read

    List Items

    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 #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/dynamic_content/items

  • Read

    Show Item

    #### Allowed For * Admins, Agents

    GET /api/v2/dynamic_content/items/{dynamic_content_item_id}

  • Read

    Show Many Items

    #### Stability * Development #### Allowed For * Admins, Agents

    GET /api/v2/dynamic_content/items/show_many

  • Write

    Create Item

    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

    POST /api/v2/dynamic_content/items

  • Destructive

    Update 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

    PUT /api/v2/dynamic_content/items/{dynamic_content_item_id}

  • Destructive

    Delete Item

    #### Allowed For * Admins, Agents

    DELETE /api/v2/dynamic_content/items/{dynamic_content_item_id}

Dynamic Content Item Variants

  • Read

    List Variants

    Returns all the variants of the specified dynamic content item. #### Allowed For * Admins * Agents who have permission to manage dynamic content #### Pagination * Cursor pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/dynamic_content/items/{dynamic_content_item_id}/variants

  • Read

    Show Variant

    #### Allowed For * Admins, Agents

    GET /api/v2/dynamic_content/items/{dynamic_content_item_id}/variants/{dynamic_content_variant_id}

  • Write

    Create Variant

    You can only create one variant for each locale id. If a locale variant already exists, the request is rejected. #### Allowed For * Admins, Agents

    POST /api/v2/dynamic_content/items/{dynamic_content_item_id}/variants

  • Write

    Create Many Variants

    #### Allowed For * Admins, Agents

    POST /api/v2/dynamic_content/items/{dynamic_content_item_id}/variants/create_many

  • Destructive

    Update 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

    PUT /api/v2/dynamic_content/items/{dynamic_content_item_id}/variants/{dynamic_content_variant_id}

  • Destructive

    Delete Variant

    #### Allowed For * Admins, Agents

    DELETE /api/v2/dynamic_content/items/{dynamic_content_item_id}/variants/{dynamic_content_variant_id}

  • Destructive

    Update 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

    PUT /api/v2/dynamic_content/items/{dynamic_content_item_id}/variants/update_many

Email Notifications

  • Read

    List Email Notifications

    #### Allowed For * Agents #### Request parameters ##### Filters **Important**: You must specify a `filter` query parameter to narrow the scope of the search for this endpoint. * By notification: `api/v2/email_notifications?filter[notification_id]=7824075373693` * By comment: `api/v2/email_notifications?filter[comment_id]=782407` * By ticket: `api/v2/email_notifications?filter[ticket_id]=623` ##### Pagination By default, a maximum of 100 email notifications are included per page. Use cursor-based pagination parameters (`page[after]` and `page[before]`) to navigate the records (can't be used together in the same request). See [Pagination](/api-reference/introduction/pagination/) for more details. ##### Sorting By default, email notifications are sorted by creation time (newest first). The query parameter is not supported for this endpoint.

    GET /api/v2/email_notifications

  • Read

    Show Email Notification

    Shows details on an email notification. You can get the value of the `notification_id` parameter by listing the ticket's outbound emails. #### Allowed For * Agents

    GET /api/v2/email_notifications/{notification_id}

  • Read

    Show Many Email Notifications

    Shows details of many email notifications. Allows you to query by providing a list of notifications, comments, or tickets IDs. #### Allowed For * Agents #### Filters * By notification: `?ids=8433702508541,8433348111869` * By comment: `?comment_ids=8433348111741,8433544226045,8433702508413` * By ticket: `?ticket_ids=730,723`

    GET /api/v2/email_notifications/show_many

User Identities

  • Read

    List End User Identities

    Returns a list of identities for the given end user. End users can only list email and phone number identities. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page for cursor pagination. #### Allowed For * Verified end users

    GET /api/v2/end_users/{user_id}/identities

  • Read

    Show End User Identity

    Shows the identity with the given id for a given end user. End users can only view email or phone number identity. #### Allowed For * Verified end users

    GET /api/v2/end_users/{user_id}/identities/{user_identity_id}

  • Read

    List Identities

    Returns a list of identities for the given user. Use the first endpoint if authenticating as an agent. Use the second if authenticating as an end user. End users can only list email and phone number identities. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page for cursor pagination. #### Allowed For * Agents * Verified end users

    GET /api/v2/users/{user_id}/identities

  • Read

    Show Identity

    Shows the identity with the given id for a given user. Use the first endpoint if authenticating as an agent. Use the second if authenticating as an end user. End users can only view email or phone number identity. #### Allowed For * Agents * Verified end users

    GET /api/v2/users/{user_id}/identities/{user_identity_id}

  • Write

    Create End User Identity

    Adds an identity to an end user's profile. Supported identity types for end users: | Type | Example | | ---------------- | ------- | | email | `{ "type" : "email", "value" : "someone@example.com" }` | | phone_number | `{ "type" : "phone_number", "value" : "+1 555-123-4567" }` | #### Allowed For * Verified end users

    POST /api/v2/end_users/{user_id}/identities

  • Write

    Create Identity

    Adds an identity to a user's profile. An agent can add an identity to any user profile. Supported identity types: | Type | Example | | ---------------- | ------- | | email | `{ "type" : "email", "value" : "someone@example.com" }` | | twitter | `{ "type" : "twitter", "value" : "screen_name" }` | | facebook | `{ "type" : "facebook", "value" : "855769377321" }` | | google | `{ "type" : "google", "value" : "example@gmail.com" }` | | agent_forwarding | `{ "type" : "agent_forwarding", "value" : "+1 555-123-4567" }` | | phone_number | `{ "type" : "phone_number", "value" : "+1 555-123-4567" }` | To create an identity without sending out a verification email, include a `"skip_verify_email": true` property. The `"skip_verify_email": true` property does not apply when updating your own agent profile. A welcome or verification email will be sent regardless of this setting. #### Allowed For * Agents

    POST /api/v2/users/{user_id}/identities

  • Destructive

    Delete End User Identity

    Deletes the identity for a given end user. In certain cases, a phone number associated with an identity is still visible on the user profile after the identity has been deleted via API. #### Allowed For * Verified end users

    DELETE /api/v2/end_users/{user_id}/identities/{user_identity_id}

  • Destructive

    Make End User Identity Primary

    Sets the specified identity as primary for the end user. This is a collection-level operation and the correct behavior for an API client is to subsequently reload the entire collection. An end user can only make an email identity primary if the email is verified. #### Allowed For * Verified end users

    PUT /api/v2/end_users/{user_id}/identities/{user_identity_id}/make_primary

  • Destructive

    Request End User Verification

    Sends the end user a verification email with a link to verify ownership of the email address. #### Allowed For * Verified end users

    PUT /api/v2/end_users/{user_id}/identities/{user_identity_id}/request_verification

  • Destructive

    Update Identity

    This endpoint allows you to: * Set the specified identity as verified (by setting `verified` to "true" or `verification_method` to "low") * Unverify a verified identity (by setting `verified` to "false" or `verification_method` to "none") * Update the `value` property of the specified identity You can't change an identity's `primary` attribute with this endpoint. You must use the [Make Identity Primary](#make-identity-primary) endpoint instead. #### Allowed For * Agents

    PUT /api/v2/users/{user_id}/identities/{user_identity_id}

  • Destructive

    Delete Identity

    Deletes the identity for a given user. In certain cases, a phone number associated with an identity is still visible on the user profile after the identity has been deleted via API. You can remove the phone number from the user profile by updating the `phone` attribute of the user to an empty string. See [Update User via API](/api-reference/ticketing/users/users/#update-user) for details and examples. Deleting identities with type `messaging` could break messaging functionality. For example, an agent may stop being able to send messages via the messaging channel. #### Allowed For * Agents

    DELETE /api/v2/users/{user_id}/identities/{user_identity_id}

  • Destructive

    Make Identity Primary

    Sets the specified identity as primary. To change other attributes, use the [Update Identity](#update-identity) endpoint. This is a collection-level operation and the correct behavior for an API client is to subsequently reload the entire collection. The first endpoint is the preferred option if authenticating as an agent. If authenticating as an end user, you can only use the second endpoint. In addition, an end user can only make an email identity primary if the email is verified. #### Allowed For * Agents * Verified end users

    PUT /api/v2/users/{user_id}/identities/{user_identity_id}/make_primary

  • Destructive

    Request User Verification

    Sends the user a verification email with a link to verify ownership of the email address. #### Allowed For * Agents

    PUT /api/v2/users/{user_id}/identities/{user_identity_id}/request_verification

  • Destructive

    Verify Identity

    Sets the specified identity as verified. For security reasons, you can't use this endpoint to update the email identity of the account owner. To verify the person's identity, send a verification email. See [Verifying the account owner's email address](https://support.zendesk.com/hc/en-us/articles/4408828975130) in Zendesk help. If [automatic mapping of users to organizations using the email domain](https://support.zendesk.com/hc/en-us/articles/4408882246298-Creating-organizations#topic_nxl_vdt_bc) is enabled and the user is not already a member of an organization, they will be automatically added to the organization associated with the email domain once the email identity is verified. #### Allowed For * Agents

    PUT /api/v2/users/{user_id}/identities/{user_identity_id}/verify

Group Memberships

  • Read

    List Memberships

    #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Agents

    GET /api/v2/group_memberships

  • Read

    Show Membership

    The 'id' is the group membership id, not a group id. #### Allowed For * Agents

    GET /api/v2/group_memberships/{group_membership_id}

  • Read

    List Assignable Memberships

    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

    GET /api/v2/group_memberships/assignable

  • Read

    List Memberships By Group

    Returns a list of all group memberships for a specific group. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Agents

    GET /api/v2/groups/{group_id}/memberships

  • Read

    List Assignable Memberships By Group

    Returns a list of assignable group memberships for a specific group. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Agents

    GET /api/v2/groups/{group_id}/memberships/assignable

  • Read

    List Group Memberships by User

    #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Agents

    GET /api/v2/users/{user_id}/group_memberships

  • Read

    Show User's Group Membership

    Returns a specific group membership for a user. #### Allowed For * Agents

    GET /api/v2/users/{user_id}/group_memberships/{group_membership_id}

  • Write

    Create Membership

    Assigns an agent to a given group. #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

    POST /api/v2/group_memberships

  • Write

    Bulk Create Memberships

    Assigns up to 100 agents to given groups. #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage group memberships (Enterprise only) #### 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.

    POST /api/v2/group_memberships/create_many

  • Write

    Create Group Membership for User

    Assigns an agent to a given group. #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

    POST /api/v2/users/{user_id}/group_memberships

  • Destructive

    Delete 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 * Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

    DELETE /api/v2/group_memberships/{group_membership_id}

  • Destructive

    Bulk Delete 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 * Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

    DELETE /api/v2/group_memberships/destroy_many

  • Destructive

    Delete User's Group 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 * Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

    DELETE /api/v2/users/{user_id}/group_memberships/{group_membership_id}

  • Destructive

    Set Membership as Default

    #### Allowed For: * Agents

    PUT /api/v2/users/{user_id}/group_memberships/{group_membership_id}/make_default

Group SLA Policies

  • Read

    List Group SLA Policies

    #### Availability * Accounts on the Professional and Enterprise plans #### Allowed For * Admins

    GET /api/v2/group_slas/policies

  • Read

    Show Group SLA Policy

    #### Availability * Accounts on the Professional and Enterprise plans #### Allowed For * Admins

    GET /api/v2/group_slas/policies/{group_sla_policy_id}

  • Read

    Retrieve Supported Filter Definition Items

    #### Allowed For * Admins

    GET /api/v2/group_slas/policies/definitions

  • Read

    List Ticket Group SLA Policy Metrics

    Returns the Group SLA (OLA) policy metrics for a specific ticket. #### Availability * Accounts on the Enterprise plan #### Allowed For * Admins

    GET /api/v2/tickets/{ticket_id}/group_slas/policy_metrics

  • Write

    Create Group SLA Policy

    #### Allowed For * Admins

    POST /api/v2/group_slas/policies

  • Destructive

    Update Group SLA Policy

    Updates the specified policy. #### Allowed For * Admins

    PUT /api/v2/group_slas/policies/{group_sla_policy_id}

  • Destructive

    Delete Group SLA Policy

    #### Allowed For * Admins

    DELETE /api/v2/group_slas/policies/{group_sla_policy_id}

  • Destructive

    Reorder Group SLA Policies

    Reorders the group SLA policies. The new order is set in a `group_sla_policy_ids` array in the JSON request body. #### Allowed For * Admins

    PUT /api/v2/group_slas/policies/reorder

Groups

  • Read

    List Groups

    #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents

    GET /api/v2/groups

  • Read

    Show Group

    #### Allowed For * Admins * Agents

    GET /api/v2/groups/{group_id}

  • Read

    List Assignable Groups

    #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents

    GET /api/v2/groups/assignable

  • Read

    Autocomplete Groups

    Returns an array of groups whose name starts with the value specified in the `name` parameter. #### Allowed For * Admins * Agents

    GET /api/v2/groups/autocomplete

  • Read

    List Available Agents

    Returns a list of all agents available to be added to groups. The current user must have permission to edit group memberships. #### Pagination * Cursor pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 1000 records per page. #### Allowed For * Admins * Agents with permission to edit group memberships

    GET /api/v2/groups/available_agents

  • Read

    Count 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

    GET /api/v2/groups/count

  • Read

    Show Default Group

    #### Allowed For * Admins * Agents

    GET /api/v2/groups/default

  • Read

    List User Groups

    Returns a list of groups for the specified user. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents

    GET /api/v2/users/{user_id}/groups

  • Read

    Count User Groups

    Returns an approximate count of groups for the specified user. 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

    GET /api/v2/users/{user_id}/groups/count

  • Write

    Create Group

    #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage groups (Enterprise only)

    POST /api/v2/groups

  • Destructive

    Update Group

    #### Allowed For * Admins

    PUT /api/v2/groups/{group_id}

  • Destructive

    Delete Group

    #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage groups (Enterprise only)

    DELETE /api/v2/groups/{group_id}

Ticket Import

  • Write

    Ticket Import

    #### Allowed For * Admins

    POST /api/v2/imports/tickets

  • Write

    Ticket Bulk Import

    Accepts an array of up to 100 ticket objects. #### Allowed For * Admins

    POST /api/v2/imports/tickets/create_many

Incremental Export

  • Read

    Incremental Sample Export

    Use this endpoint to test the incremental export format. It's more strict in terms of rate limiting, at 10 requests per 20 minutes instead of 10 requests per minute. It also returns only up to 50 results per request. Otherwise, it's identical to the above APIs. Use the `incremental_resource` parameter to specify the resource. Possible values are "tickets", "ticket_events", "users", or "organizations". #### Allowed For * Admins

    GET /api/v2/incremental/{incremental_resource}/sample

  • Read

    Incremental Organization Export

    #### Allowed For * Admins #### Sideloading See [Organizations sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).

    GET /api/v2/incremental/organizations

  • Read

    Incremental Ticket Event Export

    Returns a stream of changes that occurred on tickets, excluding events occuring within one minute of the request. Each event is tied to an update on a ticket and contains all the fields that were updated in that change. For more information, see: - [Exporting ticket events](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#exporting-ticket-events) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api) - [Time-based incremental exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#time-based-incremental-exports) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api) You can include comments in the event stream by using the `comment_events` sideload. See Sideloading below. If you don't specify the sideload, any comment present in the ticket update is described only by Boolean `comment_present` and `comment_public` object properties in the event's `child_events` array. The comment itself is not included. The `child_events` within a parent `ticket_event` are ordered by `id` by default, which reflects the order the changes were actually applied. For example, when several "Change" events touch the same field in one update, the child event with the highest id is the final value of that field. #### Allowed For * Admins #### Sideloading The endpoint supports the `comment_events` sideload. Any comment present in the ticket update is listed as an object in the event's `child_events` array. Example: ```js "child_events": [ { "id": 91048994488, "via": { "channel": "api", "source": {"from":{},"to":{},"rel":null}}, "via_reference_id":null, "type": "Comment", "author_id": 5031726587, "body": "This is a comment", "html_body": "&lt;div class="zd-comment"&gt;&lt;p dir="auto"&gt;This is a comment&lt;/p&gt;", "public": true, "attachments": [], "audit_id": 91048994468, "created_at": "2009-06-25T10:15:18Z", "event_type": "Comment" }, ... ], ... ```

    GET /api/v2/incremental/ticket_events

  • Read

    Incremental Ticket Export, Time Based

    Returns the tickets that changed since the start time. For more information, see [Exporting tickets](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#exporting-tickets) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api). This endpoint supports time-based incremental exports. For more information, see [Time-based incremental exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#time-based-incremental-exports) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api). You can also return tickets using cursor-based pagination. See [Incremental Ticket Export, Cursor Based](#incremental-ticket-export-cursor-based). The results include tickets that were updated by the system. See [Excluding system-updated tickets](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#excluding-system-updated-tickets-time-based-exports) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api). The endpoint can return tickets with an `updated_at` time that's earlier than the `start_time` time. The reason is that the API compares the `start_time` with the ticket's `generated_timestamp` value, not its `updated_at` value. The `updated_at` value is updated only if the update generates a [ticket event](#incremental-ticket-event-export). The `generated_timestamp` value is updated for all ticket updates, including system updates. If a system update occurs after a ticket event, the unchanged `updated_at` time will become earlier relative to the updated `generated_timestamp` time. #### Allowed For * Admins #### Sideloading See [Tickets sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints). For performance reasons, `last_audits` sideloads aren't supported.

    GET /api/v2/incremental/tickets

  • Read

    Incremental Ticket Export, Cursor Based

    Returns the tickets that changed since the start time. For more information, see [Exporting tickets](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#exporting-tickets) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api). This endpoint supports cursor-based incremental exports. Cursor-based exports are highly encouraged because they provide more consistent performance and response body sizes. For more information, see [Cursor-based incremental exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#cursor-based-incremental-exports) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api). #### Allowed For * Admins #### Sideloading See [Tickets sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints). For performance reasons, `last_audits` sideloads aren't supported.

    GET /api/v2/incremental/tickets/cursor

  • Read

    Incremental User Export, Time Based

    #### Allowed For * Admins #### Sideloading See [Users sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).

    GET /api/v2/incremental/users

  • Read

    Incremental User Export, Cursor Based

    #### Allowed For * Admins #### Sideloading See [Users sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).

    GET /api/v2/incremental/users/cursor

Incremental Skill Based Routing

  • Read

    Incremental Attributes Values Export

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

    GET /api/v2/incremental/routing/attribute_values

  • Read

    Incremental Attributes Export

    Returns a stream of changes that occurred on routing attributes. #### 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).

    GET /api/v2/incremental/routing/attributes

  • Read

    Incremental Instance Values Export

    Returns a stream of changes that occurred on routing instance values. Changes are grouped by `attribute_value_id`, with associate type events listed alongside unassociate type events based on the unassociate event’s timestamp. #### 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).

    GET /api/v2/incremental/routing/instance_values

Ticket Metric Events

  • Read

    List Ticket Metric Events

    Returns ticket metric events that occurred on or after the start time. Cursor pagination returns a maximum of 100 records per page. Events are listed in chronological order. If the results are not paginated, events will be returned as a time-based incremental export. See [Time-based incremental exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#time-based-incremental-exports). #### Pagination * Cursor pagination See [Pagination](/api-reference/introduction/pagination/). #### Allowed For * Admins

    GET /api/v2/incremental/ticket_metric_events

  • Read

    List Ticket Metric Events by Ticket

    Lists the ticket metric events for a specific ticket. Returns a sorted list by metric instance, grouped by metric name. #### Allowed For * Admins, Agents

    GET /api/v2/tickets/{ticket_id}/metric_events

ITAM Asset Types

  • Read

    List Asset Types

    Lists all asset types. #### Allowed For * Agents

    GET /api/v2/it_asset_management/asset_types

  • Read

    Show Asset Type

    Returns an asset type with the specified id. #### Allowed For * Agents

    GET /api/v2/it_asset_management/asset_types/{asset_type_id}

  • Write

    Create Asset Type

    Creates an asset type. To set an icon at the same time, send a `multipart/form-data` request instead of JSON — see the "Create asset type with a photo" code sample. #### Allowed For * Admins

    POST /api/v2/it_asset_management/asset_types

  • Write

    Update Asset Type

    Updates an existing asset type. All fields are optional. Your request should include only the properties you want to change. The update will fail if you attempt to change the asset type's `parent_id`, the asset type's `name` isn't unique, the hierarchy depth limit would be exceeded, the asset type is one of the predefined standard asset types. To set an icon, send a `multipart/form-data` request instead of JSON — see the "Adding a photo to an asset type" code sample. To remove an existing icon, send `"photo": null` in a normal JSON request. #### Allowed For * Admins

    PATCH /api/v2/it_asset_management/asset_types/{asset_type_id}

  • Destructive

    Delete Asset Type

    Deletes an asset type with the specified id. The deletion will fail if the asset type is one of the predefined standard asset types, is a base asset type, has child asset types, has asset records, or still has custom field keys assigned to it. #### Allowed For * Admins

    DELETE /api/v2/it_asset_management/asset_types/{asset_type_id}

ITAM Asset Fields

  • Read

    List Asset Fields

    Lists all standard and custom fields for an asset type. #### Allowed For * Agents

    GET /api/v2/it_asset_management/asset_types/{asset_type_id}/fields

  • Read

    Show Asset Field

    Returns an asset field with the specified id. #### Allowed For * Agents

    GET /api/v2/it_asset_management/asset_types/{asset_type_id}/fields/{asset_type_field_id}

  • Read

    List Fields

    Lists all asset fields. #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. #### Allowed For * Agents

    GET /api/v2/it_asset_management/fields

  • Read

    Show Field

    Shows an asset field. #### Allowed For * Agents

    GET /api/v2/it_asset_management/fields/{id}

  • Write

    Create Field

    Creates an asset field. #### Allowed For * Admins

    POST /api/v2/it_asset_management/fields

  • Write

    Update Field

    Updates an asset field. #### Allowed For * Admins

    PATCH /api/v2/it_asset_management/fields/{id}

  • Destructive

    Delete Field

    Deletes an asset field. #### Allowed For * Admins

    DELETE /api/v2/it_asset_management/fields/{id}

ITAM Assets

  • Read

    List Assets

    Lists all assets for all asset types. #### Filtering Use the `filter[ids]` or `filter[external_ids]` query parameters to filter results by asset IDs or external IDs. Both parameters accept comma-separated values. #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. #### Allowed For * Agents

    GET /api/v2/it_asset_management/assets

  • Read

    Show Asset

    Returns the asset with the specified id. #### Allowed For * Agents

    GET /api/v2/it_asset_management/assets/{asset_id}

  • Read

    Search Assets

    Returns an array of assets with values in text-based fields that match the search query. If the query includes multiple words or numbers, it's treated as a space-separated list of search terms and assets with values matching one or more of the terms are returned. For example, `query=laptop Apple 2024` is encoded as `query=laptop%20Apple%202024` and treated as three distinct search terms: `laptop`, `Apple`, and `2024`. Every asset record with a text field containing 'laptop', 'Apple', or '2024' is returned. If you need to search by more complex logic, use the [Filtered Search API](/api-reference/it-asset-management/assets/#filtered-search-of-assets) endpoint. #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. * Returns the assets sorted by relevancy with page limits. Without a `sort` parameter, only the first 10,000 assets are returned. If your request includes a `sort` parameter, all assets are returned. #### Allowed For * Agents

    GET /api/v2/it_asset_management/assets/search

  • Write

    Create Asset

    Creates an asset. #### Allowed For * Admins

    POST /api/v2/it_asset_management/assets

  • Write

    Update Asset

    Updates an individual asset. This request takes an `asset` object that specifies the properties to update, with custom field values nested within a `custom_field_values` object. Values are updated only for the properties specified in the request. Any asset properties that aren't specified in the request are unaffected, and their values are preserved for the asset. #### Allowed For * Admins

    PATCH /api/v2/it_asset_management/assets/{asset_id}

  • Write

    Asset Bulk Jobs

    Queues a background job to perform bulk actions on up to 100 asset records per request. Takes a `job` object with two nested fields: * `action`, one of: * `"create"` * `"update"` * `"delete"` * `"delete_by_external_id"` * `items` * For a `"create"` action, an array of JSON objects representing the assets being created * For an `"update"` action, an array of JSON objects representing the assets being updated (must include `id` attribute) * For a `"delete"` action, an array of strings representing Zendesk asset ids * For a `"delete_by_external_id"` action, an array of strings representing external ids Note: For create and update actions, the `asset_type_id`, `status_id`, and `location_id` fields can be specified using either the ID or the name of the resource. For example, you can use `"asset_type_id": "01K9BW852KHGF59W0TM02J2F6H"` or `"asset_type": "Laptop"`. #### 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.

    POST /api/v2/it_asset_management/assets/jobs

  • Write

    Filtered Search of Assets

    Returns an array of assets that meet the complex search and filter criteria. For simple searches limited to text fields, use the [Search Assets API](/api-reference/it-asset-management/assets/#search-assets) endpoint instead. Filters can contain either an individual [comparison object](#comparison-object) or an array of [comparison objects](#comparison-object) within logical namespaces. A filter is a JSON object that has the following properties: | Name | Type | Required | Description | --------- | ------ | -------- | ----------- | ATTRIBUTE | object | no | A [comparison object](#comparison-object) specifying an attribute value condition to be met for assets to match.<br/><br/>Examples are marked below. | $and | array | no | Array of comparison objects combined using logical AND | $or | array | no | Array of comparison objects combined using logical OR ##### Examples ```js { "filter": { "model": { "$eq": "MacBook Pro" } // ATTRIBUTE (standard field) } } ``` ```js { "filter": { "custom_object_fields.ip_address": { "$eq": "192.168.1.1" } // ATTRIBUTE (custom field) } } ``` ```js // $or { "filter": { "$or": [ { "model": { "$eq": "MacBook Pro" } }, // ATTRIBUTE { "model": { "$eq": "ThinkPad X1" } } // ATTRIBUTE ] } } ``` #### Comparison Object A comparison object is essentially an 'if' statement that returns all asset records that meet the specified condition. Conditions are based on attribute values. A comparison object is a JSON object that has the following properties: | Name | Type | Required | Description | --------- | ------------- | -------- | ----------- | FIELD_KEY | string | yes | To filter on a custom asset field, you must prepend `custom_object_fields.` on the field key. For example: `custom_object_fields.ip_address`<br/><br/>The following standard asset fields can be used without needing to prepend a namespace: `asset_type`, `user`, `organization`, `location`, `model`, `purchase_date`, `status` | OPERATOR | string | yes | A comparison operator, such as `$eq` | VALUE | string, array | yes | The value you're filtering for * Date values should be in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. * Returns the assets sorted by relevancy with page limits. Requests with a `sort` parameter return all assets; requests without a `sort` parameter return the first 10,000 assets only. #### Allowed For * Agents

    POST /api/v2/it_asset_management/assets/search

  • Destructive

    Delete Asset

    Deletes an asset with the specified id. #### Allowed For * Admins

    DELETE /api/v2/it_asset_management/assets/{asset_id}

ITAM Asset Locations

  • Read

    List Asset Locations

    Lists all locations. #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. #### Allowed For * Agents

    GET /api/v2/it_asset_management/locations

  • Read

    Show Asset Location

    Returns the location with the specified id. #### Allowed For * Agents

    GET /api/v2/it_asset_management/locations/{location_id}

  • Write

    Create Asset Location

    Creates a location. #### Allowed For * Admins

    POST /api/v2/it_asset_management/locations

  • Write

    Update Asset Location

    Updates an existing location. #### Allowed For * Admins

    PATCH /api/v2/it_asset_management/locations/{location_id}

  • Destructive

    Delete Asset Location

    Deletes a location with the specified id. #### Allowed For * Admins

    DELETE /api/v2/it_asset_management/locations/{location_id}

ITAM Asset Statuses

  • Read

    List Asset Statuses

    Lists all statuses. #### Allowed For * Agents

    GET /api/v2/it_asset_management/statuses

  • Read

    Show Asset Status

    Returns the status with the specified id. #### Allowed For * Agents

    GET /api/v2/it_asset_management/statuses/{status_id}

  • Write

    Create Asset Status

    Creates a status. #### Allowed For * Admins

    POST /api/v2/it_asset_management/statuses

  • Write

    Update Asset Status

    Updates an existing status. Standard (system-defined) statuses cannot be modified. `category` cannot be changed after the status is created — it can only be set on create. #### Allowed For * Admins

    PATCH /api/v2/it_asset_management/statuses/{status_id}

  • Destructive

    Delete Asset Status

    Deletes a status with the specified id. Standard (system-defined) statuses cannot be deleted. Statuses assigned to assets cannot be deleted. #### Allowed For * Admins

    DELETE /api/v2/it_asset_management/statuses/{status_id}

Job Statuses

  • Read

    List Job Statuses

    Shows the statuses for background jobs. Statuses are sorted first by completion date and then by creation date in descending order. #### Allowed For: * Agents #### Pagination * Cursor pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/job_statuses

  • Read

    Show Job Status

    Shows the status of a background job. #### Allowed For: * Agents

    GET /api/v2/job_statuses/{job_status_id}

  • Read

    Show Many Job Statuses

    Accepts a comma-separated list of job status ids. #### Allowed For: * Agents

    GET /api/v2/job_statuses/show_many

Locales

  • Read

    List Locales

    Lists the translation locales available for the account. **Note**: You can alter the list by passing an updated `locale_ids` array to the [Update Account Settings](/api-reference/ticketing/account-configuration/account_settings/#update-account-settings) endpoint. #### Allowed For * Anyone

    GET /api/v2/locales

  • Read

    Show Locale

    #### Allowed For * Anyone

    GET /api/v2/locales/{locale_id}

  • Read

    List Locales for Agent

    Lists the translation locales that have been localized for agents on a specific account. #### Allowed For * Anyone

    GET /api/v2/locales/agent

  • Read

    Show Current Locale

    This works like [Show Locale](#show-locale), but instead of taking a locale id as an argument, it renders the locale of the user performing the request. #### Allowed For * Anyone

    GET /api/v2/locales/current

  • Read

    Detect Best Language for User

    #### Allowed For * Anyone

    GET /api/v2/locales/detect_best_locale

  • Read

    List Available Public Locales

    Lists the translation locales that are available to all accounts. #### Allowed For * Anyone

    GET /api/v2/locales/public

Macros

  • Read

    List Macros

    Lists all shared and personal macros available to the current user. For admins, the API returns all macros for the account, including the personal macros of agents and other admins. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents

    GET /api/v2/macros

  • Read

    Show Macro

    #### Allowed For * Agents

    GET /api/v2/macros/{macro_id}

  • Read

    Show Changes to Ticket

    Returns the changes the macro would make to a ticket. It doesn't actually change a ticket. You can use the response data in a subsequent API call to the [Tickets](/api-reference/ticketing/tickets/tickets/) endpoint to update the ticket. The response includes only the ticket fields that would be changed by the macro. To get the full ticket object after the macro is applied, see [Show Ticket After Changes](#show-ticket-after-changes). #### Allowed For * Agents

    GET /api/v2/macros/{macro_id}/apply

  • Read

    List Macro Attachments

    Lists the attachments associated with a macro. #### Allowed For * Agents

    GET /api/v2/macros/{macro_id}/attachments

  • Read

    List Supported Actions for Macros

    #### Allowed For * Agents

    GET /api/v2/macros/actions

  • Read

    List Active Macros

    Lists all active shared and personal macros available to the current user. #### Allowed For * Agents

    GET /api/v2/macros/active

  • Read

    Show Macro Attachment

    Shows the properties of the specified macro attachment. #### Allowed For * Agents

    GET /api/v2/macros/attachments/{attachment_id}

  • Read

    Download Macro Attachment

    Downloads the file content of the specified macro attachment. The response `Content-Type` matches the attachment's content type. #### Allowed For * Agents

    GET /api/v2/macros/attachments/{attachment_id}/content

  • Read

    List Macro Categories

    Lists all macro categories available to the current user. #### Allowed For * Agents

    GET /api/v2/macros/categories

  • Read

    List Macro Action Definitions

    Returns the definitions of the actions a macro can perform. For example, one action can set the status of a ticket. The definition of the action includes a title ("Status"), a type ("list"), and possible values. For a list of support actions, see [Actions reference](/documentation/ticketing/reference-guides/actions-reference). #### Allowed For * Agents

    GET /api/v2/macros/definitions

  • Read

    List Macro Groups

    Lists active groups associated with at least one macro. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). #### Allowed For * Agents

    GET /api/v2/macros/groups

  • Read

    List Most Used Macros

    Returns up to 10 most used macros for the current user. When there are no most used macros, an empty array is returned. #### Allowed For * Agents

    GET /api/v2/macros/most_used

  • Read

    Show Macro Replica

    Returns an unpersisted macro representation derived from a ticket or macro. The endpoint takes one of the following query parameters: `macro_id` or `ticket_id`. If you include both, `macro_id` is used. #### Allowed For * Agents

    GET /api/v2/macros/new

  • Read

    Search Macros

    #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/introduction/pagination/#using-offset-pagination). #### Allowed For * Agents

    GET /api/v2/macros/search

  • Read

    Show Ticket After Changes

    Returns the full ticket object as it would be after applying the macro to the ticket. It doesn't actually change the ticket. To get only the ticket fields that would be changed by the macro, see [Show Changes to Ticket](#show-changes-to-ticket). #### Allowed For * Agents

    GET /api/v2/tickets/{ticket_id}/macros/{macro_id}/apply

  • Write

    Create Macro

    #### Allowed For * Agents

    POST /api/v2/macros

  • Write

    Create Macro Attachment

    Allows an attachment to be uploaded and associated with a macro at the same time. **Note:** A macro can be associated with up to five attachments. #### Allowed For * Agents

    POST /api/v2/macros/{macro_id}/attachments

  • Write

    Create Unassociated Macro Attachment

    Allows an attachment to be uploaded that can be associated with a macro at a later time. **Note:** To ensure an uploaded attachment is not lost, associate it with a macro as soon as possible. From time to time, old attachments that are not not associated with any macro are purged. #### Allowed For * Agents

    POST /api/v2/macros/attachments

  • Destructive

    Update Macro

    #### Allowed For * Agents

    PUT /api/v2/macros/{macro_id}

  • Destructive

    Delete Macro

    #### Allowed For * Agents, with restrictions applying on certain actions

    DELETE /api/v2/macros/{macro_id}

  • Destructive

    Bulk Delete Macros

    Deletes the macros corresponding to the provided comma-separated list of IDs. #### Allowed For * Agents

    DELETE /api/v2/macros/destroy_many

  • Destructive

    Update Many Macros

    Updates the provided macros with the specified changes. #### Allowed For * Agents

    PUT /api/v2/macros/update_many

OAuth Clients

  • Read

    List Clients

    #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins

    GET /api/v2/oauth/clients

  • Read

    Show Client

    #### Allowed for * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission

    GET /api/v2/oauth/clients/{oauth_client_id}

  • Read

    List Current User's Clients

    Returns the OAuth clients owned by the current user. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission

    GET /api/v2/users/me/oauth/clients

  • Write

    Create Client

    #### Allowed For * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission #### Allowed scopes You can optionally set a `scope` property on the client to restrict which scopes it is permitted to request during the OAuth authorization flow. The value is a space-separated string of scope values. When set, any token request using this client must only include scopes from this list. If a client requests a scope not included in its allowed scopes, the request fails with a `400 Bad Request` response and an `invalid_scope` error. If `scope` is omitted, no scope restrictions are applied to the client. For the full list of valid scope values, see [Scopes](/api-reference/ticketing/oauth/grant_type_tokens/#scope).

    POST /api/v2/oauth/clients

  • Destructive

    Update Client

    #### Allowed for * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission

    PUT /api/v2/oauth/clients/{oauth_client_id}

  • Destructive

    Delete Client

    #### Allowed for * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission

    DELETE /api/v2/oauth/clients/{oauth_client_id}

  • Destructive

    Generate Secret

    #### Allowed for * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission

    PUT /api/v2/oauth/clients/{oauth_client_id}/generate_secret

Global Clients

  • Read

    List Global OAuth Clients

    Returns all the global OAuth clients that users on your account have authorized. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission

    GET /api/v2/oauth/global_clients

  • Read

    Show Global OAuth Client

    Returns the global OAuth client associated with the ID sent on the request. #### Allowed for * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission

    GET /api/v2/oauth/global_clients/{global_client_id}

  • Read

    Show Token summary for Global OAuth Clients

    Returns information about tokens for the global clients that your account has authorized. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents with the [Manage APIs](https://support.zendesk.com/hc/en-us/articles/4408882153882) permission

    GET /api/v2/oauth/global_clients/token_summary

OAuth Tokens

  • Read

    List Tokens

    Returns the properties of the tokens for the current user. Admins can view OAuth token properties for all users using the [all](/api-reference/ticketing/oauth/oauth_tokens/#parameters) parameter. To filter the list by OAuth client, use the [client_id](/api-reference/ticketing/oauth/oauth_tokens/#parameters) parameter for a local OAuth client ID, or the [global_client_id](/api-reference/ticketing/oauth/oauth_tokens/#parameters) parameter for a global OAuth client ID. For security reasons, only the first 10 characters of each access token are included. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins

    GET /api/v2/oauth/tokens

  • Read

    Show Token

    Returns the properties of the specified token. For security reasons, only the first 10 characters of the access token are included. In the first endpoint, `id` is a token id, not the full token. In the second endpoint, include an `Authorization: Bearer` header with the full token to get its associated properties. Example: ```sh curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens/current \ -H 'Authorization: Bearer ${authToken}' ``` #### Allowed for * Admins, Agents, End Users

    GET /api/v2/oauth/tokens/{oauth_token_id}

  • Read

    Show Current Token

    Returns the properties of the current token. Include an `Authorization: Bearer` header with the full token to get its associated properties. For security reasons, only the first 10 characters of the access token are included. #### Allowed for * Admins, Agents, End Users

    GET /api/v2/oauth/tokens/current

  • Destructive

    Revoke Token

    #### Allowed for * Admins, Agents, End Users

    DELETE /api/v2/oauth/tokens/{oauth_token_id}

  • Destructive

    Revoke Current Token

    Revokes the current OAuth token. Include an `Authorization: Bearer` header with the full token. #### Allowed for * Admins, Agents, End Users

    DELETE /api/v2/oauth/tokens/current

  • Destructive

    Revoke Many Tokens

    Revokes multiple OAuth tokens in a single request. Pass the IDs of the tokens to revoke in the `token_ids` array. #### Allowed For * Admins * Agents with the `manage_api_credentials` permission

    POST /api/v2/oauth/tokens/delete_many

Organization Fields

  • Read

    List Organization Fields

    Returns a list of custom organization fields in your account. Fields are returned in the order that you specify in your organization fields configuration in Zendesk Support. Clients should cache this resource for the duration of their API usage and map the key for each organization field to the values returned under the `organization_fields` attribute on the [organization](/api-reference/ticketing/organizations/organizations/) resource. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents

    GET /api/v2/organization_fields

  • Read

    Show Organization Field

    #### Allowed for * Agents

    GET /api/v2/organization_fields/{organization_field_id}

  • Write

    Create Organization Field

    Creates any of the following custom field types: * text (default when no "type" is specified) * textarea * checkbox * date * integer * decimal * regexp * dropdown * lookup * multiselect See [About custom field types](https://support.zendesk.com/hc/en-us/articles/4408838961562) in Zendesk help. #### Allowed For * Admins

    POST /api/v2/organization_fields

  • Destructive

    Update Organization Field

    #### Updating a Dropdown (Tagger) or Multiselect Field Dropdown and multiselect fields return an array of `custom_field_options` which specify the name, value, and order of dropdown or multiselect options. When updating a dropdown or multiselect field, note the following information: - All options must be passed on update. Options that are not passed will be removed. As a result, these values will be removed from any organizations - To create a new option, pass a null `id` along with the `name` and `value` - To update an existing option, pass its `id` along with the `name` and `value` - To reorder an option, reposition it in the `custom_field_options` array relative to the other options - To remove an option, omit it from the list of options upon update #### Example Request ```bash curl https://{subdomain}.zendesk.com/api/v2/organization_fields/{organization_field_id} \ -H "Content-Type: application/json" -X PUT \ -d '{"organization_field": {"custom_field_options": [{"id": 124, "name": "Option 2", "value": "option_2"}, {"id": 123, "name": "Option 1", "value": "option_1"}, {"id": 125, "name": "Option 3", "value": "option_3"}]}}' \ -v -H "Authorization: Bearer {access_token}" ``` #### Allowed for * Admins

    PUT /api/v2/organization_fields/{organization_field_id}

  • Destructive

    Delete Organization Field

    #### Allowed for * Admins

    DELETE /api/v2/organization_fields/{organization_field_id}

  • Destructive

    Reorder Organization Field

    #### Allowed For * Admins

    PUT /api/v2/organization_fields/reorder

Organization Memberships

  • Read

    List Memberships

    Returns a list of organization memberships for the account, user or organization in question. **Note**: When returning organization memberships for a user, organization memberships are sorted with the default organization first, and then by organization name. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For - Agents - End users

    GET /api/v2/organization_memberships

  • Read

    Show Membership

    #### Allowed for * Agents

    GET /api/v2/organization_memberships/{organization_membership_id}

  • Read

    List Organization Memberships by Organization

    Returns a list of organization memberships for the account, user or organization in question. **Note**: When returning organization memberships for a user, organization memberships are sorted with the default organization first, and then by organization name. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For - Agents - End users

    GET /api/v2/organizations/{organization_id}/organization_memberships

  • Read

    List Organization Memberships by User

    Returns a list of organization memberships for the account, user or organization in question. **Note**: When returning organization memberships for a user, organization memberships are sorted with the default organization first, and then by organization name. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For - Agents - End users

    GET /api/v2/users/{user_id}/organization_memberships

  • Read

    Show Organization Membership by User

    #### Allowed for * Agents

    GET /api/v2/users/{user_id}/organization_memberships/{organization_membership_id}

  • Write

    Create Membership

    Assigns a user to a given organization. Returns an error with status 422 if the user is already assigned to the organization. #### Allowed For * Admins * Agents when creating a new organization membership for an end user

    POST /api/v2/organization_memberships

  • Write

    Create Many Memberships

    Accepts an array of up to 100 organization membership objects. 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. #### Allowed For * Admins * Agents

    POST /api/v2/organization_memberships/create_many

  • Write

    Create Organization Membership for User

    Assigns a user to a given organization. Returns an error with status 422 if the user is already assigned to the organization. #### Allowed For * Admins * Agents when creating a new organization membership for an end user

    POST /api/v2/users/{user_id}/organization_memberships

  • Destructive

    Delete Membership

    Immediately removes a user from an organization and schedules a job to unassign all working tickets currently assigned to the user and organization combination. The `organization_id` of the unassigned tickets is set to null. #### Allowed for * Admins * Agents when deleting an organization membership for an end user

    DELETE /api/v2/organization_memberships/{organization_membership_id}

  • Destructive

    Bulk Delete Memberships

    Immediately removes a user from an organization and schedules a job to unassign all working tickets currently assigned to the user and organization combination. The `organization_id` of the unassigned tickets is set to null. #### 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. #### Allowed For * Agents

    DELETE /api/v2/organization_memberships/destroy_many

  • Destructive

    Delete Organization Membership for User

    Immediately removes a user from an organization and schedules a job to unassign all working tickets currently assigned to the user and organization combination. The `organization_id` of the unassigned tickets is set to null. #### Allowed for * Admins * Agents when deleting an organization membership for an end user

    DELETE /api/v2/users/{user_id}/organization_memberships/{organization_membership_id}

  • Destructive

    Set Membership as Default

    Sets the default organization membership of a given user. #### Allowed for * Admins * Agents when setting the default organization membership for an end user

    PUT /api/v2/users/{user_id}/organization_memberships/{organization_membership_id}/make_default

  • Destructive

    Unassign Organization

    Immediately removes a user from an organization and schedules a job to unassign all working tickets currently assigned to the user and organization combination. The `organization_id` of the unassigned tickets is set to null. #### Allowed For * Agents

    DELETE /api/v2/users/{user_id}/organizations/{organization_id}

  • Destructive

    Set Organization as Default

    Sets the default organization membership of a given user. #### Allowed For * Agents

    PUT /api/v2/users/{user_id}/organizations/{organization_id}/make_default

Organizations

  • Read

    Show Organization Merge

    Retrieves the details of a specific organization merge operation. This endpoint is useful for obtaining the status and outcome of a merge that was previously initiated. It provides information such as the winning and losing organization IDs, the status of the merge, and the associated URLs. This endpoint can be used to determine if a merge is still in progress, has completed successfully, or has encountered an error. #### Allowed For * Admins

    GET /api/v2/organization_merges/{organization_merge_id}

  • Read

    List Organizations

    #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents, with certain restrictions If the agent has a custom agent role that restricts their access to only users in their own organization, a 403 Forbidden error is returned. See [Creating custom agent roles](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) in Zendesk help.

    GET /api/v2/organizations

  • Read

    Show Organization

    #### Allowed For * Admins * Agents

    GET /api/v2/organizations/{organization_id}

  • Read

    List Organization Merges

    Retrieves a list of all organization merge operations associated with a given organization. This endpoint allows you to track the history of merge actions for an organization, including ongoing and completed merges. Each entry in the list contains details such as the ID of the merge, the winning and losing organization IDs, the current status of the merge, and a URL to access the `Organization Merge` record. #### Pagination - Cursor pagination is used for this endpoint. - A maximum of 100 records can be returned per page. See [Pagination](/api-reference/introduction/pagination/) for more details. #### Allowed For * Admins

    GET /api/v2/organizations/{organization_id}/merges

  • Read

    Show Organization's Related Information

    #### Allowed For * Agents

    GET /api/v2/organizations/{organization_id}/related

  • Read

    Autocomplete Organizations

    Returns an array of organizations whose name starts with the value specified in the `name` parameter. #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/introduction/pagination/#using-offset-pagination). #### Allowed For * Agents

    GET /api/v2/organizations/autocomplete

  • Read

    Count Organizations

    Returns an approximate count of organizations. 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. 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 and the `value` property of the `count` object is limited to 100,000 until the update is complete. #### Allowed For * Agents

    GET /api/v2/organizations/count

  • Read

    Search Organizations

    Returns an array of organizations matching the criteria. You may search by an organization's `external_id` or `name`, but not both: #### Searching by `external_id` If you set the `external_id` value of an organization to associate it to an external record, you can use it to search for the organization. For an organization to be returned, its `external_id` must exactly match the value provided (case insensitive). #### Searching by `name` For an organization to be returned, its `name` must exactly match the value provided (case insensitive). #### Allowed For: * Admins * Agents assigned to a custom role with permissions to add or modify organizations (Enterprise only) See [Creating custom agent roles](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) in Zendesk help.

    GET /api/v2/organizations/search

  • Read

    Show Many Organizations

    Accepts a comma-separated list of up to 100 organization ids or external ids. #### Allowed For * Admins * Agents

    GET /api/v2/organizations/show_many

  • Read

    List User Organizations

    Returns a list of organizations associated with the specified user. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents, with certain restrictions If the agent has a custom agent role that restricts their access to only users in their own organization, a 403 Forbidden error is returned. See [Creating custom agent roles](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) in Zendesk help.

    GET /api/v2/users/{user_id}/organizations

  • Read

    Count User's Organizations

    Returns an approximate count of organizations for a specific user. 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. 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 and the `value` property of the `count` object is limited to 100,000 until the update is complete. #### Allowed For * Agents

    GET /api/v2/users/{user_id}/organizations/count

  • Write

    Create Organization

    You must provide a unique `name` for each organization. Normally the system doesn't allow records to be created with identical names. However, a race condition can occur if you make two or more identical POSTs very close to each other, causing the records to have identical organization names. **Note**: Leading and trailing whitespace in `name` is automatically trimmed before validation. This means that names differing only by whitespace are treated as duplicates. For example, "API Company" and "API Company " are considered the same name. #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

    POST /api/v2/organizations

  • Write

    Create Many Organizations

    Accepts an array of up to 100 organization objects. #### 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. #### Allowed For * Agents, with restrictions applying on certain actions

    POST /api/v2/organizations/create_many

  • Write

    Create Or Update Organization

    Creates an organization if it doesn't already exist, or updates an existing organization. Using this method means one less call to check if an organization exists before creating it. You need to specify the id or external id when updating an organization to avoid a duplicate error response. Name is not available as a matching criteria. #### Allowed For * Agents, with restrictions on certain actions

    POST /api/v2/organizations/create_or_update

  • Destructive

    Update Organization

    #### Allowed For * Admins * Agents Agents with no permissions restrictions can only update "notes" on organizations. **Note:** Updating an organization's `domain_names` property overwrites all existing `domain_names` values. To prevent this, submit a complete list of `domain_names` for the organization in your request. #### Example Request ```js { "organization": { "notes": "Something interesting" } } ```

    PUT /api/v2/organizations/{organization_id}

  • Destructive

    Delete Organization

    #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

    DELETE /api/v2/organizations/{organization_id}

  • Destructive

    Merge Organization With Another Organization

    Merges two organizations by moving all users, tickets, and domain names from the organization specified by `{organization_id}` to the organization specified by `winner_id`. After the merge: - The "losing" organization will be deleted. - Other organization fields and their values will not be carried over to the "winning" organization. - The merge operation creates an `Organization Merge` record which contains a status indicating the progress of the merge. **Note**: This operation is irreversible. #### Merge Statuses | Status | Description | |--------|-------------| | new | A job has been queued to merge the two organizations. | | in progress | The job to merge the two organizations has started. | | error | An error occurred during the merge job. The merge can be retried by repeating the API call. | | complete | The merge has been completed successfully. | #### Allowed For * Admins

    POST /api/v2/organizations/{organization_id}/merge

  • Destructive

    Bulk Delete Organizations

    Accepts a comma-separated list of up to 100 organization ids or external ids. #### 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. #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

    DELETE /api/v2/organizations/destroy_many

  • Destructive

    Update Many Organizations

    Bulk or batch updates up to 100 organizations. #### Bulk update To make the same change to multiple organizations, use the following endpoint and data format: `https://{subdomain}.zendesk.com/api/v2/organizations/update_many?ids=1,2,3` ```js { "organization": { "notes": "Priority" } } ``` #### Batch update To make different changes to multiple organizations, use the following endpoint and data format: `https://{subdomain}.zendesk.com/api/v2/organizations/update_many` ```js { "organizations": [ { "id": 1, "notes": "Priority" }, { "id": 2, "notes": "Normal" } ] } ``` #### 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. #### Allowed For * Admins * Agents Agents with no permissions restrictions can only update "notes" on organizations.

    PUT /api/v2/organizations/update_many

Organization Subscriptions

  • Read

    List Organization Subscriptions

    #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Agents * End users For end users, the response will only list the subscriptions created by the requesting end user.

    GET /api/v2/organization_subscriptions

  • Read

    Show Organization Subscription

    #### Allowed For: * Agents * End users For end users, the response will only list the subscriptions created by the requesting end user.

    GET /api/v2/organization_subscriptions/{organization_subscription_id}

  • Read

    List Subscriptions By Organization

    Returns a list of organization subscriptions for a specific organization. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Agents * End users For end users, the response will only list the subscriptions created by the requesting end user.

    GET /api/v2/organizations/{organization_id}/subscriptions

  • Read

    List User's Organization Subscriptions

    Returns a list of organization subscriptions for a specific user. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Agents * End users For end users, the response will only list the subscriptions created by the requesting end user.

    GET /api/v2/users/{user_id}/organization_subscriptions

  • Write

    Create Organization Subscription

    #### Allowed For: * Agents * End users End users can only subscribe to shared organizations in which they're members.

    POST /api/v2/organization_subscriptions

  • Destructive

    Delete Organization Subscription

    #### Allowed For: * Agents * End users

    DELETE /api/v2/organization_subscriptions/{organization_subscription_id}

Requests

  • Read

    List Organization Requests

    Returns a list of requests for a specific organization. #### Allowed for * End Users #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/organizations/{organization_id}/requests

  • Read

    List Requests

    #### Allowed for * End Users #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). #### High volume requests Requesting a large number of tickets may return intermittent "503 Service Unavailable" errors. Workarounds: - Use cursor pagination with a smaller page size. Example: GET /api/v2/requests?page[size]=100. If you continue to see timeouts, try a smaller value, such as 50 or 25. - Use [Search Requests](/api-reference/ticketing/tickets/ticket-requests/#search-requests) instead.

    GET /api/v2/requests

  • Read

    Show Request

    #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | users | The email ccs for a request by side-loading users #### Allowed For * End Users

    GET /api/v2/requests/{request_id}

  • Read

    Listing Comments

    #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). #### Sorting By default, comments are sorted by creation date in ascending order. When using cursor pagination, use the following parameter to change the sort order: | Name | Type | Required | Comments | ------ | ------ | -------- | -------- | `sort` | string | no | Possible values are "created_at" (ascending order) or "-created_at" (descending order) When using offset pagination, use the following parameters to change the sort order: | Name | Type | Required | Comments | ------------ | ------ | -------- | -------- | `sort_by` | string | no | One of `created_at`, `updated_at` | `sort_order` | string | no | One of `asc`, `desc` #### Allowed For * End Users

    GET /api/v2/requests/{request_id}/comments

  • Read

    Getting Comments

    #### Allowed For * End Users

    GET /api/v2/requests/{request_id}/comments/{ticket_comment_id}

  • Read

    List CCD Requests

    Lists requests where the authenticated end user is CC'd. #### Allowed for * End Users #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/requests/ccd

  • Read

    List Open Requests

    Lists requests with the "open" status for the authenticated end user. #### Allowed for * End Users #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/requests/open

  • Read

    Search Requests

    Examples: * `GET /api/v2/requests/search?query=printer` * `GET /api/v2/requests/search?query=printer&organization_id=1` * `GET /api/v2/requests/search?query=printer&cc_id=true` * `GET /api/v2/requests/search?query=printer&status=hold,open` #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/introduction/pagination/#using-offset-pagination). #### Results limit The Search Requests endpoint returns up to 1,000 results per query, with a maximum of 100 results per page. See [Pagination](/api-reference/ticketing/introduction/#pagination). If you request a page past the limit (`page=11` at 100 results per page), a 422 Insufficient Resource Error is returned. #### Allowed For * End Users

    GET /api/v2/requests/search

  • Read

    List Solved Requests

    Lists requests with the "solved" status for the authenticated end user. #### Allowed for * End Users #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/requests/solved

  • Read

    List User Requests

    Lists requests for the specified user. #### Allowed for * End Users

    GET /api/v2/users/{user_id}/requests

  • Write

    Create Request

    Accepts a `request` object that sets one or more properties. #### Allowed for * End users * Anonymous users (rate limit of 5 requests per hour for [trial accounts](/documentation/developer-tools/getting-started/getting-a-trial-or-sponsored-account-for-development/)) #### Additional properties In addition to the writable request properties in the [JSON Format table](#json-format) above, you can set the following properties when creating a request. | Name | Type | Mandatory | Comment | ---------------- | -------| --------- | ------- | comment | object | yes | Describes the problem, incident, question, or task. See [Request comments](#request-comments) | collaborators | array | no | Adds collaborators (cc's) to the request. An email notification is sent to them when the ticket is created. See [Setting collaborators](/documentation/ticketing/managing-tickets/creating-and-managing-requests#setting-collaborators) | requester | object | yes* | \*Required for anonymous requests. Specifies the requester of the anonymous request. See [Creating anonymous requests](/documentation/ticketing/managing-tickets/creating-and-managing-requests#creating-anonymous-requests) #### Creating follow-up requests Once a ticket is closed (as distinct from solved), it can't be reopened. However, you can create a new request that references the closed ticket. To create the follow-up request, include a `via_followup_source_id` property in the `request` object that specifies the closed ticket. The parameter only works with closed tickets. It has no effect with other tickets.

    POST /api/v2/requests

  • Destructive

    Update Request

    Updates a request with a comment or collaborators (cc's). The end user who created the request can also use it to mark the request as solved. The endpoint can't be used to update other request attributes. #### Writable properties This endpoint can only update the following properties in the request. | Name | Type | Required | Description | | ------------------------ | ------- | -------- | ---------------------------------------------------- | | comment | object | no | Adds a comment to the request. See [Request comments](#request-comments) | | solved | boolean | no | Marks the request as solved. Example: `{"request": {"solved": "true"}}`. End users can mark requests as solved only if the request's `can_be_solved_by_me` property is true. The property is true only when the ticket is assigned to an agent and the ticket type is not a problem but a question, task, or incident | | additional_collaborators | array | no | Adds collaborators to the request. An email notification is sent to them when the ticket is updated. See [Adding collaborators](/documentation/ticketing/managing-tickets/creating-and-managing-requests#adding-collaborators) | #### Allowed For * End users

    PUT /api/v2/requests/{request_id}

Push Notification Devices

  • Write

    Bulk Unregister Push Notification Devices

    Unregisters the mobile devices that are receiving push notifications. Specify the devices as an array of mobile device tokens. #### Allowed for * Admins

    POST /api/v2/push_notification_devices/destroy_many

Omnichannel Routing Queues

  • Read

    List queues

    Returns all active queues for an account. #### Allowed For * Admins

    GET /api/v2/queues

  • Read

    Show Queue

    Returns a queue for the given queue id. #### Allowed For * Agents

    GET /api/v2/queues/{queue_id}

  • Read

    List Queue Definitions

    Returns the definitions of the queues and the definitions of the conditions under which a queue can execute. The definition of the action includes a title ("Status"), a type ("list"), and possible values. The definition of the condition includes the same fields as well as the possible operators. #### Allowed For * Admins

    GET /api/v2/queues/definitions

  • Write

    Create Queue

    Creates a queue. Accepts a JSON queue definition as the request body. #### Allowed For * Admins

    POST /api/v2/queues

  • Write

    Reorder Queues

    Alters the evaluation order of OCR queues in the account. The evaluation order is set in a `queue_ids` array in the request body. You must include every queue id in your account to reorder the OCR queues. If not, the endpoint will return 400 Bad Request. #### Allowed For * Admins

    PATCH /api/v2/queues/order

  • Destructive

    Update Queue

    Updates the queue definition for a given queue id. #### Allowed For * Admins

    PUT /api/v2/queues/{queue_id}

  • Destructive

    Delete Queue

    Deletes the queue and related records. #### Allowed For * Admins

    DELETE /api/v2/queues/{queue_id}

Support Addresses

  • Read

    List Support Addresses

    Lists all the support addresses for the account. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents

    GET /api/v2/recipient_addresses

  • Read

    Show Support Address

    #### Allowed For * Admins * Agents

    GET /api/v2/recipient_addresses/{support_address_id}

  • Write

    Create Support Address

    Adds a Zendesk or external support address to your account. To add a Zendesk address, use the following syntax: `{local-part}@{accountname}.zendesk.com`. Example: 'sales-team@example.zendesk.com'. The [local-part](https://en.wikipedia.org/wiki/Email_address#Local-part) can be anything you like. To add an external email address such as help@omniwearshop.com, the email must already exist and you must set up forwarding on your email server. The exact steps depend on your mail server. See [Forwarding incoming email to Zendesk Support](https://support.zendesk.com/hc/en-us/articles/4408836514202). After setting up forwarding, run the [Verify Support Address Forwarding](#verify-support-address-forwarding) endpoint. The address won't work in Zendesk Support until it's been verified. #### Allowed For * Admins * Agents with permission to manage channels and extensions. See the system permissions in [Creating custom agent roles](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) in Zendesk help

    POST /api/v2/recipient_addresses

  • Destructive

    Update Support Address

    Updates an existing support address for your account. You can't use this endpoint to update a support address's `email` property. Instead, you can create a new address using the [Create Support Address](#create-support-address) endpoint. #### Allowed For * Admins * Agents with permission to manage channels and extensions. See the system permissions in [Creating custom agent roles](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) in Zendesk help

    PUT /api/v2/recipient_addresses/{support_address_id}

  • Destructive

    Delete Support Address

    Deletes a support address. #### Allowed For * Admins * Agents with permission to manage channels and extensions. See the system permissions in [Creating custom agent roles](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) in Zendesk help

    DELETE /api/v2/recipient_addresses/{support_address_id}

  • Destructive

    Verify Support Address Forwarding

    Sends a test email to the specified support address to verify that email forwarding for the address works. An external support address won't work in Zendesk Support until it's verified. **Note**: You don't need to verify Zendesk system support addresses. The endpoint takes the following body: `{"type": "forwarding"}`. The value of the `type` property defaults to "forwarding" if none is specified, but the values "spf" and "dns" are also accepted. Use this endpoint after [adding](#create-support-address) an external support address to Zendesk Support and setting up forwarding on your email server. See [Forwarding incoming email to Zendesk Support](https://support.zendesk.com/hc/en-us/articles/4408836514202). The endpoint doesn't return the results of the test. Instead, use the [Show Support Address](#show-support-address) endpoint to check that the `forwarding_status` property is "verified". Other verification checks can also be performed using this API. These include SPF checks and DNS checks. When calling the endpoint with `type` set to "spf", it will queries the DNS records to check that the SPF records for Zendesk are present for outbound emails. When calling the endpoint with `type` set to "dns", it runs checks on your CNAME records to make sure they are set up properly in your DNS. #### Allowed For * Admins * Agents with permission to manage channels and extensions. See the system permissions in [Creating custom agent roles](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) in Zendesk help

    PUT /api/v2/recipient_addresses/{support_address_id}/verify

Remote Authentications

  • Read

    List Remote Authentications

    #### Allowed For * Admins

    GET /api/v2/remote_authentications

Resource Collections

  • Read

    List Resource Collections

    Lists resource collections for the account. #### Allowed for * Admins

    GET /api/v2/resource_collections

  • Read

    Show Resource Collection

    Retrieves details for a specified resource collection. #### Allowed for * Admins

    GET /api/v2/resource_collections/{resource_collection_id}

  • Write

    Create Resource Collection

    Creates a resource collection from a provided `payload` object. The `payload` object is specified the same way as the content of a requirements.json file in a Zendesk app. See [Specifying Apps Requirements](/documentation/apps/app-developer-guide/apps_requirements/) in the Zendesk Apps framework docs. The response includes a [job status](/api-reference/ticketing/ticket-management/job_statuses/) for creation of the specified resources. #### Allowed for * Admins

    POST /api/v2/resource_collections

  • Destructive

    Update Resource Collection

    Updates a resource collection using a provided `payload` object. The `payload` object is specified the same way as the content of a requirements.json file in a Zendesk app. See [Specifying Apps Requirements](/documentation/apps/app-developer-guide/apps_requirements/) in the Zendesk Apps framework docs. The response includes a [job status](/api-reference/ticketing/ticket-management/job_statuses/) for the resource updates. #### Allowed for * Admins

    PUT /api/v2/resource_collections/{resource_collection_id}

  • Destructive

    Delete Resource Collection

    Deletes a specified resource collection. The response includes a [job status](/api-reference/ticketing/ticket-management/job_statuses/) for deletion of the collection's resources. #### Allowed for * Admins

    DELETE /api/v2/resource_collections/{resource_collection_id}

Skill Based Routing

  • Read

    List Agent Attribute Values

    Returns an attribute value. #### Allowed For * Agents * Light agents and contributors

    GET /api/v2/routing/agents/{user_id}/instance_values

  • Read

    List Attribute Values for Many Agents

    Accepts a comma-separated list of up to 100 agent ids and returns attribute values for each agent in the list. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882) #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. Note: `page[before]` and `page[after]` can't be used together in the same request.

    GET /api/v2/routing/agents/instance_values

  • Read

    List Account Attributes

    Returns a list of attributes for the account. #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | attribute_values | The attribute values available on the account #### Allowed For * Agents * Light agents and contributors

    GET /api/v2/routing/attributes

  • Read

    Show Attribute

    Returns an attribute. #### Allowed For * Agents * Light agents and contributors

    GET /api/v2/routing/attributes/{attribute_id}

  • Read

    List Attribute Values for an Attribute

    Returns a list of attribute values for a provided attribute. #### Allowed For * Agents * Light agents and contributors

    GET /api/v2/routing/attributes/{attribute_id}/values

  • Read

    Show Attribute Value

    Returns an attribute value. #### Allowed For * Agents * Light agents and contributors

    GET /api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}

  • Read

    List Routing Attribute Definitions

    Returns the condition definitions that can be configured to apply attributes to a ticket. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882)

    GET /api/v2/routing/attributes/definitions

  • Read

    List Tickets Fulfilled by a User

    Returns a list of ticket ids that contain attributes matching the current user's attributes. Accepts a `ticket_ids` parameter for relevant tickets to check for matching attributes. #### Allowed For * Agents * Light agents and contributors

    GET /api/v2/routing/requirements/fulfilled

  • Read

    List Ticket Attribute Values

    Returns a list of attributes values for the ticket. #### Allowed For * Agents * Light agents and contributors

    GET /api/v2/routing/tickets/{ticket_id}/instance_values

  • Write

    Create Attribute

    Creates an attribute. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882)

    POST /api/v2/routing/attributes

  • Write

    Create Attribute Value

    Creates an attribute value. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882)

    POST /api/v2/routing/attributes/{attribute_id}/values

  • Write

    Update Attribute Value

    Updates the name and ticket conditions of a skill. When a ticket is created, the skill is applied to a ticket if the ticket meets the specified condition or conditions. See the [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference/) for more information. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882)

    PATCH /api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}

  • Destructive

    Set Agent Attribute Values

    Adds the specified attributes if no attributes exists, or replaces all existing attributes with the specified attributes. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882)

    POST /api/v2/routing/agents/{user_id}/instance_values

  • Destructive

    Bulk Set Agent Attribute Values Jobs

    Adds, replaces or removes multiple attributes for up to 100 agents. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882) #### Available Parameters The request takes a data object with the following properties: | Name | Type | Required | Description | | ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action | string | true | The action to perform on the attribute values. One of the following: "upsert", "update", "delete" | | attributes | object | true | The attribute values to update. See [Attribute Values](#attribute-values). `agent_skill_priority` is optional. If not provided, it keeps the current priority or defaults to `NORMAL` when adding new attribute values. | | items | array | true | The list of agent ids | Action can be one of the following: * upsert: Adds new attribute values to the agents * update: Replaces all the current attribute values of the agents with the new values * delete: Removes specified attribute values from the agents 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.

    POST /api/v2/routing/agents/instance_values/jobs

  • Destructive

    Update Attribute

    Updates an attribute. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882)

    PUT /api/v2/routing/attributes/{attribute_id}

  • Destructive

    Delete Attribute

    Deletes an attribute. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882)

    DELETE /api/v2/routing/attributes/{attribute_id}

  • Destructive

    Update Attribute Value

    Updates the name and ticket conditions of a skill. When a ticket is created, the skill is applied to a ticket if the ticket meets the specified condition or conditions. See the [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference/) for more information. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882)

    PUT /api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}

  • Destructive

    Delete Attribute Value

    Deletes an attribute value. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882)

    DELETE /api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}

  • Destructive

    Set Ticket Attribute Values

    Adds the specified attributes if no attributes exists, or replaces all existing attributes with the specified attributes. Invalid or deleted attributes are ignored. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882) * Agents, when the account setting for editing ticket skills is enabled for all agents

    POST /api/v2/routing/tickets/{ticket_id}/instance_values

Satisfaction Ratings

  • Read

    List Satisfaction Ratings

    #### Allowed For * Admins #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). #### Filters | Parameter | Value | ---------- | ----- | score | offered, unoffered, received, received\_with\_comment, received\_without\_comment,<br/>good, good\_with\_comment, good\_without\_comment,<br/>bad, bad\_with\_comment, bad\_without\_comment | start_time | Time of the oldest satisfaction rating, as a [Unix epoch time](https://www.epochconverter.com/) | end_time | Time of the most recent satisfaction rating, as a [Unix epoch time](https://www.epochconverter.com/) If you specify an unqualified score such as `good`, the results include all the records with and without comments. Examples: * `/api/v2/satisfaction_ratings?score=bad` * `/api/v2/satisfaction_ratings?score=bad&start_time=1498151194` * `/api/v2/satisfaction_ratings?start_time=1340384793&end_time=1371920793`

    GET /api/v2/satisfaction_ratings

  • Read

    Show Satisfaction Rating

    Returns a specific satisfaction rating. You can get the id from the [List Satisfaction Ratings](#list-satisfaction-ratings) endpoint. #### Allowed For * Admins

    GET /api/v2/satisfaction_ratings/{satisfaction_rating_id}

  • Read

    Count Satisfaction Ratings

    Returns an approximate count of satisfaction ratings in the account. 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 * Admins

    GET /api/v2/satisfaction_ratings/count

  • Write

    Create a Satisfaction Rating

    Creates a CSAT rating for a solved ticket, or for a ticket that was previously solved and then reopened. Only the end user listed as the ticket requester can create a satisfaction rating for the ticket. Only "good" and "bad" are valid values for the score when creating a rating. Other states, like "offered", are not valid and will result in a 422 error. #### Allowed For * End user who requested the ticket The end user must be a verified user.

    POST /api/v2/tickets/{ticket_id}/satisfaction_rating

Satisfaction Reasons

  • Read

    List Reasons for Satisfaction Rating

    List all reasons for an account #### Allowed For * Admins

    GET /api/v2/satisfaction_reasons

  • Read

    Show Reason for Satisfaction Rating

    #### Allowed For * Admins

    GET /api/v2/satisfaction_reasons/{satisfaction_reason_id}

Saved Searches

  • Read

    List Saved Searches

    Returns all saved searches for the requesting agent. #### Allowed For - Agents

    GET /api/v2/saved_searches

  • Write

    Create Saved Search

    Creates a saved search for the requesting agent. An agent can have at most 20 saved searches, and names must be unique per agent. #### Allowed For - Agents

    POST /api/v2/saved_searches

  • Destructive

    Update Saved Search

    Updates the name, type, and query of the saved search with the specified id for the requesting agent. Names must remain unique per agent. #### Allowed For - Agents (own saved searches only)

    PUT /api/v2/saved_searches/{id}

  • Destructive

    Delete Saved Search

    Deletes the saved search with the specified id for the requesting agent. #### Allowed For - Agents (own saved searches only)

    DELETE /api/v2/saved_searches/{id}

Search

  • Read

    List Search Results

    Returns the search results. See [Query syntax](#query-syntax) for details on the `query` parameter. Use the ampersand character (&) to append the `sort_by` or `sort_order` parameters to the URL. For examples, see [Searching with Zendesk API](/documentation/ticketing/using-the-zendesk-api/searching-with-the-zendesk-api). This endpoint has its own rate limit. The rate limit counts towards the global API rate limit. See [Limits](#limits). #### Allowed For * Agents #### Pagination * Offset pagination only Offset pagination may result in duplicate results when paging. You can also use the [Export Search Results](/api-reference/ticketing/ticket-management/search/#export-search-results) endpoint, which uses cursor-based pagination and doesn't return duplicate results. See [Using cursor pagination](/api-reference/introduction/pagination/#using-cursor-pagination) for more information. #### Errors JSON Format Errors are represented as JSON objects which have the following keys: | Name | Type | Comment | --------------------- | ---------------------| -------------------- | error | string | The type of error. Examples: "unavailable", "invalid" | description | string | ##### Example Error ```js { "error": "unavailable", "description": "Sorry, we could not complete your search query. Please try again in a moment." } ```

    GET /api/v2/search

  • Read

    Show Results Count

    Returns the number of items matching the query rather than the items. The search string works the same as a regular search. #### Allowed For - Agents

    GET /api/v2/search/count

  • Read

    Export Search Results

    Exports a set of results. See [Query syntax](#query-syntax) for the syntax of the `query` parameter. Use this endpoint for search queries that will return more than 1000 results. The result set is ordered only by the `created_at` attribute. The search only returns results of a single object type. The following object types are supported: ticket, organization, user, or group. You must specify the type in the `filter[type]` parameter. Searches with type in the query string will result in an error. #### Allowed For - Agents #### Pagination - Cursor pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 1000 records per page. The number of results shown in a page is determined by the `page[size]` parameter. **Note**: You may experience a speed reduction or a timeout if you request 1000 results per page and you have many archived tickets in the results. Try reducing the number of results per page. We recommend 100 results per page. The cursor specified by the `after_cursor` property in a response expires after one hour. For more information on cursor-based pagination, see the following articles: - [Comparing cursor pagination and offset pagination](/documentation/developer-tools/pagination/comparing-cursor-pagination-and-offset-pagination) - [Paginating through lists using cursor pagination](/documentation/developer-tools/pagination/paginating-through-lists-using-cursor-pagination) #### Export Search Results Limits This API endpoint is rate-limited to 100 requests per minute per account. The limit also counts towards the global API rate limit. #### Response Format | Name | Type | Comment | --------------------- | ---------------------| -------------------- | links[next] | string | URL to the next page of results | meta[has_more] | string | Boolean indicating if there are more results | meta[after_cursor] | string | Cursor object returned from the Search Service | results | array | May consist of tickets, users, groups, or organizations, as specified by the `filter[type]` parameter The response is similar to the response of `GET /api/v2/search?`, with a few changes: * `links` - Has the following nested properties: `prev` and `next`. These replace the `next_page` and `prev_page` links. The `prev` property is always null because backward pagination is not supported. The `next` property may include an auto-generated link to the next page of results. * `meta` - Has the following nested properties: `has_more` and `after_cursor`. The `has_more` property indicates whether the next page has more results. The `after_cursor` property is the cursor used to paginate to the next page. It expires after one hour. There's no `count` property.

    GET /api/v2/search/export

Security Settings

  • Read

    Show Security Settings

    #### Allowed For * Admins

    GET /api/v2/security_settings

Sessions

  • Read

    List Sessions

    If authenticated as an admin, returns all the account's sessions. If authenticated as an agent or end user, returns only the sessions of the user making the request. #### Pagination - Cursor pagination only See [Pagination](/api-reference/introduction/pagination/). #### Allowed For * Admins, Agents, End users

    GET /api/v2/sessions

  • Read

    List Sessions for User

    Lists all sessions for a specific user. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). #### Allowed For * Admins, Agents, End users

    GET /api/v2/users/{user_id}/sessions

  • Read

    Show Session

    #### Allowed For * Admins, Agents, End users

    GET /api/v2/users/{user_id}/sessions/{session_id}

  • Read

    Show the Currently Authenticated Session

    #### Allowed For * Admins, Agents, End users

    GET /api/v2/users/me/session

  • Read

    Renew the current session

    #### Allowed For * Admins, Agents, End users

    GET /api/v2/users/me/session/renew

  • Destructive

    Bulk Delete Sessions

    Deletes all the sessions for a user. #### Allowed For * Admins, Agents, End users

    DELETE /api/v2/users/{user_id}/sessions

  • Destructive

    Delete Session

    #### Allowed For * Admins, Agents, End users

    DELETE /api/v2/users/{user_id}/sessions/{session_id}

  • Destructive

    Delete the Authenticated Session

    Deletes the current session. In practice, this only works when using session auth for requests, such as client-side requests made from a Zendesk app. When using OAuth or basic authentication, you don't have a current session so this endpoint has no effect. #### Allowed For * Admins, Agents, End users

    DELETE /api/v2/users/me/logout

Sharing Agreements

  • Read

    List Sharing Agreements

    #### Allowed For * Agents

    GET /api/v2/sharing_agreements

  • Read

    Show a Sharing Agreement

    Returns a sharing agreement for your account. #### Allowed For * Agents

    GET /api/v2/sharing_agreements/{sharing_agreement_id}

  • Write

    Create Sharing Agreement

    #### Allowed For * Admins

    POST /api/v2/sharing_agreements

  • Destructive

    Update a Sharing Agreement

    Returns an updated sharing agreement. Only `status` is allowed to be updated. #### Allowed For * Admins

    PUT /api/v2/sharing_agreements/{sharing_agreement_id}

  • Destructive

    Delete a Sharing Agreement

    Deletes a sharing agreement. #### Allowed For * Admins

    DELETE /api/v2/sharing_agreements/{sharing_agreement_id}

Ticket Skips

  • Read

    List All Skips

    Lists all skips. Archived tickets are not included in the response. See [About archived tickets](https://support.zendesk.com/hc/en-us/articles/4408887617050) in the Support Help Center. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents with "View only" or higher reports permissions in Support. These permissions are distinct from Explore permissions. * Agents retrieving their own skips

    GET /api/v2/skips

  • Read

    List Ticket Skips By Ticket

    Returns the skips for a specific ticket. Archived tickets are not included in the response. See [About archived tickets](https://support.zendesk.com/hc/en-us/articles/4408887617050) in the Support Help Center. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents with "View only" or higher reports permissions in Support. These permissions are distinct from Explore permissions. * Agents retrieving their own skips

    GET /api/v2/tickets/{ticket_id}/skips

  • Read

    List Ticket Skips

    Archived tickets are not included in the response. See [About archived tickets](https://support.zendesk.com/hc/en-us/articles/4408887617050) in the Support Help Center. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents with "View only" or higher reports permissions in Support. These permissions are distinct from Explore permissions. * Agents retrieving their own skips

    GET /api/v2/users/{user_id}/skips

  • Write

    Record a New Skip for the Current User

    Record a new ticket skip for the current user. #### Allowed For * Agents

    POST /api/v2/skips

SLA Policies

  • Read

    List SLA Policies

    #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

    GET /api/v2/slas/policies

  • Read

    Show SLA Policy

    #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

    GET /api/v2/slas/policies/{sla_policy_id}

  • Read

    Retrieve Supported Filter Definition Items

    #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

    GET /api/v2/slas/policies/definitions

  • Read

    List Ticket SLA Policy Metrics

    Returns the SLA policy metrics for a specific ticket. #### Availability * Accounts on the Enterprise plan #### Allowed For * Admins

    GET /api/v2/tickets/{ticket_id}/slas/policy_metrics

  • Write

    Create SLA Policy

    #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

    POST /api/v2/slas/policies

  • Destructive

    Update SLA Policy

    Updates the specified policy. #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

    PUT /api/v2/slas/policies/{sla_policy_id}

  • Destructive

    Delete SLA Policy

    #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

    DELETE /api/v2/slas/policies/{sla_policy_id}

  • Destructive

    Reorder SLA Policies

    Reorders the SLA policies. The new order is set in a `sla_policy_ids` array in the JSON request body. #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

    PUT /api/v2/slas/policies/reorder

Suspended Tickets

  • Read

    List Suspended Tickets

    #### 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 suspended tickets on Enterprise plans * Unrestricted agents on all other plans #### Sorting You can sort the tickets with the `sort_by` and `sort_order` query string parameters. #### Pagination * Cursor pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/suspended_tickets

  • Read

    Show Suspended Ticket

    #### 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 suspended tickets on Enterprise plans * Unrestricted agents on all other plans

    GET /api/v2/suspended_tickets/{id}

  • Write

    Suspended Ticket Attachments

    Makes copies of any attachments on a suspended ticket and returns them as [attachment tokens](/api-reference/ticketing/tickets/ticket-attachments/). If the ticket is manually recovered, you can include the attachment tokens on the new ticket. #### 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 suspended tickets on Enterprise plans * Unrestricted agents on all other plans

    POST /api/v2/suspended_tickets/attachments

  • Write

    Export Suspended Tickets

    Exports a list of suspended tickets for the Zendesk Support instance. To export the list, the endpoint enqueues a job to create a CSV file with the data. When done, Zendesk sends the requester an email containing a link to the CSV file. In the CSV, tickets are sorted by the update timestamp in ascending order. #### 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 suspended tickets on Enterprise plans * Unrestricted agents on all other plans #### Rate limits Limited to one request per minute and up to one million records in return. The rate-limiting mechanism behaves identically to the one described in [Usage limits](/api-reference/ticketing/account-configuration/usage_limits/#monitoring-your-request-activity). We recommend using the `Retry-After` header value as described in [Catching errors caused by rate limiting](/documentation/ticketing/using-the-zendesk-api/best-practices-for-avoiding-rate-limiting#catch).

    POST /api/v2/suspended_tickets/export

  • Destructive

    Delete Suspended Ticket

    #### Allowed For * Unrestricted agents

    DELETE /api/v2/suspended_tickets/{id}

  • Destructive

    Recover Suspended Ticket

    **Note**: During recovery, the API sets the requester to the authenticated agent who called the API, not the original requester. This prevents the ticket from being re-suspended after recovery. To preserve the original requester, use the [Recover Multiple Suspended Tickets](#recover-multiple-suspended-tickets) endpoint with the single ticket. This endpoint does not queue an asynchronous job that can be tracked from [Job Statuses](/api-reference/ticketing/ticket-management/job_statuses/). Instead, it processes the request with a synchronous response. - If the recovery is successful, it returns a 200 with the restored ticket as a `ticket` object in the response. - If the recovery fails, it returns a 422 with no response body. #### 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 suspended tickets on Enterprise plans * Unrestricted agents on all other plans

    PUT /api/v2/suspended_tickets/{id}/recover

  • Destructive

    Bulk Recover Suspended Tickets

    Enqueues a bulk job to recover multiple suspended tickets. Returns a job status that can be tracked via the Job Statuses API. Unlike the [Recover Multiple Suspended Tickets](#recover-multiple-suspended-tickets) endpoint which processes tickets synchronously, this endpoint queues an asynchronous job for processing large batches. #### 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 suspended tickets on Enterprise plans * Unrestricted agents on all other plans

    PUT /api/v2/suspended_tickets/bulk_recover

  • Destructive

    Delete Multiple Suspended Tickets

    Accepts up to 100 ids (the auto-generated id, not the ticket id.) #### 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 suspended tickets on Enterprise plans * Unrestricted agents on all other plans

    DELETE /api/v2/suspended_tickets/destroy_many

  • Destructive

    Recover Multiple Suspended Tickets

    Accepts up to 100 ids (the auto-generated id, not the ticket id.) Note that suspended tickets that fail to be recovered are still included in the response. #### 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 suspended tickets on Enterprise plans * Unrestricted agents on all other plans

    PUT /api/v2/suspended_tickets/recover_many

Target Failures

  • Read

    List Target Failures

    Returns the 25 most recent target failures, per target. #### Stability * Development #### Allowed For * Admins

    GET /api/v2/target_failures

  • Read

    Show Target Failure

    #### Stability * Development #### Allowed For * Admins

    GET /api/v2/target_failures/{target_failure_id}

Targets

  • Read

    List Targets

    #### Allowed For * Agents

    GET /api/v2/targets

  • Read

    Show Target

    #### Allowed For * Agents

    GET /api/v2/targets/{target_id}

  • Write

    Create Target

    #### Allowed For * Admins

    POST /api/v2/targets

  • Destructive

    Update Target

    #### Allowed For * Admins

    PUT /api/v2/targets/{target_id}

  • Destructive

    Delete Target

    #### Allowed For * Admins

    DELETE /api/v2/targets/{target_id}

Task List Templates

  • Read

    List Task List Templates

    Lists all task list templates. The template's tasks aren't included in the response. #### Allowed For * Agents

    GET /api/v2/task_list_templates

  • Read

    Show Task List Template

    Returns the task list template with the specified id. The template's tasks aren't included in the response. #### Allowed For * Agents

    GET /api/v2/task_list_templates/{task_list_template_id}

  • Read

    Get Tasks by Task List Template Id

    Returns the tasks for the specified task list template. #### Allowed For * Agents

    GET /api/v2/task_list_templates/{task_list_template_id}/tasks

  • Write

    Create Task List Template

    Creates a task list template. #### Allowed For * Admins

    POST /api/v2/task_list_templates

  • Destructive

    Update Task List Template

    Creates, modifies, or deletes tasks in a task list template. Only the tasks included in the `task_list_template` object in the request are updated. Tasks that aren't specified in the request are unchanged. #### Allowed For * Admins

    PUT /api/v2/task_list_templates/{task_list_template_id}

  • Destructive

    Delete Task List Template

    Deletes a task list template with the specified id. #### Allowed For * Admins

    DELETE /api/v2/task_list_templates/{task_list_template_id}

Task Lists

  • Read

    Show Task List

    Returns the task list with the specified id. The response includes `is_completed`, which indicates whether all task items in the list have been completed. Works for both template-based and custom task lists. #### Allowed For * Agents

    GET /api/v2/task_lists/{task_list_id}

  • Read

    List Task Items

    Returns all task items for the specified task list. Works for both template-based and custom task lists. Each item includes an `is_custom` field indicating whether it was added directly to the task list or inherited from a template. #### Allowed For * Agents

    GET /api/v2/task_lists/{task_list_id}/task_items

  • Read

    Show Task Item

    Returns the task item with the specified id. Works for both template-based and custom task items. #### Allowed For * Agents

    GET /api/v2/task_lists/{task_list_id}/task_items/{task_item_id}

  • Read

    List Parent Ticket References

    Returns parent tickets and task items that link to the specified subticket. If the ticket has no parent task links, `parent_ticket_tasks` is empty. #### Allowed For * Agents

    GET /api/v2/tickets/{ticket_id}/parent_ticket_tasks

  • Read

    List Linked Tickets

    Returns tickets linked to the specified task item. #### Allowed For * Agents

    GET /api/v2/tickets/{ticket_id}/task_items/{task_item_id}/task_links

  • Read

    Show Task Lists for Ticket

    Returns the task lists attached to the specified ticket. A ticket can have zero, one, or many task lists, so `task_lists` is an array of 0 to N task lists. It's empty when the ticket has no task lists attached. #### Allowed For * Agents

    GET /api/v2/tickets/{ticket_id}/task_lists

  • Write

    Create Custom Task Item

    Adds a task item to the specified custom task list. The task list must be a custom task list (not created from a template). Creating a task item increments `task_count` on the parent task list. `name` is required. `description` is optional. #### Allowed For * Agents

    POST /api/v2/task_lists/{task_list_id}/task_items

  • Write

    Create Subticket

    Creates a ticket and links it to the specified task item as a subticket. The parent ticket must not already be a subticket. `subject` and `comment.body` are required. `comment.body` can contain up to 1,000 characters. #### Allowed For * Agents

    POST /api/v2/tickets/{ticket_id}/task_items/{task_item_id}/subticket

  • Write

    Link Existing Ticket

    Links an existing ticket to the specified task item. A task item can have one linked ticket. #### Allowed For * Agents

    POST /api/v2/tickets/{ticket_id}/task_items/{task_item_id}/task_links

  • Write

    Create Task List

    Adds a task list to the specified ticket. There are two ways to create a task list: **Create from a template:** Include `task_list_template_id` in the request body. The new task list will inherit the template's name, description, and task items. **Create a custom task list:** Include `name` (and optionally `description`) instead of `task_list_template_id`. Custom task lists have no template and allow you to add, update, and delete task items individually. A ticket can hold more than one task list, up to the account's task list limit. Requests beyond that limit return a 422 error. #### Allowed For * Agents

    POST /api/v2/tickets/{ticket_id}/task_lists

  • Destructive

    Update Custom Task List

    Updates the name or description of a custom task list. Only custom task lists (those without a template) can be updated. #### Allowed For * Agents

    PUT /api/v2/task_lists/{task_list_id}

  • Destructive

    Delete Task List

    Deletes the task list with the specified id. #### Allowed For * Agents

    DELETE /api/v2/task_lists/{task_list_id}

  • Destructive

    Update Task Item

    Updates a task item. Available fields depend on the item type: **Any task item:** Use `completed` to mark the item complete (`true`) or incomplete (`false`). This is reflected as `is_completed` in the response. Completing all task items in a task list automatically marks the task list as completed. **Custom task items only:** Also supports updating `name` and `description`. Template-based task items cannot be renamed. #### Allowed For * Agents

    PUT /api/v2/task_lists/{task_list_id}/task_items/{task_item_id}

  • Destructive

    Delete Custom Task Item

    Deletes the specified custom task item from its task list. Only custom task items (those not inherited from a template) can be deleted. Deleting a task item decrements `task_count` on the parent task list. #### Allowed For * Agents

    DELETE /api/v2/task_lists/{task_list_id}/task_items/{task_item_id}

  • Destructive

    Unlink Ticket

    Deletes the link between the specified task item and ticket. This does not delete the ticket or the task item. #### Allowed For * Agents

    DELETE /api/v2/tickets/{ticket_id}/task_items/{task_item_id}/task_links/{task_object_link_id}

Ticket Audits

  • Read

    List All Ticket Audits

    Returns ticket audits. Archived tickets are not included in the response. Use the [List Audits for a Ticket](#list-audits-for-a-ticket) endpoint to retrieve audit records for an archived ticket. To learn more about archived tickets, see [About archived tickets](https://support.zendesk.com/hc/en-us/articles/4408887617050). This endpoint should not be used for capturing change data. When continually chasing the tail of a cursor, some records will be skipped. For this use case, use the [Incremental Ticket Event Export API](/api-reference/ticketing/ticket-management/incremental_exports/#incremental-ticket-event-export). #### Allowed For * Admins

    GET /api/v2/ticket_audits

  • Read

    List Audits for a Ticket

    Lists the audits for a specified ticket. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. **Note**: Audits for [Archived Tickets](https://support.zendesk.com/hc/en-us/articles/4408887617050) do not support pagination for this endpoint. #### Allowed for * Agents

    GET /api/v2/tickets/{ticket_id}/audits

  • Read

    Show Audit

    #### Allowed for * Agents

    GET /api/v2/tickets/{ticket_id}/audits/{ticket_audit_id}

  • Read

    Count Audits for a Ticket

    Returns an approximate count of audits for a specified ticket. 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**: If the total number of audits for a ticket exceeds 100,000, this endpoint returns a count of 100,000 with a `count[refreshed_at]` value of null. This value is cached for 24 hours, during which any requests returns the same count and timestamp. After 24 hours, the endpoint temporarily shows the same count again before providing an updated total. #### Allowed for * Agents

    GET /api/v2/tickets/{ticket_id}/audits/count

  • Destructive

    Change a Comment From Public To Private

    #### Allowed for * Agents

    PUT /api/v2/tickets/{ticket_id}/audits/{ticket_audit_id}/make_private

Ticket Content Pins

  • Read

    List Ticket Content Pins

    Lists the content pins for a specific ticket. Content pins are used to pin related content such as articles to a ticket for quick access. This endpoint returns the content pins associated with the specified ticket id. #### Allowed For * Agents

    GET /api/v2/ticket_content_pins

  • Write

    Create Ticket Content Pin

    Creates a new content pin for a specific ticket. Content pins allow you to link to articles, community posts, or external content for easy reference. #### Allowed For * Admins * Agents

    POST /api/v2/ticket_content_pins

  • Destructive

    Delete Content Pin from Ticket

    Deletes a specific content pin from a ticket. #### Allowed For * Agents

    DELETE /api/v2/ticket_content_pins/{content_pin_id}

Ticket Fields

  • Read

    List Ticket Fields

    Returns a list of all system and custom ticket fields in your account. For end users, only the ticket fields with visible_in_portal set to true are returned. Cursor pagination returns a maximum of 100 records per page and fields are returned in the order specified by their id. If the results are not paginated, every field is returned in the response and fields are returned in the order specified by the position. You can adjust the position of ticket fields by: - Using the [Update Ticket Field](/api-reference/ticketing/tickets/ticket_fields/#update-ticket-field) endpoint - Using the [Reorder Ticket Fields](/api-reference/ticketing/tickets/ticket_fields/#reorder-ticket-fields) endpoint - Ticket Fields page in the Admin Center (**Admin Center** > **Manage** > **Ticket** > **Fields** > **Actions** > **Edit order**) These adjustments determine the order in which fields are displayed in various locations. For accounts without access to multiple ticket forms, the order will also be used to display field values within tickets. However, for accounts with access to multiple ticket forms, the field order on the ticket page is defined within each form. Consider caching this resource to use with the [Tickets](/api-reference/ticketing/tickets/tickets/#json-format) API. #### Pagination - Cursor pagination (recommended) - No pagination See [Pagination](/api-reference/introduction/pagination/). #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | users | The user or users that created the ticket field #### Allowed For * Anyone

    GET /api/v2/ticket_fields

  • Read

    Show Ticket Field

    #### Allowed for * Agents #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | users | The user or users that created the ticket field

    GET /api/v2/ticket_fields/{ticket_field_id}

  • Read

    List Ticket Field Options

    Returns a list of custom ticket field options for the given drop-down ticket field. #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/ticket_fields/{ticket_field_id}/options

  • Read

    Show Ticket Field Option

    #### Allowed for * Agents

    GET /api/v2/ticket_fields/{ticket_field_id}/options/{ticket_field_option_id}

  • Read

    Count Ticket Fields

    Returns an approximate count of system and custom ticket fields in the account. 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

    GET /api/v2/ticket_fields/count

  • Read

    Show Many Ticket Fields

    Returns multiple ticket fields in a single request. Provide either: - `ids` — a comma-separated list of ticket field IDs, or - `keys` — a comma-separated list of ticket field keys Up to 100 values are accepted. The response payload matches the List Ticket Fields [response format](/api-reference/ticketing/tickets/ticket_fields/#example-responses). #### Sideloads The following sideloads are supported: | Name | Will sideload | |-------|---------------------------------------| | users | The user or users that created fields | #### Allowed For * Anyone

    GET /api/v2/ticket_fields/show_many

  • Write

    Create Ticket Field

    Creates any of the following custom field types: | Custom field type | Description | |-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| | text | Default custom field type when `type` is not specified | | textarea | For multi-line text | | checkbox | To capture a boolean value. Allowed values are true or false. Optionally, you can specify a tag to be added to the ticket when the value is true. | | date | Example: 2021-04-16 | | integer | String composed of numbers. May contain an optional decimal point | | decimal | For numbers containing decimals | | regexp | Matches the Regex pattern found in the custom field settings | | partialcreditcard | A credit card number. Only the last 4 digits are retained | | multiselect | Enables users to choose multiple options from a dropdown menu. It contains one or more tag values belonging to the field's options. | | tagger | Single-select dropdown menu. It contains one or more tag values belonging to the field's options. Example: ( {"id": 21938362, "value": ["hd_3000", "hd_5555"]}) | | lookup | A field to create a relationship (see [lookup relationships](/api-reference/ticketing/lookup_relationships/lookup_relationships/)) to another object such as a user, ticket, or organization | | multi_lookup | A field to create a relationship to multiple records of the same object type. See [About multi-lookup relationship fields](/api-reference/ticketing/lookup_relationships/lookup_relationships/#about-multi-lookup-relationship-fields) | **Note**: Tags can't be re-used across custom ticket fields. For example, if you configure a tag for a checkbox field, you can't use that tag value for a dropdown (tagger) field option. The use of tags isn't validated and can prevent editing in the future. See [About custom field types](https://support.zendesk.com/hc/en-us/articles/4408838961562) in the Zendesk Help Center. #### Allowed For * Admins #### Field limits We recommend the following best practices for ticket fields limits. Creating more than these amounts can affect performance. * 400 ticket fields per account if your account doesn't have ticket forms * 400 ticket fields per ticket form if your account has ticket forms The following field types have their own limits, enforced on creation: * Two `multi_lookup` fields per account. See [Creating multi-lookup relationship fields](/api-reference/ticketing/lookup_relationships/lookup_relationships/#creating-multi-lookup-relationship-fields)

    POST /api/v2/ticket_fields

  • Write

    Create or Update Ticket Field Option

    Creates or updates an option for the given drop-down ticket field. To update an option, include the id of the option in the `custom_field_option` object. Example: `{"custom_field_option": {"id": 10002, "name": "Pineapples", ... }` If an option exists for the given ID, the option will be updated. Otherwise, a new option will be created. #### Response Returns one of the following status codes: - 200 with `Location: /api/v2/ticket_fields/{ticket_field_id}/options` if the ticket field option already exists in the database - 201 with `Location: /api/v2/ticket_fields/{ticket_field_id}/options` if the ticket field option is new #### Allowed For * Admins #### Rate Limit You can make 100 requests every 1 minute using this endpoint. 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. #### Field Option Limits * 2000 options per ticket field

    POST /api/v2/ticket_fields/{ticket_field_id}/options

  • Destructive

    Update Ticket Field

    #### Updating drop-down field options You can also use the update endpoint to add, update, or remove options in a drop-down custom field. Updating field options for multi-select fields works exactly the same as drop-down field options. **Important**: Unless you want to remove some options, you must specify all existing options in any update request. Omitting an option removes it from the drop-down field, which removes its values from any tickets or macros. Use the `custom_field_options` attribute to update the options. The attribute consists of an array of option objects, with each object consisting of a `name`, `value` and `allow_solving` property. The properties correspond to the "Title", "Tag" and "Required to solve" boxes in the admin interface. Example request body: ```json {"ticket_field": { "custom_field_options": [ {"name": "Apple Pie", "value": "apple", "allow_solving": true}, {"name": "Pecan Pie", "value": "pecan", "allow_solving": false} ] } } ``` #### Example Request ```bash curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{id} \ -d '{"ticket_field": {"custom_field_options": [{"name": "Apple Pie", "value": "apple", "allow_solving": true}, {"name": "Pecan Pie", "value": "pecan", "allow_solving": false}]}}' \ -H "Content-Type: application/json" -X PUT \ -v -H "Authorization: Bearer {access_token}" ``` #### Example Response ```http Status: 200 OK { "ticket_field": { "id":21938362, "type":"tagger", "title":"Pies", ... "custom_field_options": [ { "id":21029772, "name":"Apple Pie", "raw_name":"Apple Pie", "value":"apple", "default":false, "allow_solving":true }, ... ] } } ``` #### Allowed for * Admins

    PUT /api/v2/ticket_fields/{ticket_field_id}

  • Destructive

    Delete Ticket Field

    #### Allowed for * Admins

    DELETE /api/v2/ticket_fields/{ticket_field_id}

  • Destructive

    Delete Ticket Field Option

    #### Allowed for * Admins

    DELETE /api/v2/ticket_fields/{ticket_field_id}/options/{ticket_field_option_id}

  • Destructive

    Reorder Ticket Fields

    #### Allowed For * Admins #### Request Parameters You can pass in the following parameter in the payload: | Name | Type | Comment | ------------------- | ------ | -------- | ticket_field_ids | array | An array of ticket field ids. Example: "[2, 23, 46, 50]". Not all ticket_field_ids are necessary in the payload; only those provided will be assigned to the first positions. Missing IDs will be assigned incremental positions automatically.

    PUT /api/v2/ticket_fields/reorder

Ticket Form Statuses

  • Read

    List Ticket Form Statuses

    Fetches all of the ticket form statuses for the account. Supports filtering by ticket form ID and other criteria using query parameters. #### Allowed For * Admins * Agents

    GET /api/v2/ticket_form_statuses

  • Read

    Show Many Ticket Form Statuses

    Fetches all of the ticket form statuses specified by a comma separated list of ids. #### Allowed For * Anyone

    GET /api/v2/ticket_form_statuses/show_many

  • Destructive

    Delete Ticket Form Statuses

    Deletes all of of the ticket form statuses by id. #### Allowed For * Admins * Agents

    DELETE /api/v2/ticket_forms/{ticket_form_id}/ticket_form_statuses

  • Destructive

    Delete Ticket Form Status By Id

    Deletes a ticket form status by id. #### Allowed For * Admins

    DELETE /api/v2/ticket_forms/{ticket_form_id}/ticket_form_statuses/{ticket_form_status_id}

Ticket Forms

  • Read

    List Ticket Forms

    Returns a list of all ticket forms for your account if accessed as an admin or agent. End users only see ticket forms that have `end_user_visible` set to true. #### Allowed For * Anyone

    GET /api/v2/ticket_forms

  • Read

    Show Ticket Form

    #### Allowed For * Admins, Agents, and End Users

    GET /api/v2/ticket_forms/{ticket_form_id}

  • Read

    List Ticket Form Statuses of a Ticket Form

    Fetches all of the associated ticket form statuses of a ticket form. #### Allowed For * Anyone

    GET /api/v2/ticket_forms/{ticket_form_id}/ticket_form_statuses

  • Read

    Show Many Ticket Forms

    Takes an `ids` query parameter that accepts a comma-separated list of up to 100 ticket form ids. This endpoint is used primarily by the [mobile SDK](/documentation/classic-web-widget-sdks/) and the [Web Widget](/api-reference/widget/introduction/). #### Allowed For * Anyone

    GET /api/v2/ticket_forms/show_many

  • Write

    Create Ticket Form

    #### Allowed For * Admins

    POST /api/v2/ticket_forms

  • Write

    Clone an Already Existing Ticket Form

    #### Allowed For * Admins

    POST /api/v2/ticket_forms/{ticket_form_id}/clone

  • Write

    Create Ticket Form Statuses

    Creates one or many ticket form status associations #### Allowed For * Admins

    POST /api/v2/ticket_forms/{ticket_form_id}/ticket_form_statuses

  • Destructive

    Update Ticket Form

    #### Allowed For * Admins

    PUT /api/v2/ticket_forms/{ticket_form_id}

  • Destructive

    Delete Ticket Form

    #### Allowed For * Admins

    DELETE /api/v2/ticket_forms/{ticket_form_id}

  • Destructive

    Bulk Update Ticket Form Statuses of a Ticket Form

    Updates or deletes ticket form status associations. This is a bulk operation that can both add and remove ticket form status associations for a form in one call. #### Allowed For * Admins

    PUT /api/v2/ticket_forms/{ticket_form_id}/ticket_form_statuses

  • Destructive

    Update Ticket Form Status By Id

    Updates or deletes ticket form status association by id. #### Allowed For * Admins

    PUT /api/v2/ticket_forms/{ticket_form_id}/ticket_form_statuses/{ticket_form_status_id}

  • Destructive

    Reorder Ticket Forms

    #### Allowed For * Admins #### Request Parameters You can pass in the following parameter in the payload: | Name | Type | Comment | ------------------- | ------ | -------- | ticket_form_ids | array | An array of ticket form ids. Example: "[2, 23, 46, 50]"

    PUT /api/v2/ticket_forms/reorder

Ticket Metrics

  • Read

    List Ticket Metrics

    Returns a list of tickets with their metrics. Tickets are ordered chronologically by created date, from newest to oldest. The last ticket listed may not be the absolute oldest ticket in your account due to ticket archiving. Archived tickets are not included in the response. See [About archived tickets](https://support.zendesk.com/hc/en-us/articles/4408887617050) in Zendesk help. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents

    GET /api/v2/ticket_metrics

  • Read

    Show Ticket Metrics

    Returns a specific metric, or the metrics of a specific ticket. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents

    GET /api/v2/ticket_metrics/{ticket_metric_id}

  • Read

    Show Ticket Metrics By Ticket

    Returns the metrics for a specific ticket. #### Allowed For * Agents

    GET /api/v2/tickets/{ticket_id}/metrics

Conversation Log

  • Read

    List Conversation log for Ticket

    Lists the conversation log events for a specified ticket. #### Pagination - Cursor pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed for * Agents

    GET /api/v2/tickets/{ticket_id}/conversation_log

Trigger Categories

  • Read

    List Ticket Trigger Categories

    Returns all the ticket trigger categories in the account. #### Pagination * Cursor pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/trigger_categories

  • Read

    Show Ticket Trigger Category

    Returns the ticket trigger category with the specified ID.

    GET /api/v2/trigger_categories/{trigger_category_id}

  • Write

    Create Ticket Trigger Category

    Creates a ticket trigger category.

    POST /api/v2/trigger_categories

  • Write

    Update Ticket Trigger Category

    Updates the ticket trigger category with the specified ID.

    PATCH /api/v2/trigger_categories/{trigger_category_id}

  • Write

    Create Batch Job for Ticket Trigger Categories

    Creates a job that performs a batch operation for the given ticket trigger categories.

    POST /api/v2/trigger_categories/jobs

  • Destructive

    Delete Ticket Trigger Category

    Deletes the ticket trigger category with the specified ID.

    DELETE /api/v2/trigger_categories/{trigger_category_id}

Triggers

  • Read

    List Ticket Triggers

    Lists all ticket triggers for the current account. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents #### 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 trigger, if present | permissions | The permissions for each trigger | usage_1h | The number of times each trigger has been used in the past hour | usage_24h | The number of times each trigger has been used in the past day | usage_7d | The number of times each trigger has been used in the past week | usage_30d | The number of times each trigger has been used in the past thirty days

    GET /api/v2/triggers

  • Read

    Show Ticket Trigger

    #### Allowed For * Agents The Via Type value is a number instead of a text string. See [Via types reference](/documentation/ticketing/reference-guides/via-types/) for the keys.

    GET /api/v2/triggers/{trigger_id}

  • Read

    List Ticket Trigger Revisions

    List the revisions associated with a ticket trigger. Ticket trigger revision history is only available on Enterprise plans. #### Allowed For * Agents #### Sideloads The following sideloads are supported: | Name | Will sideload | ----- | ------------- | users | The user that authored each revision #### Pagination This endpoint uses cursor-based pagination. The records are ordered in descending order by the `created_at` timestamp, then by `id` on duplicate `created_at` values. The `cursor` parameter is a non-human-readable argument you can use to move forward or backward in time. Each JSON response will contain the following attributes to help you get more results: - `after_url` requests more recent results - `before_url` requests older results - `after_cursor` is the cursor to build the request yourself - `before_cursor` is the cursor to build the request yourself The properties are null if no more records are available. You can request a maximum of 1000 records using the `limit` parameter. If no `limit` parameter is supplied, it will default to 1,000.

    GET /api/v2/triggers/{trigger_id}/revisions

  • Read

    Show Ticket Trigger Revision

    Fetches a revision associated with a ticket trigger. Ticket trigger revision history is only available on Enterprise plans. #### Allowed For * Agents #### Sideloads The following sideloads are supported: | Name | Will sideload | ----- | ------------- | users | The user that authored each revision

    GET /api/v2/triggers/{trigger_id}/revisions/{trigger_revision_id}

  • Read

    List Active Ticket Triggers

    Lists all active ticket triggers. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each ticket trigger, if present | permissions | The permissions for each trigger | usage_1h | The number of times each ticket trigger has been used in the past hour | usage_24h | The number of times each ticket trigger has been used in the past day | usage_7d | The number of times each ticket trigger has been used in the past week | usage_30d | The number of times each ticket trigger has been used in the past thirty days

    GET /api/v2/triggers/active

  • Read

    List Ticket Trigger Action and Condition Definitions

    Returns the definitions of the actions a ticket trigger can perform and the definitions of the conditions under which a ticket trigger can execute. The definition of the action includes a title ("Status"), a type ("list"), and possible values. The definition of the condition includes the same fields as well as the possible operators. For a list of supported actions, see the [Actions reference](/documentation/ticketing/reference-guides/actions-reference) For a list of supported conditions, see the [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) #### Allowed For * Agents

    GET /api/v2/triggers/definitions

  • Read

    Show Ticket Trigger Limits

    Returns the number of active ticket triggers on the account and the maximum number of active ticket triggers allowed on the account's plan. #### Allowed For * Agents

    GET /api/v2/triggers/limits

  • Read

    Search Ticket Triggers

    #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/introduction/pagination/#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 ticket trigger, if present | permissions | The permissions for each ticket trigger | usage_1h | The number of times each ticket trigger has been used in the past hour | usage_24h | The number of times each ticket trigger has been used in the past day | usage_7d | The number of times each ticket trigger has been used in the past week | usage_30d | The number of times each ticket trigger has been used in the past thirty days #### Filter Use the `filter` query parameter to filter a ticket trigger search by one or more attributes. For example, the following `filter` argument filters ticket triggers by the `description` attribute: ```json { "json": { "description": "Close a ticket" } } ```

    GET /api/v2/triggers/search

  • Read

    Validate Ticket Trigger

    Validates a ticket trigger definition without creating or updating a trigger record. Useful for checking whether trigger conditions and actions are valid before submitting a create or update request. This endpoint applies create-time validation, so the body must include the required fields (`title` and `actions`); partial update bodies (which omit them) are not accepted here even though `UpdateTrigger` accepts them. #### Allowed For * Agents

    POST /api/v2/triggers/validate

  • Write

    Create Trigger

    #### Allowed For * Agents

    POST /api/v2/triggers

  • Destructive

    Update Ticket Trigger

    #### Allowed For * Agents #### 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.

    PUT /api/v2/triggers/{trigger_id}

  • Destructive

    Delete Ticket Trigger

    #### Allowed For * Agents

    DELETE /api/v2/triggers/{trigger_id}

  • Destructive

    Bulk Delete Ticket Triggers

    Deletes the ticket triggers corresponding to the provided comma-separated list of IDs. #### Allowed For * Agents #### Request Parameters The DELETE request takes one parameter, an `ids` object that lists the ticket triggers to delete. | Name | Description | ---- | ----------- | ids | The IDs of the triggers to delete #### Example request ```js { "ids": "25,23,27,22" } ```

    DELETE /api/v2/triggers/destroy_many

  • Destructive

    Reorder Ticket Triggers

    Alters the firing order of ticket triggers in the account. See [Reordering and sorting triggers](https://support.zendesk.com/hc/en-us/articles/10356973691546) in the Zendesk Help Center. The firing order is set in a `trigger_ids` array in the request body. You must include the id of every **active** ticket trigger in the account to reorder the ticket triggers — inactive triggers are excluded by the endpoint and must not be sent. If not, the endpoint will return a `400 Bad Request` (`Invalid attribute`) error and nothing is reordered. Reordering ticket triggers via the API is not permitted if you have more than one ticket trigger category. If there is more than one ticket trigger category, the endpoint will return a `LimitOneCategory` error. #### Allowed For * Agents

    PUT /api/v2/triggers/reorder

  • Destructive

    Update Many Ticket Triggers

    Updates the position or the active status of multiple ticket triggers. Any additional properties are ignored. #### Allowed For * Agents #### Request Parameters The PUT request expects a `triggers` object that lists the ticket triggers to update. A maximum of 100 ticket triggers can be updated per request. Each ticket trigger may have the following properties: | Name | Mandatory | Description | -------- | --------- | ----------- | id | yes | The ID of the ticket trigger to update | position | no | The new position of the ticket trigger | active | no | The active status of the ticket trigger (true or false) | category_id | no | The ID of the new category the ticket trigger is to be moved to #### Example Request ```js { "triggers": [ {"id": 25, "position": 3}, {"id": 23, "position": 5}, {"id": 27, "position": 9}, {"id": 22, "position": 7} ] } ```

    PUT /api/v2/triggers/update_many

User Fields

  • Read

    List User Fields

    Returns a list of custom user fields in your account. Fields are returned in the order that you specify in your user fields configuration in Zendesk Support. Clients should cache this resource for the duration of their API usage and map the key for each User Field to the values returned under the `user_fields` attribute on the [User](/api-reference/ticketing/users/users/) resource. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents

    GET /api/v2/user_fields

  • Read

    Show User Field

    #### Allowed for * Agents

    GET /api/v2/user_fields/{user_field_id}

  • Read

    List User Field Options

    Returns a list of custom user field options for the given dropdown user field. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents

    GET /api/v2/user_fields/{user_field_id}/options

  • Read

    Show a User Field Option

    #### Allowed for * Agents

    GET /api/v2/user_fields/{user_field_id}/options/{user_field_option_id}

  • Read

    Show Many User Fields

    Returns multiple user fields by their keys. #### Allowed For * Agents

    GET /api/v2/user_fields/show_many

  • Write

    Create User Field

    Creates any of the following custom field types: * text (default when no "type" is specified) * textarea * checkbox * date * integer * decimal * regexp * dropdown * tagger * lookup * multiselect See [About custom field types](https://support.zendesk.com/hc/en-us/articles/4408838961562) in Zendesk help. #### Allowed For * Admins

    POST /api/v2/user_fields

  • Write

    Create or Update a User Field Option

    Creates a new option or updates an existing option for the given drop-down user field. To update an option, include the id of the option in the `custom_field_option` object. Example: `{"custom_field_option": {"id": 10002, "name": "Pineapples", ... }`. If an option exists for the given ID, the option will be updated. Otherwise, a new option will be created. #### Response Returns one of the following status codes: - 200 with `Location: /api/v2/user_fields/{user_field_id}/options` if the user field option already exists in the database - 201 with `Location: /api/v2/user_fields/{user_field_id}/options` if the user field option is new #### Allowed For * Admins

    POST /api/v2/user_fields/{user_field_id}/options

  • Destructive

    Update User Field

    #### Updating a Dropdown (Tagger) or Multiselect Field Dropdown and multiselect fields return an array of `custom_field_options` which specify the name, value, and order of the list of dropdown or multiselect options. Understand the following behavior when updating a dropdown or multiselect field: - All options must be passed on update. Options that are not passed will be removed. As a result, these values will be removed from any organizations. - To create a new option, pass a null `id` along with `name` and `value`. - To update an existing option, pass its `id` along with `name` and `value`. - To re-order an option, reposition it in the `custom_field_options` array relative to the other options. - To remove an option, omit it from the list of options upon update. #### Example Request ```bash curl https://{subdomain}.zendesk.com/api/v2/user_fields/{user_field_id} \ -H "Content-Type: application/json" -X PUT \ -d '{"user_field": {"custom_field_options": [{"id": 124, "name": "Option 2", "value": "option_2"}, {"id": 123, "name": "Option 1", "value": "option_1"}, {"id": 125, "name": "Option 2", "value": "option_3"}]}}' \ -v -H "Authorization: Bearer {access_token}" ``` #### Allowed for * Admins

    PUT /api/v2/user_fields/{user_field_id}

  • Destructive

    Delete User Field

    #### Allowed for * Admins

    DELETE /api/v2/user_fields/{user_field_id}

  • Destructive

    Delete User Field Option

    #### Allowed for * Admins

    DELETE /api/v2/user_fields/{user_field_id}/options/{user_field_option_id}

  • Destructive

    Reorder User Field

    #### Allowed For * Admins

    PUT /api/v2/user_fields/reorder

User Passwords

  • Read

    List password requirements

    #### Allowed For * Agents * End Users

    GET /api/v2/users/{user_id}/password/requirements

  • Write

    Set a User's Password

    An admin can set a user's password only if the setting is enabled in Zendesk Support under **Settings** > **Security** > **Global**. The setting is off by default. Only the account owner can access and change this setting. #### Allowed For * Admins

    POST /api/v2/users/{user_id}/password

  • Destructive

    Change Your Password

    You can only change your own password. Nobody can change the password of another user because it requires knowing the user's existing password. However, an admin can set a new password for another user without knowing the existing password. See [Set a User's Password](#set-a-users-password) above. #### Allowed For * Agents * End Users

    PUT /api/v2/users/{user_id}/password

Views

  • Read

    List Views

    Lists shared and personal views available to the current user. #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each view, if present | permissions | The permissions for each view #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents

    GET /api/v2/views

  • Read

    Show View

    In addition to numeric IDs, the `view_id` path parameter accepts the string aliases `"incoming"`, `"my"`, and `"my_groups"` to retrieve the corresponding built-in views. #### Allowed For * Agents

    GET /api/v2/views/{view_id}

  • Read

    Count Tickets in View

    Returns the ticket count for a single view. This endpoint is rate limited to 5 requests per minute, per view, per agent. #### View Counts The view count endpoints, Count Tickets in View (this endpoint) and [Count Tickets in Views](#count-tickets-in-views), let you estimate how many tickets remain in a view without having to retrieve the entire view. They're designed to help estimate view size. From a business perspective, accuracy becomes less relevant as view size increases. To ensure quality of service, these counts are cached more heavily as the number of tickets in a view grows. For a view with thousands of tickets, you can expect the count to be cached for 60-90 minutes. As a result, the count may not reflect the actual number of tickets in your view. View counts are represented as JSON objects with the following attributes: | Name | Type | Comment | --------------- | ------------| ------- | view_id | integer | The id of the view | url | string | The API url of the count | value | integer | The cached number of tickets in the view. Can also be null if the system is loading and caching new data. Not to be confused with 0 tickets | pretty | string | A pretty-printed text approximation of the view count | fresh | boolean | false if the cached data is stale and the system is still loading and caching new data | active | boolean | Only active views if true, inactive views if false, all views if null. #### Example ```js { "view_count": { "view_id": 25, "url": "https://company.zendesk.com/api/v2/views/25/count", "value": 719, "pretty": "~700", "fresh": true } } ```

    GET /api/v2/views/{view_id}/count

  • Read

    Execute View

    Returns the column titles and the rows of the specified view. The `columns` array lists the view's column titles and includes only views parameters. The `rows` array lists the values of each column for each ticket and includes parameters from both views and tickets. Though not displayed in the view, a partial ticket object is included with each row object. **Note**: To get the full ticket objects for a specified view, use [List Tickets from a View](#list-tickets-from-a-view). This endpoint is rate limited to 5 requests per minute, per view, per agent. This rate limit includes activity in Zendesk Support. An API script is more likely to encounter rate limit errors if the authenticating agent or admin is concurrently active in Zendesk Support. The view execution system is designed for periodic rather than high-frequency API usage. In particular, views called very frequently may be cached by Zendesk. This means that the API client will still receive a result, but that result may have been computed at any time within the last 10 minutes. Zendesk recommends using the Incremental Ticket Export endpoint to get the latest changes. You can call it more often, and it returns all the tickets that changed since the last poll. For details and rate limits, see [Incremental Exports](/api-reference/ticketing/ticket-management/incremental_exports/). View output sorting can be controlled by passing the `sort_by` and `sort_order` parameters in the format described in the table in [Preview Views](#preview-views). #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/views/{view_id}/execute

  • Read

    Export View

    Returns the csv attachment of the specified view if possible. Enqueues a job to produce the csv if necessary. #### Allowed For * Agents

    GET /api/v2/views/{view_id}/export

  • Read

    List Tickets From a View

    #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/).

    GET /api/v2/views/{view_id}/tickets

  • Read

    List Active Views

    Lists active shared and personal views available to the current user. #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each view, if present | permissions | The permissions for each view #### Pagination - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents

    GET /api/v2/views/active

  • Read

    List Views - Compact

    A compacted list of shared and personal views available to the current user. This endpoint never returns more than 32 records and does not respect the "per_page" option. #### Allowed For * Agents

    GET /api/v2/views/compact

  • Read

    Count Views

    Returns an approximate count of shared and personal views available to the current user. 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

    GET /api/v2/views/count

  • Read

    Count Tickets in Views

    Returns the ticket count of each view in a list of views. Accepts up to 20 view ids per request. For the ticket count of a single view, see [Count Tickets in View](#count-tickets-in-view). Only returns values for personal and shared views accessible to the user performing the request. ***Note:*** Due to the asynchronous operation of computing the counts for the requested views, some of the views' counts could be null. This means that the system is still computing the count for that view. Periodically issue another request until all of the views' counts in the response are integers greater than zero. #### Rate limiting This endpoint is rate limited to 6 requests every 1 minute. #### Allowed For * Agents

    GET /api/v2/views/count_many

  • Read

    List View Filter Definitions

    Returns the definitions of the conditions and actions a view can perform. The definitions include conditions, output columns, groupable fields, and sortable fields. #### Allowed For * Agents

    GET /api/v2/views/definitions

  • Read

    Preview Views

    You can preview views by constructing the conditions in the proper format and nesting them under the `view` property. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference/). The output can also be controlled by passing in any of the following parameters and nesting them under the `output` property. | Name | Type | Comment | --------------- | ------- | ------- | columns | Array | The ticket fields to display. System fields are looked up by name, custom fields by title or id. See the [View columns](#view-columns) table | group_by | String | When present, the field by which the tickets are grouped | group_order | String | The direction the tickets are grouped. May be one of "asc" or "desc" | sort_order | String | The direction the tickets are sorted. May be one of "asc" or "desc" | sort_by | String | The ticket field used for sorting. This will either be a title or a custom field id. This endpoint is rate limited to 5 requests per minute, per view, per agent. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). #### Allowed For * Agents

    POST /api/v2/views/preview

  • Read

    Preview Ticket Count

    Returns the ticket count for a single preview. #### Allowed For * Agents

    POST /api/v2/views/preview/count

  • Read

    Search Views

    #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/introduction/pagination/#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 view, if present | permissions | The permissions for each view

    GET /api/v2/views/search

  • Read

    List Views By ID

    #### Allowed For * Agents #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each view, if present | permissions | The permissions for each view

    GET /api/v2/views/show_many

  • Write

    Create View

    #### Allowed For * Agents #### JSON Format The JSON format consists of one property, a `view` object that lists the values to set when the view is created. **Note**: The request must include at least one condition in the `all` array that checks one of the following fields: `status`, `type`, `group_id`, `assignee_id`, or `requester_id`. | Name | Description | ----------- | ----------- | title | Required. The title of the view | all | Required. An array of one or more conditions. A ticket must meet all of them to be included in the view. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) | any | An array of one or more conditions. A ticket must meet any of them to be included in the view. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) | description | The description of the view | active | Allowed values are true or false. Determines if the view is displayed or not | output | An object that specifies the columns to display. Example: `"output": {"columns": ["status", "description", "priority"]}`. See [View columns](#view-columns) | restriction | An object that describes who can access the view. To give all agents access to the view, omit this property The `restriction` object has the following properties. | Name | Comment | ---- | ------- | type | Allowed values are "Group" or "User" | id | The numeric ID of a single group or user | ids | The numeric IDs of a single or more groups. Recommended for "Group" `type` If `type` is "Group", the `ids` property is the preferred method of specifying the group id or ids. #### Example Request Body ```js { "view": { "title": "Kelly's tickets", "raw_title": "{{dc.tickets_assigned_to_kelly}}", "description": "Tickets that are assigned to Kelly", "active": true, "restriction": { "type": "User", "id": "213977756" }, "all": [ { "field": "status", "operator": "less_than", "value": "solved" }, { "field": "group_id", "operator": "is", "value": "24000932" }, { "field": "custom_fields_360011872073", "operator": "is", "value": "Canada" }, ... ], "output": { "columns": ["status", "requester", "assignee"], "group_by": "assignee", "group_order": "desc", "sort_by": "status", "sort_order": "desc" } } } ``` #### View columns The `output` request parameter lets you specify what columns to include in the view in the agent interface. Example: `"output": {"columns": ["status", "description", "priority"]}`. The following table lists possible columns for views in the agent UI and the corresponding values in the `columns` array. For custom fields, specify the id of the custom field in the `columns` array. You can specify a total of 10 columns to a view. | View column title in UI | Value | |---------------------------- | -------------------- | | Assigned | `assigned` | | Assignee | `assignee` | | Due Date | `due_date` | | Group | `group` | | ID | `nice_id` | | Updated | `updated` | | Assignee updated | `updated_assignee` | | Requester updated | `updated_requester` | | Updater | `updated_by_type` | | Organization | `organization` | | Priority | `priority` | | Requested | `created` | | Requester | `requester` | | Requester language | `locale_id` | | Satisfaction | `satisfaction_score` | | Solved | `solved` | | Status category | `status` | | Subject | `description` | | Submitter | `submitter` | | Ticket form | `ticket_form` | | Type | `type` | | Brand | `brand` | | Ticket status | `custom_status_id` | #### View sorting You can group and sort items in the view by adding items to the `output` parameter: | Attribute | Description |-----------------------------| ----------- | `group_by`, `sort_by` | Sort or group the tickets by a column in the [View columns](#view-columns) table. The `description`, `submitter` and `custom_status_id` columns are not supported | `group_order`, `sort_order` | Either "asc" or "desc"

    POST /api/v2/views

  • Destructive

    Update View

    #### Allowed For * Agents #### JSON Format The PUT request takes one property, a `view` object that lists the values to update. All properties are optional. **Note**: Updating a condition updates the containing array, clearing the other conditions. Include all your conditions when updating any condition. | Name | Description | ----------- | ----------- | title | The title of the view | all | An array of one or more conditions. A ticket must meet all the conditions to be included in the view. The PUT request replaces all existing conditions. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) | any | An array of one or more conditions. A ticket must meet any of them to be included in the view. At least one `all` condition must be defined with the `any` conditions. The PUT request replaces all existing `any` conditions. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) | active | Allowed values are true or false. Determines if the view is displayed or not | output | An object that specifies the columns to display. Example: `"output": {"columns": ["status", "description," "priority"]}`. See [View columns](#view-columns) | restriction | An object that describes who can access the view. To give all agents access to the view, omit this property The `restriction` object has the following properties. | Name | Comment | ---- | ------- | type | Allowed values are "Group" or "User" | id | The numeric ID of a single group or user | ids | The numeric IDs of a single or more groups. Recommended for "Group" `type` If `type` is "Group", the `ids` property is the preferred method of specifying the group id or ids. You can also update how items are sorted and grouped. See [View sorting](#view-sorting) in Create View. #### Example Request Body ```js { "view": { "title": "Code red tickets", "restriction": { "type": "Group", "ids": [10052, 10057, 10062, 10002] }, "all": [ { "field": "priority", "operator": "is", "value": "urgent" } ], "output": { "columns": ["status", "requester", "assignee", "updated"] } } } ```

    PUT /api/v2/views/{view_id}

  • Destructive

    Delete View

    #### Allowed For * Agents

    DELETE /api/v2/views/{view_id}

  • Destructive

    Bulk Delete Views

    Deletes the views corresponding to the provided list of IDs. #### Allowed For * Agents

    DELETE /api/v2/views/destroy_many

  • Destructive

    Update Many Views

    #### Allowed For * Agents #### Request Parameters The PUT request expects a `views` object that lists the views to update. Each view may have the following properties: | Name | Mandatory | Description | -------- | --------- | ----------- | id | yes | The ID of the view to update | position | no | The new position of the view | active | no | The active status of the view (true or false) #### Example Request Body ```js { "views": [ {"id": 25, "position": 3}, {"id": 23, "position": 5}, {"id": 27, "position": 9}, {"id": 22, "position": 7} ] } ```

    PUT /api/v2/views/update_many

Workspaces

  • Read

    List Workspaces

    #### Allowed For * Admins, Agents

    GET /api/v2/workspaces

  • Read

    Show Workspace

    #### Allowed For * Admins

    GET /api/v2/workspaces/{workspace_id}

  • Write

    Create Workspace

    #### Allowed For * Admins

    POST /api/v2/workspaces

  • Destructive

    Update Workspace

    #### Allowed For * Admins

    PUT /api/v2/workspaces/{workspace_id}

  • Destructive

    Delete Workspace

    #### Allowed For * Admins

    DELETE /api/v2/workspaces/{workspace_id}

  • Destructive

    Bulk Delete Workspaces

    #### Allowed For * Admins

    DELETE /api/v2/workspaces/destroy_many

  • Destructive

    Reorder Workspaces

    #### Allowed For * Admins

    PUT /api/v2/workspaces/reorder

Grant Type Tokens

  • Write

    Create Token for Grant Type

    Returns an OAuth access token in exchange for one of the following: - an [authorization code](https://support.zendesk.com/hc/en-us/articles/4408845965210#topic_pvr_ncl_1l) - a [refresh token](https://support.zendesk.com/hc/en-us/articles/4408845965210#topic_p1c_xjf_52c) - a [client secret](https://support.zendesk.com/hc/en-us/articles/4408845965210#topic_s21_lfs_qk) **Note**: The password grant type flow, which used a Zendesk username and password to get an access token, has been deprecated and is highly discouraged. To revoke an access token, see [Revoke Token](/api-reference/ticketing/oauth/oauth_tokens/#revoke-token). #### Request parameters The POST request takes the following parameters, which must be formatted as JSON: | Name | Description | ------------------------ | -------------------------------------------------- | grant_type | "authorization_code", "refresh_token", or "client_credentials" | code | Authorization grant flow only. The authorization code you received from Zendesk after the user granted access. The code is valid for only 120 seconds. See [Handle the user's authorization decision](https://support.zendesk.com/hc/en-us/articles/4408845965210#topic_ykc_dcm_dcc) in Zendesk help | client_id | The **Identifier** value specified in an OAuth client in the Zendesk Admin Center (**Apps and integrations** > **APIs** > **OAuth clients**). See [Registering your application with Zendesk](https://support.zendesk.com/hc/en-us/articles/4408845965210#topic_s21_lfs_qk) | client_secret | The **Secret** value specified in an OAuth client in the Admin Center (**Apps and integrations** > **APIs** > **OAuth clients**). See [Registering your application with Zendesk](https://support.zendesk.com/hc/en-us/articles/4408845965210#topic_s21_lfs_qk) | redirect_uri | Authorization grant flow only. The redirect URL you specified when you sent the user to the Zendesk authorization page. For ID purposes only. See [Send the user to the Zendesk authorization page](https://support.zendesk.com/hc/en-us/articles/4408845965210#topic_mkc_dcm_dcc) | scope | Valid scope for this token. A space-separated string of scope values. Must be within the client's configured allowed scopes, if set. See [Scope](#scope) below | expires_in | Number of seconds the access token is valid. Must be greater than or equal to 300 seconds (5 minutes) and less than or equal to 172,800 seconds (2 days), or less than `refresh_token_expires_in`, whichever is the shorter. Defaults to null | refresh_token_expires_in | Number of seconds the refresh token is valid. Must be greater than or equal to 604,800 seconds (7 days) or `expires_in` (if given), and less than or equal to 7,776,000 seconds (90 days). Defaults to 2,592,000 seconds (30 days) | refresh_token | A valid refresh token. See [Replacing expired access tokens](https://support.zendesk.com/hc/en-us/articles/4408845965210#topic_p1c_xjf_52c) **Authorization code example** ```javascript const tokenResponse = await axios.post( "https://{subdomain}.zendesk.com/oauth/tokens", { grant_type: "authorization_code", code: AUTHORIZATION_CODE, client_id: ZENDESK_CLIENT_ID, redirect_uri: REDIRECT_URI_PKCE, scope: "tickets:read users:read", code_verifier: CODE_VERIFIER, expires_in: 86400, refresh_token_expires_in: 604800, }, { headers: { "Content-Type": "application/json" } } ); ``` **Refresh token example** ```javascript const tokenResponse = await axios.post( "https://{subdomain}.zendesk.com/oauth/tokens", { grant_type: "refresh_token", refresh_token: REFRESH_TOKEN, client_id: ZENDESK_CLIENT_ID, client_secret: ZENDESK_CLIENT_SECRET, scope: "tickets:write", expires_in: 86400, refresh_token_expires_in: 604800, }, { headers: { "Content-Type": "application/json" } } ); ``` **Client credentials example** ```javascript const tokenResponse = await axios.post( "https://{subdomain}.zendesk.com/oauth/tokens", { grant_type: "client_credentials", client_id: ZENDESK_CLIENT_ID, client_secret: ZENDESK_CLIENT_SECRET, scope: "tickets:write", expires_in: 86400 }, { headers: { "Content-Type": "application/json" } } ); ``` #### Scope You must specify a scope to control the app's access to Zendesk resources. The "read" scope gives access to GET endpoints and includes permission to sideload related resources. The "write" scope gives access to POST, PUT, and DELETE endpoints for creating, updating, and deleting resources. **Note**: Don't confuse the **scope** parameter (singular) with the **scopes** parameter (plural) for non-grant-type tokens described in [OAuth Tokens](/api-reference/ticketing/oauth/oauth_tokens). The "impersonate" scope allows a Zendesk admin to make requests on behalf of end users. See [Making API requests on behalf of end users](/documentation/ticketing/using-the-zendesk-api/making-api-requests-on-behalf-of-end-users/). **Broad scopes** The following parameter gives read access to all resources: `"scope": "read"` The following parameter gives read and write access to all resources: `"scope": "read write"` **Resource-specific scopes** You can fine-tune access using resource-specific scopes. The syntax is as follows: `"scope": "resource:action"` For example, the following parameter restricts the scope to only reading tickets: `"scope": "tickets:read"` To give read and write access to a resource, specify both scopes: `"scope": "users:read users:write"` To give write access only to one resource, such as organizations, and read access to everything else: `"scope": "organizations:write read"` **Scope errors** There are two distinct scope-related error cases to be aware of: - **Unrecognized scope string**: If you specify a scope value that doesn't exist (for example, a typo such as `"scope": ["read", "write"]` using an array instead of a string), the endpoint still creates an access token. However, any API request made with that token will return a `403 Forbidden` error. - **Scope outside client's allowed scopes**: If the OAuth client has [allowed scopes](/api-reference/ticketing/oauth/oauth_clients/#create-client) configured and you request a scope not included in that list, the endpoint returns `400 Bad Request` with an `invalid_scope` error and no token is created. **Available scopes** | Scope | Description | | ----- | ----------- | | `read` | Read all data. Gives access to GET endpoints, including permission to sideload related resources. | | `write` | Write all data. Gives access to POST, PUT, and DELETE endpoints. | | `impersonate` | Allows Zendesk Support admins to make requests on behalf of end users. See [Making API requests on behalf of end users](/documentation/ticketing/using-the-zendesk-api/making-api-requests-on-behalf-of-end-users/). | | `account_settings:read` | View account settings. Includes account configuration, ticket and user fields, and workspaces. | | `account_settings:write` | Create, edit, and delete account settings. Includes account configuration, ticket and user fields, and workspaces. | | `ai_agents:chat` | Chat with AI agents. Includes sending messages and receiving responses via the Zendesk Developers API. | | `apps:read` | View installed apps and their settings. Includes which apps are installed and each app's settings. | | `apps:write` | Install, configure, and remove apps. Includes installing and uninstalling apps, changing settings, and uploading custom app packages. | | `auditlogs:read` | View audit logs. Includes the account-wide record of changes: who changed what and when. Read only. | | `automations:read` | View automations and their details. | | `automations:write` | Create, edit, and delete automations. | | `brands:read` | View brands and their agent assignments. | | `brands:write` | Create, edit, and delete brands and their agent assignments. | | `custom_objects:read` | View custom objects. Includes custom object definitions and record attachments. | | `custom_objects:write` | Create, edit, and delete custom objects. Includes definitions and record attachments. | | `deletion_schedules:read` | View deletion schedules. Includes data retention policies that automatically delete tickets, users, and other data. | | `deletion_schedules:write` | Delete deletion schedules. Includes deleting data retention policies. | | `dynamic_content:read` | View dynamic content items and language variants. | | `dynamic_content:write` | Create, edit, and delete dynamic content items and language variants. | | `groups:read` | View groups and their memberships. | | `groups:write` | Create, edit, and delete groups and their memberships. | | `hc:read` | View Help Center content. Includes articles, sections, categories, community posts and comments. | | `hc:write` | Create, edit, and delete Help Center content. Includes articles, sections, categories, community posts and comments. | | `macros:read` | View macros, their categories, and attachments. | | `macros:write` | Create, edit, and delete macros and their attachments. | | `organizations:read` | View organizations and their details. Includes memberships, subscriptions, and merge history. | | `organizations:write` | Create, edit, and delete organizations and manage their memberships. Includes adding and removing users, managing subscriptions, and merging organizations. | | `requests:read` | View support requests and their comments. | | `requests:write` | Submit and edit support requests. Includes creating new requests and adding to existing ones. | | `satisfaction_ratings:read` | View satisfaction ratings, scores, and reasons. | | `satisfaction_ratings:write` | Submit satisfaction ratings. Includes rating a ticket good or bad with an optional reason. | | `security:read` | View security and sign-in settings. Includes password policy, session timeouts, IP restrictions, and SSO configuration. Read only. | | `side_conversations:read` | View side conversations. Includes the side conversations on a ticket, their messages and events, and their participants. | | `side_conversations:write` | Create, update, and reply to side conversations. Includes starting side conversations with people outside the ticket by email, Slack, or Microsoft Teams, creating child tickets, sending replies and files, and importing conversations from other systems. | | `sla_policies:read` | View SLA and group SLA policies. | | `sla_policies:write` | Create, edit, delete, and reorder SLA and group SLA policies. | | `targets:read` | View targets and their delivery failures. | | `targets:write` | Create, edit, and delete targets. | | `themes:read` | View Guide themes and their files. | | `themes:write` | Create, edit, and delete Guide themes. Includes importing, updating, publishing, exporting, and deleting themes. | | `ticket_attachments:read` | View files attached to tickets. | | `ticket_attachments:write` | Upload, edit, and delete ticket attachments. Includes uploading files, updating and deleting attachments, and redacting them. | | `ticket_views:read` | View ticket views and the tickets they return. | | `ticket_views:write` | Create, edit, and delete ticket views. | | `tickets:read` | View tickets. Includes ticket contents, comments and conversation history, tags, forms and fields, audits, events, and metrics. | | `tickets:write` | Create, edit, and delete tickets. Includes adding comments, tags, merging tickets, marking spam, attachments, forms, and custom statuses. | | `triggers:read` | View triggers, trigger categories, and their revision history. | | `triggers:write` | Create, edit, delete, and reorder triggers and trigger categories. | | `users:read` | View users. Includes identities, active sessions, group, organization, and brand memberships, roles, and settings. | | `users:write` | Create, edit, and delete users and manage their access. Includes resetting passwords, ending sessions, adding identities, changing memberships, and managing custom roles. | | `webhooks:read` | View webhooks and their activity history. | | `webhooks:write` | Create, edit, test, and delete webhooks. | | `any_channel:write` | Push messages from an external channel into Zendesk. Includes creating tickets, comments, and users from an integrated channel. Write only. | | `web_widget:write` | Edit Web Widget settings and configuration. Write only. | | `zis:read` | View private integrations. Includes configurations, connections, and inbound webhooks. | | `zis:write` | Create, edit, and delete private integrations. Includes configurations, connections, and inbound webhooks. |

    POST /oauth/tokens

Get started

  1. Open Space settings → Connections and search for Zendesk.
  2. Connect your account and add the connection to the Space.
  3. Ask for what you need in any thread in that Space.

See How connections work for access and permissions, or browse all integrations.