Data API

Apps running within Zendesk have access to a rich Javascript Data API which can be used to fetch information about data within Zendesk, as well as to manipulate that data on behalf of the current user.

The portion of the Data API that your app has access to depends on the location of your app. This section will document all of the Data API, and will make note of the locations corresponding to each API.

Ticket Data API

This API contains a number of Javascript functions that are available to your app if its location is the ticket side-bar.

Here is an example of using this API, excerpted from the built-in JIRA app:

firstLookup: function() {
  this.ajax("externalLinks", this.ticket().id());
}

The excerpt doesn't show the full context of this code. It should, however be clear how to access ticket data:

this.ticket()

The above function is the entry point to data access in your Ticket sidebar app. Note the id() function that you can call on the value returned by the ticket() function. The code in the above snippet invokes an AJAX request with the id of the current ticket.

Here is another example from the same built-in JIRA app:

handleAddTagResult: function(e, data) {
  var ticket = this.ticket();
  ticket.tags().add(this.TICKET_JIRA_TAG);
}

The tags function above returns the tags on the current ticket as an array of strings that also has an add (and similarly remove) function to add to the list of tags.

A full listing of all the of the ticket Data API follows.

ticket.id()

Returns the ticket ID as an integer.

  var ticket = this.ticket();
  ticket.id();

ticket.subject()

Returns the ticket subject as a string.

  var ticket = this.ticket();
  ticket.subject();

ticket.subject(value)

Sets the ticket subject to the passed string.

  var ticket = this.ticket();
  ticket.subject("This is important");

ticket.description()

Returns the ticket description as a string.

  var ticket = this.ticket();
  ticket.description();

ticket.status()

Returns one of: new, open, pending, solved, closed, deleted

  var ticket = this.ticket();
  ticket.status();

ticket.status(value)

Sets the ticket status.

You can pass in one of the following values: open, pending, solved

  var ticket = this.ticket();
  ticket.status("pending");

ticket.priority()

Returns one of: -, low, normal, high, urgent

  var ticket = this.ticket();
  ticket.priority();

ticket.priority(value)

Sets the ticket priority.

You can pass in one of the following values: low, normal, high, urgent

  var ticket = this.ticket();
  ticket.priority("low");

ticket.type()

Returns one of: ticket, question, incident, problem, task

  var ticket = this.ticket();
  ticket.type();

ticket.type(value)

Sets the ticket type.

You can pass in one of the following values: question, incident, problem, task

  var ticket = this.ticket();
  ticket.type("question");

ticket.requester()

Returns the ticket requester as an user object.

  var ticket = this.ticket();
  ticket.requester()

ticket.requester({ email: value [, name: newName] })

Sets the ticket requester. If no user is matched, a new requester will be created.

You may optionally provide a name. If the requester already exists, the name will be ignored.

  var ticket = this.ticket();
  ticket.requester({ email: "someone@example.com" });
  ticket.requester({ email: "someone@example.com", name: 'A Name' });

ticket.requester({ id: value })

Sets the ticket requester.

  var ticket = this.ticket();
  ticket.requester({ id: 10 })

ticket.assignee()

Returns the ticket assignee as an object.

Assignee is a composition of user (an agent) and his/her group.

  var ticket = this.ticket();
  ticket.assignee();

ticket.assignee({ groupId: groupId })

Sets the ticket assignee to a group.

  var ticket = this.ticket();
  ticket.assignee({ groupdId: 2 })

ticket.assignee({ userId: userId, groupId: groupId })

Sets the ticket assignee to a user/group combination.

  var ticket = this.ticket();
  ticket.assignee({ userId: 5, groupdId: 2 })

ticket.assignee().user()

Returns the ticket assignee user as an user object.

  var ticket = this.ticket();
  ticket.assignee().user();

ticket.assignee().group()

Returns the ticket assignee group as an group object.

  var ticket = this.ticket();
  ticket.assignee().group();

ticket.collaborators()

Returns the list of collaborators on the ticket as an array of user objects.

  var ticket = this.ticket();
  ticket.collaborators();

The returned array has some additional functionality explained below.

ticket.collaborators().add({ email: value })

Adds the passed email as a new collaborator on the ticket.

  var ticket = this.ticket();
  ticket.collaborators().add({ email: "someone@example.com" });

ticket.collaborators().add({ id: value })

Adds the passed user (matched by id) as a new collaborator on the ticket.

  var ticket = this.ticket();
  ticket.collaborators().add({ id: 15 });

