Ticket Audits

Audits are a read-only history of all updates to a ticket. When a ticket is updated in Zendesk, Zendesk stores an audit. 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 Audit Events.

JSON Format

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

Name Type Read-only Comment
id integer yes Automatically assigned when creating audits
ticket_id integer yes The ID of the associated ticket
metadata hash yes Metadata for the audit, custom and system data
via Via yes This object explains how this audit was created
created_at date yes The time the audit was created
author_id integer yes The user who created the audit
events array yes An array of the events that happened in this audit. See Audit Events
Example
{
  "id":         35436,
  "ticket_id":  47,
  "created_at": "2009-07-20T22:55:29Z",
  "author_id":  35436,
  "metadata":  { "custom": { "time_spent": "3m22s" }, "system": { "ip_address": "184.106.40.75" }}
  "via": {
    "channel": "web"
  },
  "events": [
    {
      "id":          1564245,
      "type":        "Comment"
      "body":        "Thanks for your help!",
      "public":      true,
      "attachments": []
    },
    {
      "id":      1564246,
      "type":    "Notification"
      "subject": "Your ticket has been updated"
      "body":    "Ticket #47 has been updated"
    }
  ]
}

Listing Audits

GET /api/v2/tickets/{ticket_id}/audits.json

Allowed For
  • Agents
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": [
    {
      "created_at": "2011/09/25 22:35:44 -0700",
      "via": {
        "channel": "web"
      },
      "metadata": {
        "system": {
          "location": "San Francisco, CA, United States",
          "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"
        },
        "custom": {
        }
      },
      "id": 2127301143,
      "ticket_id": 666,
      "events": [
        {
          "html_body": "<p>This is a new private comment</p>",
          "public": false,
          "body": "This is a new private comment",
          "id": 2127301148,
          "type": "Comment",
          "attachments": [
          ]
        },
        {
          "via": {
            "channel": "rule",
            "source": {
              "to": { },
              "from": {
                "id": 35079792,
                "title": "Assign to first responder"
              },
              "rel": "trigger"
            }
          },
          "id": 2127301163,
          "value": "open",
          "type": "Change",
          "previous_value": "new",
          "field_name": "status"
        }
      ],
      "author_id": 5246746
    },
    ...
    {
      ...
      "events": [
        ...
      ],
    }
  ],
  "next_page": null,
  "previous_page": null,
  "count": 5
}

Show Audit

GET /api/v2/tickets/{ticket_id}/audits/{id}.json

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/audits/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "audit": {
    "created_at": "2011/09/25 22:35:44 -0700",
    "via": {
      "channel": "web"
    },
    "metadata": {
      "system": {
        "location": "San Francisco, CA, United States",
        "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"
      },
      "custom": {
      }
    },
    "id": 2127301143,
    "ticket_id": 666,
    "events": [
      {
        "html_body": "<p>This is a new private comment</p>",
        "public": false,
        "body": "This is a new private comment",
        "id": 2127301148,
        "type": "Comment",
        "attachments": []
      },
      {
        "via": {
          "channel": "rule",
          "source": {
            "to": { },
            "from": {
              "id": 22472716,
              "title": "Assign to first responder"
              },
            "rel": "trigger"
          }
        },
        "id": 2127301163,
        "value": "open",
        "type": "Change",
        "previous_value": "new",
        "field_name": "status"
      }
    ],
    "author_id": 5246746
  }
}

Change a comment from public to private

PUT /api/v2/tickets/{ticket_id}/audits/{id}/make_private.json

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/audits/{id}/make_private.json \
  -v -u {email_address}:{password} -X PUT -d '{}' -H "Content-Type: application/json"
Example Response
Status: 200 OK

Audit Events

An audit can include any of the following events to describe the ticket update:

An event will have its own via object if it's different from the via object of the audit.

Create event

A ticket property was set on a newly created ticket. A separate event is created for each property set.

Create events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when the event is created
type string yes Has the value Create
field_name string yes The name of the field that was set
value string / array yes The value of the field that was set

value will always be a string, except when when the value of field_name is tags.

Example
{
  "id":         1274,
  "type":       "Create"
  "field_name": "status",
  "value":      "new"
}
Change event

A ticket property was updated. The event describes the previous and newly updated value of each ticket property.

Change events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when the event is created
type string yes Has the value Change
field_name string yes The name of the field that was changed
value string / array yes The value of the field that was changed
previous_value string / array yes The previous value of the field that was changed

value and previous_value will always be strings, except when the value of field_name is tags.

Example
{
  "id":            1274,
  "type":          "Change"
  "field_name":    "subject",
  "value":         "My printer is on fire!",
  "previous_value": "I need help!"
}
Comment event

