Requests
A request is an end user's perspective on a ticket. End users can only see public comments and certain fields of a ticket. Use this API to let end users view, update, and create tickets they have access to.
You can sideload some resources with requests. See Requests in Supported Endpoints in Side-loading.
Authentication
End users can use the Requests API.
Note: An end user won't be able to view their requests if the end user added an email identity (an email address associated with a Zendesk profile) after September 17, 2017, and didn't verify the email address. The problem is flagged by the API with a 403 response. See Verifying a user's email address in the Support Help Center.
Anonymous requests are supported for ticket creation but can be disabled by administrators. These anonymous requests have a rate limit of 5 requests per hour for trial accounts. See Create Request below.
Admins and agents are treated as end users when using the Requests endpoint.
Multibrand accounts
On the Enterprise plan and above, a Support account can have more than one brand. See Understanding how Multibrand works in your account in the Support Help Center.
If you have multiple brands in your account, the Requests API only returns tickets for the brand specified in the API path. It doesn't return all tickets in the account. In the API path, the brand is specified by the subdomain. For example, a GET request to https://omniwear.zendesk.com/api/v2/requests only returns tickets for the Omniwear brand, even if Omniwear is the default brand.
Status (legacy) and Custom Ticket Status
See Status (legacy) and Custom Ticket Status in Tickets
JSON format
Requests are represented as JSON objects with the following properties:
| Name | Type | Read-only | Mandatory | Description |
|---|---|---|---|---|
| assignee_id | integer | true | false | The id of the assignee if the field is visible to end users |
| can_be_solved_by_me | boolean | true | false | If true, an end user can mark the request as solved. See Update Request |
| collaborator_ids | array | true | false | The ids of users currently CC'ed on the ticket |
| created_at | string | true | false | When this record was created |
| custom_fields | array | false | false | Custom fields for the request. See Setting custom field values in the Tickets doc |
| custom_status_id | integer | false | false | The custom ticket status id of the ticket |
| description | string | true | false | Read-only first comment on the request. When creating a request, use comment to set the description |
| due_at | string | false | false | When the task is due (only applies if the request is of type "task") |
| email_cc_ids | array | true | false | The ids of users who are currently email CCs on the ticket. See CCs and followers resources in the Support Help Center |
| followup_source_id | integer | true | false | The id of the original ticket if this request is a follow-up ticket. See Create Request |
| group_id | integer | true | false | The id of the assigned group if the field is visible to end users |
| id | integer | true | false | Automatically assigned when creating requests |
| is_public | boolean | true | false | Is true if any comments are public, false otherwise |
| organization_id | integer | true | false | The organization of the requester |
| priority | string | false | false | The priority of the request, "low", "normal", "high", "urgent" |
| recipient | string | false | false | The original recipient e-mail address of the request |
| requester_id | integer | true | false | The id of the requester |
| solved | boolean | false | false | Whether or not request is solved (an end user can set this if "can_be_solved_by_me", above, is true for that user) |
| status | string | false | false | The state of the request, "new", "open", "pending", "hold", "solved", "closed" |
| subject | string | false | true | The value of the subject field for this request if the subject field is visible to end users; a truncated version of the description otherwise |
| ticket_form_id | integer | false | false | The numeric id of the ticket form associated with this request if the form is visible to end users - only applicable for enterprise accounts |
| type | string | false | false | The type of the request, "question", "incident", "problem", "task" |
| updated_at | string | true | false | When this record last got updated |
| url | string | true | false | The API url of this request |
| via | object | false | false | Describes how the object was created. See the Via object reference |
Request Comments
Comments represent the public conversation between requesters, collaborators and agents on a request.
Request comments have the following properties:
| Name | Type | Read-only | Comment |
|---|---|---|---|
| id | integer | yes | Automatically assigned when the comment is created |
| type | string | yes | "Comment" or "VoiceComment" |
| request_id | integer | yes | The id of the request |
| body | string | no | The actual comment made by the author |
| html_body | string | yes | The actual comment made by the author formatted as HTML |
| plain_body | string | yes | The comment formatted as plain text |
| public | boolean | yes | If true, the comment is public |
| author_id | integer | yes | The id of the author |
| attachments | array | yes | Read-only list of attachments to the comment. See Attaching files |
| uploads | array | no* | *On create only. List of tokens received after uploading files to attach |
| created_at | date | yes | When this comment was created |
Request Comment Example
{"id": 1274,"type": "Comment","body": "Thanks for your help!","html_body": "<p>Thanks for your help!</p>","author_id": 1,"attachments": [{"id": 498483,"name": "crash.log","content_url": "https://company.zendesk.com/attachments/crash.log","content_type": "text/plain","size": 2532,"thumbnails": []}],"created_at": "2009-07-20T22:55:29Z"}
Example
{"assignee_id": 72983,"can_be_solved_by_me": false,"collaborator_ids": [],"created_at": "2009-07-20T22:55:29Z","description": "The fire is very colorful.","due_at": "2011-05-24T12:00:00Z","group_id": 8665,"id": 35436,"organization_id": 509974,"priority": "normal","requester_id": 1462,"status": "open","subject": "Help, my printer is on fire!","ticket_form_id": 2,"type": "problem","updated_at": "2011-05-05T10:38:52Z","url": "https://company.zendesk.com/api/v2/requests/35436","via": {"channel": "web"}}
List Requests
GET /api/v2/requests
Allowed for
- End Users
Pagination
- Cursor pagination (recommended)
- Offset pagination
See 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 instead.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| page | Query | false | Pagination parameter. Supports both traditional offset and cursor-based pagination: - Traditional: ?page=2 (integer page number) - Cursor: ?page[size]=50&page[after]=cursor (deepObject with size, after, before) These are mutually exclusive - use one format or the other, not both. | |
| per_page | integer | Query | false | Number of records to return per page. Note: Default and maximum values vary by endpoint. Check endpoint-specific documentation for limits. |
| sort_by | string | Query | false | Possible values are "updated_at", "created_at" |
| sort_order | string | Query | false | One of "asc", "desc". Defaults to "asc" |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/requests \-H "Authorization: Bearer {access_token}"
Go
import ("fmt""io""net/http")func main() {url := "https://example.zendesk.com/api/v2/requests?page=&per_page=50&sort_by=&sort_order="method := "GET"