Ticket Audits
Audits are a read-only history of all updates to a ticket. When a ticket is updated in Zendesk Support, an audit is stored. Each audit represents a single update to the ticket. An update can consist of one or more events. Examples:
- The value of a ticket field was changed
- A new comment was added
- Tags were added or removed
- A notification was sent
For a complete list, see the Ticket Audit events reference.
JSON Format
Ticket Audits are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
author_id | integer | true | false | The user who created the audit |
created_at | string | true | false | The time the audit was created |
events | array | false | false | An array of the events that happened in this audit. See the Ticket Audit events reference |
id | integer | true | false | Automatically assigned when creating audits |
metadata | object | true | false | Metadata for the audit, custom and system data |
ticket_id | integer | true | false | The ID of the associated ticket |
via | object | false | false | Describes how the object was created. See the Via object reference |
Example
{
"author_id": 35436,
"created_at": "2009-07-20T22:55:29Z",
"events": [
{
"attachments": [],
"body": "Thanks for your help!",
"id": 1564245,
"public": true,
"type": "Comment"
},
{
"body": "Ticket #47 has been updated",
"id": 1564246,
"subject": "Your ticket has been updated",
"type": "Notification"
}
],
"id": 35436,
"metadata": {
"custom": {
"time_spent": "3m22s"
},
"system": {
"ip_address": "184.106.40.75"
}
},
"ticket_id": 47,
"via": {
"channel": "web"
}
}
List All Ticket Audits
GET /api/v2/ticket_audits
GET /api/v2/ticket_audits.json?cursor=fDE1MDE1OTE1MzQuMHx8MTEzMjQ4NDI1MQ%3D%3D
Archived tickets are not included in the response. See About archived tickets in the Support Help Center.
Pagination
This endpoint uses a variant of cursor pagination with some differences from cursor pagination used in other endpoints.
The records are ordered sequentially by the created_at
timestamp, then by id within duplicate timestamp values. The first page will return the most recent audits.
The cursor
parameter is a non-human-readable argument you can use to move forward or backward in time.
Each JSON response will contain the following attributes to help you get more results:
after_url
requests more recent resultsbefore_url
requests older resultsafter_cursor
is the cursor to build the request yourselfbefore_cursor
is the cursor to build the request yourself.
The after_cursor
and before_cursor
attributes may contain non-URL-safe characters. Make sure to URL-encode them, or simply use the after_url
or before_url
values to paginate.
The properties are null if no more records are available.
You can request a maximum of 1,000 results. The default number of results is 1,000, but you can change it with the limit
parameter.
Allowed For
- Admins
Stability
- Development
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
limit | integer | Query | false | Maximum number of results returned |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_audits.json?limit=1000 \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"after_cursor": "MTUwMTYwNzUyMi4wfHwxMzQ3NTMxNjcxfA==",
"after_url": "https://subdomain.zendesk.com/api/v2/ticket_audits.json?cursor=MTUwMTYwNzUyMi4wfHwxMzQ3NTMxNjcxfA%3D%3D\u0026limit=1000",
"audits": [
{
"author_id": 35436,
"created_at": "2011-09-25T22:35:44Z",
"events": [
{
"attachments": [],
"body": "Thanks for your help!",
"id": 1564245,
"public": true,
"type": "Comment"
},
{
"body": "Ticket #47 has been updated",
"id": 1564246,
"subject": "Your ticket has been updated",
"type": "Notification"
}
],
"id": 2127301143,
"metadata": {
"custom": {
"time_spent": "3m22s"
},
"system": {
"ip_address": "184.106.40.75"
}
},
"ticket_id": 123,
"via": {
"channel": "web"
}
}
],
"before_cursor": "fDE1MDE1NzUxMjIuMHx8MTM0NzM0MzAxMQ==",
"before_url": "https://subdomain.zendesk.com/api/v2/ticket_audits.json?cursor=fDE1MDE1NzUxMjIuMHx8MTM0NzM0MzAxMQ%3D%3D\u0026limit=1000"
}
List Audits for a Ticket
GET /api/v2/tickets/{ticket_id}/audits
Lists the audits for a specified ticket.
Allowed for
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/audits.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"audits": [
{
"author_id": 5246746,
"created_at": "2011-09-25T22:35:44Z",
"events": [
{
"attachments": [],
"body": "This is a new private comment",
"html_body": "\u003cp\u003eThis is a new private comment\u003c/p\u003e",
"id": 2127301148,
"public": false,
"type": "Comment"
},
{
"field_name": "status",
"id": 2127301163,
"previous_value": "new",
"type": "Change",
"value": "open",
"via": {
"channel": "rule",
"source": {
"from": {
"id": 35079792,
"title": "Assign to first responder"
},
"rel": "trigger",
"to": {}
}
}
}
],
"id": 2127301143,
"metadata": {
"custom": {},
"system": {
"client": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.1 (KHTML, like Gecko) Chrome/14.0.835.186 Safari/535.1",
"ip_address": "76.218.201.212",
"location": "San Francisco, CA, United States"
}
},
"ticket_id": 666,
"via": {
"channel": "web"
}
}
],
"count": 1,
"next_page": null,
"previous_page": null
}
Show Audit
GET /api/v2/tickets/{ticket_id}/audits/{ticket_audit_id}
Allowed for
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_audit_id | integer | Path | true | The ID of the ticket audit |
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/audits.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"audit": {
"author_id": 5246746,
"created_at": "2011-09-25T22:35:44Z",
"events": [
{
"attachments": [],
"body": "This is a new private comment",
"html_body": "\u003cp\u003eThis is a new private comment\u003c/p\u003e",
"id": 2127301148,
"public": false,
"type": "Comment"
},
{
"field_name": "status",
"id": 2127301163,
"previous_value": "new",
"type": "Change",
"value": "open",
"via": {
"channel": "rule",
"source": {
"from": {
"id": 22472716,
"title": "Assign to first responder"
},
"rel": "trigger",
"to": {}
}
}
}
],
"id": 2127301143,
"metadata": {
"custom": {},
"system": {
"client": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.1 (KHTML, like Gecko) Chrome/14.0.835.186 Safari/535.1",
"ip_address": "76.218.201.212",
"location": "San Francisco, CA, United States"
}
},
"ticket_id": 666,
"via": {
"channel": "web"
}
}
}
Change a comment from public to private
PUT /api/v2/tickets/{ticket_id}/audits/{ticket_audit_id}/make_private
Allowed for
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_audit_id | integer | Path | true | The ID of the ticket audit |
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/audits/{ticket_audit_id}/make_private.json \
-v -u {email_address}:{password} -X PUT -d '{}' -H "Content-Type: application/json"
Example Response
Status 200 OK