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.

Authentication

You must use the following authentication credentials with this API:

  • Use the end-user's email address, not an agent's email address as is the case with all other API end-points.
  • Use your API token as the password, and append /token to the email address.

To get your API token, go to Manage > Channels in Zendesk, and then click the Edit link in the API channel.

Example

-u joe_enduser@zendesk.com/token:{YOUR_API_TOKEN}

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 no 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
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"
}

Listing 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' when no 'order' criteria is requested.
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",
      ...
    },
  ]
}

Searching 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",
      ...
    },
  ]
}

Getting Requests

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!",
    ...
  }
}

Creating Requests

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": [...], "screencasts": [...]}}}' \
  -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 Ticket comments in Audit Events.

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

Updating Requests

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

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 updates one or more attributes in the ticket. At minimum, you must include the following required attribute:

Name Description
comment Required. An object that adds a comment to the ticket. See Ticket comments in Audit Events.

You can also update the "solved" attribute in the JSON Format table above, allowing the end-user who requested a ticket to mark that ticket as solved.

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' when no 'order' criteria is requested.
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!",
    ...
  }
}