Ticket Audits

Audits are a read-only history of all updates to a ticket and the events that occur as a result of these updates. When a Ticket is updated in Zendesk, we store an Audit. Each Audit represents a single update to the Ticket, and each Audit includes a list of changes, such as:

  • Changes to ticket fields
  • Addition of a new comment
  • Addition or removal of tags
  • Notifications sent to Groups, Assignees, Requesters and CCs

To learn more about adding new comments to tickets, see our Ticket documentation.

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

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

Audit Events

An Audit contains many Events. These Events represent all activity which occurs on a Ticket, including public and private Comments, field changes, notifications send by business rule execution, and events which send notification to external services via our Targets framework.

If an Event has a different Via than its Audit, it will have its own Via object.

Ticket Comments

Ticket comments represent the conversation between requesters, collaborators, and agents. Comments can be public or private.

JSON Format

Ticket comments are represented as JSON objects with the following properties:

Name Type Read-only Comment
id integer yes Automatically assigned when the comment is created
type string yes Has the value Comment
body string yes The comment string
html_body string yes The comment formatted as HTML
public boolean no true if a public comment; false if an internal note
author_id integer yes The id of the comment author
attachments array yes Attachments, if any. See Attachment
via object yes How the comment was created. See Via Object
metadata object yes System information (web client, IP address, etc.)
created_at date yes The time the comment was created
Example
{
  "id":        1274,
  "type":      "Comment"
  "body":      "Thanks for your help!",
  "public":    true,
  "created_at": "2009-07-20T22:55:29Z",
  "author_id": 123123,
  "attachments": [
    {
      "id":           498483,
      "name":         "crash.log",
      "content_url":  "https://company.zendesk.com/attachments/crash.log",
      "content_type": "text/plain",
      "size":         2532,
      "thumbnails":   []
    }
  ],
  "metadata": {
    ...
  },
  "via": {
    ...
  },
}
Ticket Voice Comments

Voice Comments are added to a ticket via our integrated Zendesk Voice feature.

Voice Comments have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
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":           []
}
Ticket Comment Privacy Change

If an Agent erroneously makes a public comment on a Ticket when they intended for it to be private, they can mark the comment as private. This event tracks the fact that this occurred.

Ticket comment privacy change events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
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
}
Ticket Create Events

Each property that is set on a newly created Ticket is tracked with a Create event.

Create events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
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 field_name is tags

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

When a ticket is updated, Change events track 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 creating events
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 when the field_name is tags

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

When a Ticket is created or updated, business rules are evaluated against the Ticket. These business rules can be configured to send various notifications.

Notifications have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
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 object holding the ids and names of the recipients of this notification
via Via yes A reference to the trigger that created this 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"
    }
  }
}
Ticket CC Events

When a CC (also known as a Collaborator) is notified of a Ticket update, a CC event is added.

Ticket CC Events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
type string yes Has the value Cc
recipients array yes A array of simple object holding the ids and names of the recipients of this notification
via Via yes A reference to the trigger 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"
    }
  }
}
Ticket Errors

Ticket Error events track any system errors that occur in the processing of a ticket.

Ticket errors have the following keys:

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

External ticket events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
type string yes Has the value External
resource string yes TODO
body string yes TODO
success string yes TODO
Example
{
  "id":       1274,
  "type":     "External",
  "resource": "WE NEED A GOOD EXAMPLE", //TODO
  "body":     "WE NEED A GOOD EXAMPLE", //TODO
  "success":  "WE NEED A GOOD EXAMPLE" //TODO
}
Facebook Events

Facebook Events track when a Facebook comment was posted back to a Facebook Wall post or Facebook Page private message.

Facebook Events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
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 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!"
}
Ticket Facebook Comments

Facebook Comments are added to a ticket via our integrated Facebook feature.

Facebook Comments have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
type string yes Has the value FacebookComment
data string yes A hash of properties about 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 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
graph_object_id string yes The graph object id of the associated facebook wall post/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": []
}
Log Me In Transcript Events

Log Me In 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 Events

Push events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
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"
}
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!"
}
Tweet Events

Tweet events have the following keys:

Name Type Read-only Comment
id integer yes Automatically assigned when creating events
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]
}
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"
}