A comment was added to the ticket. The event's type is Comment. The event's properties are identical to the ticket comment object. See Ticket comments.

Example
{
  "id": 2127301148,
  "type": "Comment",
  "body": "This is a new private comment",
  "public": false,
  "created_at": "2015-07-20T22:55:29Z",
  "author_id": 123123,
  "attachments": []
}
Voice comment event

A voice comment was added to a ticket with Zendesk Voice.

Voice comments have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when the event is created
type string yes Has the value VoiceComment
data string yes A hash of properties about the call
public boolean yes If true, the ticket requester can see this comment
formatted_from string yes A formatted version of the phone number which dialed the call
formatted_to string yes A formatted version of the phone number which answered the call
body string yes The actual comment made by the author
html_body string yes The actual comment made by the author formatted to HTML
public boolean yes If this is a public comment or an internal agents only note
trusted boolean yes If this comment is trusted or marked as being potentially fraudulent
author_id integer yes The id of the author of this comment
attachments array yes The attachments on this comment as Attachment objects
Example
{
  "id":                    1274,
  "type":                  "VoiceComment"
  "body":                  "Thanks for your help!",
  "data":                  {
                             "from":                 "+14156973270",
                             "to":                   "+14129996294",
                             "recording_url":        "http//api.twilio.com/2010-04-01/Accounts/accountsid/Recordings/recording_sid",
                             "recording_duration":   "7",
                             "call_duration":        60,
                             "call_id":              171,
                             "answered_by_id":       6,            # not present for voicemails
                             "transcription_text":   "Hello",      # only present for voicemails with transcription enabled
                             "transcription_status": "completed",  # only present for voicemails with transcription enabled
                             "started_at":           2012-11-16 223622 UTC,
                             "location":             "San Francisco, California, United States",
                             "voice_transcription":  true,
                             "outbound":             false
                           },
  "formatted_from":        "+1 (123) 654-7890",
  "formatted_to":          "+1 (123) 325-7890",
  "transcription_visible": true,
  "public":                true,
  "author_id":             1,
  "body":                  "Request #219 "request" was closed and merged into this request.",
  "html_body":             "<p>Request <a target="_blank" href="/tickets/219">#219</a> &quot;aa&quot; was closed and merged into this request.</p>",
  "trusted":               true,
  "attachments":           []
}
Comment privacy change event

A public comment was marked as private.

Ticket comment privacy change events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when the event is created
type string yes Has the value CommentPrivacyChange
comment_id integer yes The id if the comment that changed privacy
public boolean yes Tells if the comment was made public or private
Example
{
  "id":         1274,
  "type":       "CommentPrivacyChange",
  "comment_id": 453,
  "public": false
}
Notification event

A notification was sent by a business rule such as a trigger when the ticket was created or updated.

Notifications have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when the event is created
type string yes Has the value Notification
subject string yes The subject of the message sent to the recipients
body string yes The message sent to the recipients
recipients array yes A array of simple objects with the ids and names of the recipients of this notification
via Via yes The business rule that created the notification
Example
{
  "id":         1275,
  "type":       "Notification"
  "subject":    "Your ticket has been updated"
  "body":       "Ticket #235 has been updated"
  "recipients": [847390, 93905],
  "via": {
    "channel": "system",
    "source": {
      "type":  "rule",
      "id":    61,
      "title": "Notify assignee of comment update"
    }
  }
}
CC event

A cc (also known as a collaborator) was notified when the ticket was updated.

Ticket CC Events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when the event is created
type string yes Has the value Cc
recipients array yes A array of simple objects with the ids and names of the recipients of this notification
via Via yes A reference to the business rule that created this notification
Example
{
  "id":         1275,
  "type":       "Cc"
  "recipients": [847390, 93905],
  "via": {
    "channel": "system",
    "source": {
      "type":  "rule",
      "id":    61,
      "title": "Notify assignee of comment update"
    }
  }
}
Satisfaction Rating Events

Satisfaction rating events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
type string yes Has the value SatisfactionRating
score string yes The rating state "offered", "unoffered", "good", "bad"
assignee_id integer yes Who the ticket was assigned to upon rating time
body string yes The users comment posted during rating
Example
{
  "id":          1274,
  "type":        "SatisfactionRating",
  "score":       "good",
  "assignee_id": 87374,
  "body":        "Thanks, you guys are great!"
}
Ticket Sharing Events

Ticket sharing events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
type string yes Has the value TicketSharingEvent
agreement_id integer yes ID of the sharing agreement
action string yes Either shared or unshared
Example
{
  "id":           1274,
  "type":         "TicketSharingEvent",
  "agreement_id": 3454,
  "action":       "shared"
}
Error event

