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 Side-loading.

Authentication

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

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 joe_enduser@zendesk.com/token:{YOUR_API_TOKEN}

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

Notes:

  • Use the end-user's email address, not an agent's email address as is the case with all other API endpoints
  • 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

JSON Format

Requests are represented as JSON objects which have the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when creating requests
url string yes no The API url of this request
subject string no yes 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
description string yes yes The first comment on the request
status string no no The state of the request, "new", "open", "pending", "hold", "solved", "closed"
priority string no no The priority of the request, "low", "normal", "high", "urgent"
type string no no The type of the request, "question", "incident", "problem", "task"
custom_fields Array no no The fields and entries for this request
organization_id integer yes no The organization of the requester
requester_id integer yes no The id of the requester
assignee_id integer yes no The id of the assignee if the field is visible to end users
group_id integer yes no The id of the assigned group if the field is visible to end users
collaborator_ids array yes no Who are currently CC'ed on the ticket
via Via yes no This object explains how the request was created
due_at date no no When the task is due (only applies if the request is of type "task")
can_be_solved_by_me boolean yes no If true, end user can mark request as solved.
solved boolean no no Whether or not request is solved (an end user can set this if "can_be_solved_by_me", above, is true for that user)
ticket_form_id integer no no The numeric id of the ticket form associated with this request if the form is visible to end users - only applicable for enterprise accounts
created_at date yes no When this record was created
updated_at date yes no When this record last got updated
recipient string no no The original recipient e-mail address of the request
followup_source_id integer yes no The id of the original ticket if this request is a follow-up ticket
Example
{
  "id":                  35436,
  "url":                 "https://company.zendesk.com/api/v2/requests/35436.json",
  "created_at":          "2009-07-20T22:55:29Z",
  "updated_at":          "2011-05-05T10:38:52Z",
  "due_at":              "2011-05-24T12:00:00Z",
  "subject":             "Help, my printer is on fire!",
  "description":         "The fire is very colorful.",
  "status":              "open",
  "priority":            "normal",
  "type":                "problem",
  "organization_id":     509974,
  "assignee_id":         72983,
  "group_id":            8665,
  "requester_id":        1462,
  "collaborator_ids":    [],
  "can_be_solved_by_me": false,
  "ticket_form_id":      2,
  "via": {
    "channel": "web"
  }
}
Request Comments

Comments represent the public conversation between Requesters, Collaborators and Agents on a request.

Ticket comments have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
body string yes The actual comment made by the author
html_body string yes The actual comment made by the author formatted to HTML
author_id integer yes The id of the author
attachments array yes The attachments on this comment as Attachment objects
created_at date yes When this comment was created
Example
{
  "id": 1274,
  "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"
}

List Requests

  • GET /api/v2/requests.json
  • 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/{id}/requests.json
  • GET /api/v2/organizations/{id}/requests.json
Allowed For
  • End Users
Available parameters
Name Type Required Comments
sort_by string no Possible values are updated_at, created_at
sort_order string no 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": [
    {
      "id": 33,
      "status": "open",
      "description": "My printer is on fire!",
      ...
    }
    {
      "id": 34,
      "status": "closed",
      "description": "I can't find my keys",
      ...
    },
  ]
}

Search requests

  • GET /api/v2/requests/search.json?query=camera
  • GET /api/v2/requests/search.json?query=camera&organization_id=1
  • GET /api/v2/requests/search.json?query=camera&cc_id=true
  • GET /api/v2/requests/search.json?query=camera&status=hold,open
Allowed For
  • End Users
Example Response
Status: 200 OK

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

Show Request

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

Allowed For
  • End Users
Using curl
curl https://{subdomain}.zendesk.com/api/v2/requests/{id}.json \
  -v -u {email_address}/token:{api_token}
Example Response
Status: 200 OK

{
  "request": {
    "id": 33,
    "status": "open",
    "description": "My printer is on fire!",
    ...
  }
}

Create Request

POST /api/v2/requests.json

Allowed For
  • End users
