Zendesk offers CRM software for support, sales, and customer engagement designed to create better customer relationships. Integrate Zendesk with Superblocks to build powerful internal tools that tie together customer interactions, support data, and service workflows with the rest of your company's data.
To get started using Zendesk, choose your authentication method and configure your integrations based on the instructions below.
Once you have an access token, you're ready to set up your Superblocks integration.
Once your Zendesk integration is created, you can start calling
Zendesk actions in Superblocks APIs.
Zendesk actions are REST requests. To learn more about REST requests in
Superblocks, see the
Building REST requests guide.
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
* AgentsList Requests
#### Allowed for
* End Users
Search Requests
Examples:
* `GET /api/v2/requests/search.json?query=printer`
* `GET /api/v2/requests/search.json?query=printer&organization_id=1`
* `GET /api/v2/requests/search.json?query=printer&cc_id=true`
* `GET /api/v2/requests/search.json?query=printer&status=hold,open`
#### Pagination
* Offset pagination only
See [Using Offset Pagination](/api-reference/ticketing/introduction/#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
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
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"}}` |
| 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
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
Show Reason for Satisfaction Rating
#### Allowed For
* Admins
List Search Results
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).
#### 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
[Pagination](/api-reference/introduction/pagination/) for more information.
#### Allowed For
* Admins, Agents and Light Agents
#### 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."
}
```
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.
Search Tags
Returns an array of registered and recent tag names that start with the characters specified in the `name` query parameter. You must specify at least 2 characters.
#### Pagination
* Offset pagination only
See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination).
#### Allowed For
* Agents
List Ticket Fields
Returns a list of all system and custom ticket fields in your account.
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 and id.
For accounts without access to multiple ticket forms, positions can be changed using the [Update Ticket Field](/api-reference/ticketing/tickets/ticket_fields/#update-ticket-field) endpoint or the Ticket Forms page in Zendesk Support (**Admin** > **Manage** > **Ticket Forms**). The Ticket Forms page shows the fields for the account. The order of the fields is used in the different products to show the field values in the tickets.
For accounts with access to multiple ticket forms, positions can only be changed using the [Update Ticket Field](/api-reference/ticketing/tickets/ticket_fields/#update-ticket-field) endpoint because products use the order defined on each form to show the field values instead of the general position of the ticket field in the account.
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/).
#### Allowed For
* Agents
Show Ticket Field
#### Allowed for
* Agents
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` and `value` property. The properties correspond to the "Title" and "Tag" text boxes in the admin interface. Example request body:
```json
{"ticket_field": {
"custom_field_options": [
{"name": "Apple Pie", "value": "apple"},
{"name": "Pecan Pie", "value": "pecan"}
]
}
}
```
#### Example Request
```bash
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{id}.json \
-d '{"ticket_field": {"custom_field_options": [{"name": "Apple Pie", "value": "apple"}, {"name": "Pecan Pie", "value": "pecan"}]}}' \
-H "Content-Type: application/json" -X PUT \
-v -u {email_address}:{password}
```
#### 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
},
...
]
}
}
```
#### Allowed for
* Admins
Delete Ticket Field
#### Allowed for
* Admins
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
List Tickets
List TicketsList Collaborators for a Ticket
#### Allowed For
* AgentsList 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/203690846) 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
* AgentsList Followers for a Ticket
Returns any users who follow the ticket.
#### Availability
The [CCs and Followers](https://support.zendesk.com/hc/en-us/articles/203690846) feature must be enabled in Zendesk Support.
#### Allowed For
* AgentsList Ticket Incidents
#### Allowed For
* AgentsMark Ticket as Spam and Suspend Requester
#### Allowed For
* AgentsMerge 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/203690916)
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 (Enterprise)](https://support.zendesk.com/hc/en-us/articles/203662026)
in the Support Help Center.
#### 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 Twitter, Facebook or the Channel framework
In any other case, comments default to private but can be modified with the comment privacy parameters.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.
#### Allowed For
* End user who requested the ticket
The end user must be a verified user.
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)
| 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
| twitter | object | Twitter information associated with the ticket
#### Allowed For
* AgentsShow Ticket
Returns a number of ticket properties though not the ticket comments. To get the comments, use [List Comments](/api-reference/ticketing/tickets/ticket_comments/#list-comments)
#### Allowed For
* AgentsUpdate Ticket
Update TicketDelete 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/203690936)
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).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/ticketing/managing-tickets/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
Update Many Tickets
Accepts an array of up to 100 ticket objects, or a comma-separated list of up to 100 ticket ids.Show Multiple Tickets
Accepts a comma-separated list of ticket ids to return.
This endpoint will return up to 100 tickets records.
#### Allowed For
* AgentsBulk 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
* AgentsBulk 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/203690936)
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.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/203657756)
in the Support Help Center.
The tickets are ordered chronologically by created date, from oldest to newest.
The first ticket listed may not be the oldest ticket in your
account due to [ticket archiving](https://support.zendesk.com/hc/en-us/articles/203657756).
#### Pagination
- Cursor pagination (recommended)
- Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Agents
#### Rate Limit
You can make 10 requests every 1 minute using this endpoint.
When making requests beyond page 100, you can make 5 requests every 1 minute.
The rate limiting mechanism behaves as described in
[Monitoring your request activity](/api-reference/ticketing/account-configuration/usage_limits/#monitoring-your-request-activity) in the API introduction.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
* AgentsRestore a previously deleted ticket
#### Allowed For
* AgentsList 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
Show User
#### Allowed For
* Agents
Update User
Update UserDelete User
Deletes the user and associated records from the account.
**Warning**: Deleted users are not recoverable.
To comply with GDPR, a further step is needed. See [Permanently Delete User](/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
Search Users
Returns an array of users who meet the search criteria.
#### Pagination
* Offset pagination only
See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination).
#### Allowed For
* Admins, Agents and Light Agents
and 25 moreTo use this action simply add the method, path, required query parameters, and body for the desired endpoint.
