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.

You must use an API token or an OAuth token with this API. Basic authentication is not supported.

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. See Create Request below.

Admins and agents have all the permissions of end users and anonymous users.

API token

Use the following authentication format with the end user's email address and an API token:

{enduser_email_address}/token:{api_token}

Example:

-u [email protected]/token:{YOUR_API_TOKEN}

To get an API token, go to Admin > Channels > API in the Zendesk Support admin interface, then click the Add New Token link.

Notes:

  • When using an API token to create requests on behalf of end users, use the end user's email address and not an agent's email address
  • Append the string /token to the email address and use the API token as the password
OAuth token

The Requests API supports OAuth authorization flows. Learn more. In your requests, specify the access token in an Authorization header as follows:

Authorization: Bearer {access_token}

Example:

curl -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo" https://obscura.zendesk.com/api/v2/requests.json

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.json only returns tickets for the Omniwear brand, even if Omniwear is the default brand.

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, end user can mark request as solved.
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
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.json",  "via": {    "channel": "web"  }}

List Requests

  • GET /api/v2/requests
  • GET /api/v2/requests.json?status=hold,open
  • GET /api/v2/requests/open.json
  • GET /api/v2/requests/solved.json
  • GET /api/v2/requests/ccd.json
  • GET /api/v2/users/{user_id}/requests.json
  • GET /api/v2/organizations/{organization_id}/requests.json

Allowed For

  • End Users

Parameters

Name Type In Required Description
sort_by string Path false Possible values are "updated_at", "created_at"
sort_order string Path false One of "asc", "desc". Defaults to "asc"

Using curl

curl https://{subdomain}.zendesk.com/api/v2/requests.json \  -v -u {email_address}/token:{api_token}

Example Response

Status 200 OK
{  "requests": [    {      "description": "My printer is on fire!",      "id": 33,      "status": "open",      "subject": "Help!"    },    {      "description": "I can't find my keys",      "id": 34,      "status": "closed",      "subject": "Help!"    }  ]}

Search Requests

  • GET /api/v2/requests/search

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

Allowed For

  • End Users

Parameters

Name Type In Required Description
query string Path false The syntax and matching logic for the string is detailed in the Zendesk Support search reference. See also Query basics in the Tickets API doc.

Using curl

curl https://{subdomain}.zendesk.com/api/v2/requests/search.json?query={search_string} \  -v -u {email_address}/token:{api_token}

Example Response

Status 200 OK
{  "requests": [    {      "description": "My printer is on fire!",      "id": 33,      "status": "open",      "subject": "Help!"    },    {      "description": "I can't find my keys",      "id": 34,      "status": "closed",      "subject": "Help!"    }  ]}

Show Request

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

Sideloads

The following sideloads are supported:

Name Will sideload
users The email ccs for a request by side-loading users

Allowed For

  • End Users

Parameters

Name Type In Required Description
request_id integer Path true The ID of the request

Using curl

curl https://{subdomain}.zendesk.com/api/v2/requests/{request_id}.json \  -v -u {email_address}/token:{api_token}

Example Response

Status 200 OK
{  "request": {    "description": "My printer is on fire!",    "id": 33,    "status": "open",    "subject": "Help!"  }}

Create Request

  • POST /api/v2/requests

Accepts a request object that sets one or more properties.

Additional properties

In addition to the writable request properties in the JSON Format table 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
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
requester object yes* *Required for anonymous requests. Specifies the requester of the anonymous request. See 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.

Allowed For

  • End users
  • Anonymous users (rate limit of 5 requests per hour)

Using curl

Authenticated request

curl https://{subdomain}.zendesk.com/api/v2/requests.json \  -d '{"request": {"subject": "Help!", "comment": {"body": "My printer is on fire!", "uploads": [...] }}}' \  -v -u {email_address}/token:{api_token} -X POST -H "Content-Type: application/json"

Using curl

Anonymous request

curl https://{subdomain}.zendesk.com/api/v2/requests.json \  -d '{"request": {"requester": {"name": "Anonymous customer"}, "subject": "Help!", "comment": {"body": "My printer is on fire!" }}}' \  -X POST -H "Content-Type: application/json"

Example Response

Status 201 Created
{  "request": {    "description": "My printer is on fire!",    "id": 33,    "status": "new",    "subject": "Help!"  }}

Update Request

  • PUT /api/v2/requests/{request_id}

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

Allowed For

  • End users

Parameters

Name Type In Required Description
request_id integer Path true The ID of the request

Using curl

curl https://{subdomain}.zendesk.com/api/v2/requests/{id}.json \  -d '{"request": {"comment": {"body": "Thanks!"}}}' \  -v -u {email_address}/token:{api_token} -X PUT -H "Content-Type: application/json"

Example Response

Status 200 OK
{  "request": {    "description": "My printer is on fire!",    "id": 33,    "status": "new",    "subject": "Help!"  }}

Listing Comments

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

Allowed For

  • End Users

Parameters

Name Type In Required Description
role string Query false One of "agent", "end_user". If not specified it does not filter
since string Query false Filters the comments from the given datetime
sort_by string Query false Possible values are "updated_at", "created_at"
sort_order string Query false One of “asc”, “desc”. Defaults to “asc”
request_id integer Path true The ID of the request

Using curl

curl https://{subdomain}.zendesk.com/api/v2/requests/{request_id}/comments.json \  -v -u {email_address}/token:{api_token}

Example Response

Status 200 OK
{  "comments": [    {      "body": "Thanks for your help",      "id": 43    }  ]}

Getting Comments

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

Allowed For

  • End Users

Parameters

Name Type In Required Description
request_id integer Path true The ID of the request
ticket_comment_id integer Path true The ID of the ticket comment

Using curl

curl https://{subdomain}.zendesk.com/api/v2/requests/{request_id}/comments/{ticket_comment_id}.json \  -v -u {email_address}/token:{api_token}

Example Response

Status 200 OK
{  "comment": {    "body": "Thanks!",    "id": 43  }}