An error occurred during the processing of the ticket.

Ticket errors have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when the event is creating
type string yes Has the value Error
message string yes The error message
Example
{
  "id":      1274,
  "type":    "Error",
  "message": 453
}
Tweet event

A comment was added to the ticket from Twitter.

Tweet events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when the event is created
type string yes Has the value Tweet
direct_message boolean yes Whether this tweet was a direct message
body string yes The body of the tweet
recipients array yes The recipients of this tweet
Example
{
  "id":             1274,
  "type":           "Tweet",
  "direct_message": false,
  "body":           "Hi there",
  "recipients":     [847390, 93905]
}
Facebook event

A comment was posted on a Facebook Wall, or a private message was sent to a Facebook Page.

Facebook events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when the event is created
type string yes Has the value FacebookEvent
page hash yes The name and graph id of the Facebook Page associated with the event
communication integer yes The Zendesk id of the associated communication (wall post or message)
ticket_via string yes "post" or "message" depending on the association with a Wall post or a private message
body string yes The value of the message posted to Facebook
Example
{
  "id":   1274,
  "type": "FacebookEvent",
  "page": {
    "name": "Zendesk",
    "graph_id": "61675732935"
  },
  "communication": 5,
  "ticket_via": "post",
  "body": "Thanks!"
}
Facebook comment event

A comment was added to a ticket from Facebook.

Facebook comments have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when the event is created
type string yes Has the value FacebookComment
data object yes Properties of the Facebook comment
body string yes The actual comment made by the author
html_body string yes The actual comment made by the author formatted as HTML
public boolean yes If this is a public comment or an internal-agents-only note
trusted boolean yes If this comment is trusted or marked as being potentially fraudulent
author_id integer yes The id of the author of this comment
graph_object_id string yes The graph object id of the associated Facebook Wall post or message
Example
{
  "id": 1274,
  "type": "FacebookComment",
  "data": {
    "type": "status"
    "content": "asrk2d",
    "attachments": [
      {
        "id": "70713f06c93b0cba705cc10239ea3e4c",
        "mime_type": "image/png",
        "name": "transpmentor.png",
        "size": 26981
      }
    ],
    "via_zendesk": false
  },
  "public": true,
  "author_id": 1,
  "body": "Thanks for your help!",
  "html_body": "<p>Thanks for your help!</p>",
  "trusted": true,
  "graph_object_id": "152318411530606_1523184115123123",
  "attachments": []
}
External event

External ticket events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when the event is created
type string yes Has the value External
resource string yes External target id
body string yes Trigger message for this target event
Example
{
  "id":       1274,
  "type":     "External",
  "resource": 135476,
  "body":     "Target this ticket {{ticket.id}}"
}
LogMeIn transcript event

LogMeIn transcript events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
type string yes Has the value LogMeInTranscript
body string yes An audit of the transcript
Example
{
  "id":   1274,
  "type": "LogMeInTranscript",
  "body": "Session ID: 1234 Technician name: Johnny User Technician email: johnny@example.com ..."
}
Push event

Push events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when the event is created
type string yes Has the value Push
value string yes Data being pushed out of our system
value_reference string yes A reference to the destination of the data
Example
{
  "id":              1274,
  "type":            "Push",
  "value":           "<li><strong>Project</strong>: Internal</li><li><strong>Task</strong>: Admin...",
  "value_reference": "Harvest Time Tracking"
}

The Via Object

The via object of a ticket audit or audit event tells you how or why the audit or event was created. Via objects have the following keys:

Name Type Comment
channel string This tells you how the ticket or event was created
source object For some channels a source object gives more information about how or why the ticket or event was created

Example

 "via": {
   "channel": "rule",
   "source": {
     "to": { },
     "from": {
       "id": 22472716,
       "title": "Assign to first responder"
     },
     "rel": "trigger"
   }
 }

The source attribute gives more information about the source of the ticket. It consists of from, to, and rel attributes. Examples:

source from to rel
an email address, name, original_recipients address, name null
"Submit a request" on website null
Zendesk widget zendesk_widget
Feedback tab feedback_tab
API - ticket sharing api
API - ticket endpoints null
API - follow-up ticket ticket_id, subject follow_up
a business rule id, title trigger or automation
a forum topic topic_id, topic_name null
a Twitter message or mention profile_url, username, name profile_url, username, name message or mention
a chat null
a call phone, formatted_phone, name phone, formatted_phone, name voicemail, inbound, or outbound
a Facebook post or message name, profile_url, facebook_id name, profile_url, facebook_id post or message
system - ticket merged ticket_id, subject merge
system - ticket follow-up ticket_id, subject follow_up
system - problem ticket solved ticket_id, subject problem