ticket.collaborators().remove({ email: "someone@example.com" })

Removes the passed email from the list of collaborators on the ticket.

  var ticket = this.ticket();
  ticket.collaborators().remove({ email: "someone@example.com" });

ticket.collaborators().remove({ id: value })

Removes the passed user (matched by id) from the list of collaborators on the ticket.

  var ticket = this.ticket();
  ticket.collaborators().remove({ id: value });

ticket.tags()

Returns the list of tags on the ticket as an array of strings.

  var ticket = this.ticket();
  ticket.tags(); //["foo", "bar"]

The returned array has some additional functionality explained below.

ticket.tags().add(value)

Adds the passed string as a new tag on the ticket.

  var ticket = this.ticket();
  ticket.tags().add("baz");

You can also add multiple tags at once using:

  var ticket = this.ticket();
  ticket.tags().add(["baz", "turnip"]);

ticket.tags().remove(value)

Removes the passed string from the list of tags on the ticket.

  var ticket = this.ticket();
  ticket.tags().remove("baz");

ticket.tags([value1, value2...])

Sets multiple tags at once.

  var ticket = this.ticket();
  ticket.tags(["bar", "baz"]);

ticket.sharedWith()

Returns the ticket shared agreement as an array of agreement objects. (at this time only one agreement is allowed).

  var ticket = this.ticket();
  var agreements = ticket.sharedWith();
  var currentAgreement = agreements[0]; // Corresponds to the selected element in the sharing dropdown. Returns `undefined` if nothing is selected.

ticket.sharedWith([ { id: value } ])

Sets the shared with field to the passed value.

  var ticket = this.ticket();
  ticket.sharedWith([ { id: 1 } ]);
  ticket.sharedWith({ id: 1 }); // Optionally, passing a hash is accepted
  ticket.sharedWith([{ id: 1 }, { id: 2 }]); // Will throw an exception, only one agreement is allowed at this time.

ticket.customField(fieldName)

Returns the ticket custom field value as its defined type.

  var ticket = this.ticket();
  ticket.customField("custom_field_1");

ticket.customField(fieldName, value)

Sets the ticket custom field to the passed value.

  var ticket = this.ticket();
  ticket.customField("custom_field_1", "text"); // type: text
  ticket.customField("custom_field_2", "yes"); // type: checkbox
  ticket.customField("custom_field_3", "vip"); // type: tagger

Comment API

This API is available if location is the ticket side-bar.

comment.text()

Returns the comment text as a string.

var comment = this.comment();
comment.text();

comment.text(value)

Sets the comment text to the passed string.

var comment = this.comment();
comment.text('New Comment');

comment.type()

Returns one of: facebookPrivateMessage, facebookWallReply, internalNote, publicReply, twitterDirectMessage, twitterReply.

var comment = this.comment();
comment.type();

comment.type(value)

Sets the comment type.

You can pass in one of the following values: facebookPrivateMessage, facebookWallReply, internalNote, publicReply, twitterDirectMessage, twitterReply.

For Twitter and Facebook related options, they'll only be accepted if those options are visible on screen.

var comment = this.comment();
comment.type('internalNote');

Current Account API

This API is always available, regardless of app location.

currentAccount();

Returns an array relative to the data available for the account the app is running in.

  var currentAccount = this.currentAccount();

currentAccount.id()

Returns the current account id as an integer.

  var currentAccount = this.currentAccount();
  currentAccount.id();

currentAccount.subdomain()

Returns the current subdomain as a string.

  var currentAccount = this.currentAccount();
  currentAccount.subdomain();

Current User API

This API is always available, regardless of app location.

currentUser()

Returns the currently currently authenticated user as an user object.

  var currentUser = this.currentUser();

Group Object

group.id()

Returns the group ID as an integer.

  group.id();

group.name()

Returns the group name as a string.

  group.name();

Agreement Object

agreement.id()

Returns the agreement ID as an integer.

  agreement.id();

agreement.name()

Returns the agreement name as a string.

  agreement.name();

agreement.partnerName()

Returns the partner name as a string. The partner name may be null.

  agreement.partnerName();

User Object

user.id()

Returns the user ID as an integer.

  user.id();

user.email()

Returns the user email as a string.

  user.email();

user.name()

Returns the user name as a string.

  user.name();

user.externalId()

Returns the user external ID as a string.

  user.externalId();

user.externalId(value)

Sets the user external ID. This method immediately saves the changed user; it does not wait for the current ticket to be saved.

  user.externalId('abc123');