Using curl
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"
Example Response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/requests/{id}.json

{
  "request": {
    "id": 33,
    "status": "new",
    "description": "My printer is on fire!",
    ...
  }
}
Request parameters

The POST request takes one parameter, a request object that sets one or more ticket attributes. At minimum, you must set the following required attribute:

Name Description
comment Required. A comment object that describes the problem, incident, question, or task. See Request comments
collaborators Optional. An array of numeric IDs, emails, or objects containing name and email properties. See Setting collaborators. An email notification is sent to them when the ticket is created.

You can also set any writable attribute in the JSON Format table above.

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 parameter that specifies the closed ticket. Example:

curl https://{subdomain}.zendesk.com/api/v2/requests.json \
  -d '{"request": {"via_followup_source_id": 103, "comment": {"body": "My printer is still too hot!"}}}' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

The parameter only works with closed tickets. It has no effect with other tickets.

Update Request

PUT /api/v2/requests/{id}.json

This endpoint can be used to add a comment to a request. The end-user who created the request can also use it to mark the request as solved. It can't be used to update other request attributes.

Allowed For
  • End Users
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": {
    "id": 33,
    "status": "new",
    "description": "My printer is on fire!",
    ...
  }
}
Request parameters

The PUT request takes one parameter, a request object that adds a comment, collaborators and sets the solved attribute. No other attribute can be updated with this endpoint.

Name Description
comment Optional. An object that adds a comment to the ticket. See Request comments
solved Optional. Allows the end-user who made the request to mark the request as solved
additional_collaborators Optional. An array of numeric IDs, emails, or objects containing name and email properties. See Adding collaborators. An email notification is sent to them when the ticket is updated.

Setting collaborators

When creating a ticket, you can set collaborators on a ticket using the collaborators parameter.

An email notification is sent to the collaborators when the ticket is created.

The collaborators parameter takes an array consisting of a combination of user ids, email addresses, or objects containing a name and email property.

  • 562562562
  • "someone@example.com"
  • { "name": "Someone Special", "email": "someone@example.com" }

Use an object to create the user on the fly with the appropriate name in your Zendesk.

Example request
{
  "ticket": {
    "collaborators": [ 562, "someone@example.com", { "name": "Someone Else", "email": "else@example.com" } ]
  }
}

The new or updated collaborators will be specified in the JSON response by a property named collaborator_ids. The response won't have a collaborators property.

Adding collaborators

When updating a ticket, you can add new collaborators on a ticket using the additional_collaborators parameter.

An email notification is sent to the collaborators when the ticket is updated.

The additional_collaborators takes an array consisting of a combination of user ids, email addresses, or objects containing a name and email property.

  • 562562562
  • "someone@example.com"
  • { "name": "Someone Special", "email": "someone@example.com" }
Example request
{
  "ticket": {
    "additional_collaborators": [ 562, "someone@example.com", { "name": "Someone Else", "email": "else@example.com" } ]
  }
}

The new or updated collaborators will be specified in the JSON response by a property named collaborator_ids. The response won't have a additional_collaborators property.

Listing Comments

GET /api/v2/requests/{id}/comments.json

Allowed For
  • End Users
Available parameters
Name Type Required Comments
sort_by string no Possible values are updated_at, created_at
sort_order string no One of asc, desc. Defaults to asc
Using curl
curl https://{subdomain}.zendesk.com/api/v2/requests/{id}/comments.json \
  -v -u {email_address}/token:{api_token}
Example Response
Status: 200 OK

{
  "comments": [
    {
      "id": 43,
      "body": "Thanks for your help!",
      ...
    },
    ...
  ]
}

Getting Comments

GET /api/v2/requests/{request_id}/comments/{id}.json

Allowed For
  • End Users
Using curl
curl https://{subdomain}.zendesk.com/api/v2/requests/{request_id}/comments/{id}.json \
  -v -u {email_address}/token:{api_token}
Example Response
Status: 200 OK

{
  "comment": {
    "id": 43,
    "body": "Thanks!",
    ...
  }
}