Data API

Apps running in Zendesk Support have access to a rich JavaScript data API. You can use the API to retrieve data from Zendesk Support or to manipulate the data on behalf of the current user.

This page documents all the data APIs and notes the availability of each one for your apps. The availability depends on the location of your app in Zendesk Support. See Locations.

Id

this.id() returns the unique id of the current app. This API is available to all apps.

InstallationId

this.installationId() returns the unique installation id of the current app. This API is available to all apps.

Guid

this.guid() returns a unique identifier for your app instance. This is a required parameter for iframe apps using the SDK and it is passed by default when using the iframe Handlebars helper. This identifier will be different for each location your app runs in and will change every time your app is reloaded.

Name

this.name() returns the app name of the current app. This API is available to all apps.

The installation name is accessible through this.setting('title')

Version

this.version() returns the version number of the current app. This API is available to all apps.

Setting

You can get other information about the app with the framework's setting() function, which returns the value of an app setting.

var message = "Error in " + this.setting('title') + " (app id: " + this.id() + ")";
services.notify(message, 'alert');

Current Account API

This API is always available, regardless of app location.

currentAccount();

Returns the current account as an account object.

  var currentAccount = this.currentAccount();

Current User API

This API is always available, regardless of app location.

currentUser()

Returns the currently authenticated user as a user object.

  var currentUser = this.currentUser();

Ticket Data API

This API contains a number of JavaScript functions that are available to your app if its location is the ticket sidebar. For example, the API is not available to apps in locations such as the top-bar or nav-bar.

The following example retrieves and uses the id of the current ticket:

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

this.ticket() is the data access entry point for ticket sidebar apps. In the example above, the id() method of the this.ticket() object returns the id of the current ticket.

The following example adds a tag to a ticket:

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

The tags() method returns the tags on the current ticket as an array of strings. The add() function adds tags to the ticket. The remove() function removes them.

See the Ticket Object for more information.

Comment API

this.comment() returns a comment object. This API is available to all ticket sidebar apps.

User Data API

This API contains a number of JavaScript functions that are available to your app if its location is the user sidebar.

firstLookup: function() {
  this.ajax("getExternalData", this.user().email());
}

this.user() is the data access entry point for user sidebar apps. In the example above, the email() method of the this.user() object returns the email address of the user being viewed.

See the User Object for more information.

Organization Data API

This API contains a number of JavaScript functions that are available to your app if its location is the organization sidebar.

The following example uses the name of the organization being viewed to query an external API:

firstLookup: function() {
  this.ajax("getExternalData", this.organization().name());
}

this.organization() is the data access entry point for organization sidebar apps. In the example above, the name() method of the this.organization() object returns the name of the organization being viewed.

See the Organization Object for more information.

Ticket Object

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.isNew()

Returns true if the ticket is new, false otherwise.

ticket.createdAt()

Returns when the ticket was created using the ISO 8601 format.

ticket.updatedAt()

Returns when the ticket was last updated using the ISO 8601 format. This is useful when using safe_update to protect against ticket update collisions.

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

Gets the ticket type. Returns one of the following values: ticket, question, incident, problem, task.

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

If the type is task, you can retrieve the task's due date, if any, with the ticket.customField(fieldName) function. Specify 'due_date' as the fieldName parameter.

var ticket = this.ticket();
if (ticket.type() === "task") {
  var task_due = ticket.customField('due_date');
}

If the type is incident, you can retrieve the ID of the linked problem ticket, if any, with the ticket.customField(fieldName) function. Specify 'problem_id' as the fieldName parameter.

var ticket = this.ticket();
if (ticket.type() === "incident") {
  var problem_ticket = ticket.customField('problem_id');
}
ticket.type(value)

Sets the ticket type. Accepts one of the following parameter values: question, incident, problem, or task.

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

If you set the type to task, you can set the task's due date with the ticket.customField(fieldName, value) function. Specify 'due_date' as the fieldName parameter and an ISO-8601-compliant date as the value.

var ticket = this.ticket();
ticket.type('task');
ticket.customField('due_date', '2015/02/30');

If you set the type to incident, you can link the incident to a problem ticket using the ticket.customField(fieldName, value) function. Specify 'problem_id' as the fieldName parameter and the problem ticket ID as the value.

var ticket = this.ticket();
ticket.type('incident');
ticket.customField('problem_id', 3150230);
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 is created.

You may optionally provide a name. If the requester already exists, the name is 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({ groupId: 2 })
ticket.assignee({ userId: userId, groupId: groupId })

Sets the ticket assignee to a user/group combination.

var ticket = this.ticket();
ticket.assignee({ userId: 5, groupId: 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.organization()

Returns the ticket organization, if set, as an organization object.

var ticketOrgId = this.ticket().organization().id();
ticket.brand()

Returns the ticket brand as a brand object.

var ticketBrandId = this.ticket().brand().id();
ticket.brand({ id: value })

Sets the ticket brand by the Brand ID.

var ticket = this.ticket();
ticket.brand({ id: 1234 });
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.postSaveAction()

Returns a String that will be one of "close_tab", "next_ticket", "next_play_ticket" or "stay_on_ticket". It is also possible to refer to the possible String values using the TicketPostSaveAction Object. The TicketPostSaveAction Object has the following constants available: CLOSE_TAB, NEXT_TICKET, NEXT_PLAY_TICKET, STAY_ON_TICKET.

var ticket = this.ticket();
ticket.postSaveAction(); // "stay_on_ticket"
ticket.postSaveAction() === TicketPostSaveAction.STAY_ON_TICKET; // true|false
ticket.form()

Returns the ticket form as a ticket form object.

var ticketFormID = this.ticket().form().id();
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. Specify fieldName as custom_field_<custom field ID>.

var ticket = this.ticket();
ticket.customField("custom_field_45678");
ticket.customField(fieldName, value)

Sets the ticket custom field to the passed value. Specify fieldName as custom_field_<custom field ID>.

var ticket = this.ticket();
ticket.customField("custom_field_13579", "text"); // type: text
ticket.customField("custom_field_24680", "yes"); // type: checkbox
ticket.customField("custom_field_34567", "vip"); // type: tagger
ticket.comment()

Gets the currently editing comment object.

var ticket = services.newTicket();
ticket.comment().text('Look ma, no hands!');
ticket.open();
ticket.comments()

Gets comments in the ticket audits field, including comment id, value, author and attachments.

var ticket = this.ticket();
ticket.comments().forEach(function(comment) {
  var id = comment.id();
  var author = comment.author();
  var value = comment.value();
  var firstImageAttachment = comment.imageAttachments().get(0);
  var firstNonImageAttachment = comment.nonImageAttachments()[0];
  //...
});
ticket.viewers()

Gets an array of Collision User objects representing other agents viewing the current ticket.

ticket.open()

After a Ticket object is created with the newTicket() service, opens the ticket in the current tab.

var newTicket = services.newTicket();
newTicket.subject('My Prefilled Ticket');
newTicket.open();
ticket.via()

Retrieves the via information for the current ticket.

var via = ticket.via();
via.channel // "any_channel"
via.source // { "from": { "service_info": { ... } } }

Comment Object

The Comment object lets you set or get properties of a comment while the user is entering the comment. For properties of comments already saved with the ticket, see ticket.comments() above.

comment.text()

Returns the comment text as a string.

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

Sets the comment text to the specified string.

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

Adds the specified string to the end of the comment as Markdown

var comment = this.comment();
comment.appendMarkdown('# Heading');
comment.appendHtml(value)

Adds the specified string to the end of the comment as HTML

var comment = this.comment();
comment.appendHtml('<h1>Heading</>');
comment.appendText(value)

Adds the specified string to the end of the comment as plain text

var comment = this.comment();
comment.appendText('New content');
comment.useRichText()

Boolean. Returns whether the account can render rich text (HTML) in the comment editor

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

Returns facebookPrivateMessage, facebookWallReply, internalNote, publicReply, twitterDirectMessage, or 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.

Twitter- and Facebook-related options are only accepted if those options are visible on screen.

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

Returns an array of Attachment objects representing attachments uploaded for the current comment. If no attachment has been uploaded yet, returns an empty array.

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

Attachment Object

An attachment uploaded for the current comment. See comment.attachments() above.

attachment.contentType()

Returns the content type of the attachment.

var firstAttachment = this.comment().attachments()[0];
firstAttachment.contentType(); // "image/gif"
attachment.contentUrl()

Returns the content url of the attachment.

var firstAttachment = this.comment().attachments()[0];
firstAttachment.contentUrl(); // "https://{subdomain}.zendesk.com/attachments/token/{token}/?name=myimage.gif"
attachment.filename()

Returns the filename of the attachment.

var firstAttachment = this.comment().attachments()[0];
firstAttachment.filename(); // "myimage.gif"
attachment.thumbnailUrl()

Returns the URL of the thumbnail representing the attachment.

var firstTicketAttachment = this.ticket().comments()[0].imageAttachments()[0];
firstTicketAttachment.thumbnailUrl(); // "https://{subdomain}.zendesk.com/attachments/token/{token}/?name=myimage_thumb.gif"
attachment.token()

Returns the token of current attachment, for uploading more attachments. See the Attachment API in the REST API docs.

var firstAttachment = this.comment().attachments()[0];
firstAttachment.token(); // "k02O4oHUa2ijlVsq5SvIfgmrD..."

Group Object

group.id()

Returns the group ID as an integer.

group.name()

Returns the group name as a string.

Ticket Form Object

form.id()

Returns the current ticket form ID as an integer.

form.id(id)

Sets the current ticket form to the form specified by id. id must be a valid ticket form ID otherwise this method will throw an error.

Organization Object

organization.id()

Returns the id of the organization.

organization.name()

Returns the name of the organization.

organization.domains()

Returns the domains associated with the organization.

organization.domains(value)

Sets the organization domains to the passed value.

organization.details()

Returns the details associated with the organization.

organization.details(value)

Sets the organization details to the passed value.

organization.notes()

Returns the notes associated with the organization.

organization.notes(value)

Sets the organization notes to the passed value.

organization.tags()

Returns an array of tags assigned to the organization, or an empty array.

organization.group()

Returns the group assigned to the organization as a group object.

organization.sharedTickets()

Returns true if users in the organization can view all org tickets or false if they can only view their own tickets

organization.sharedComments()

Returns true if users in the organization can view and add comment to all org tickets, false otherwise

organization.customField(fieldName)

Returns the organization custom field value as its defined type. Specify fieldName as <custom_field_key>. See Organization Fields. Example: my_text_field.

var organization = this.organization();
organization.customField("organization_text_field");
organization.customField(fieldName, value)

Sets the organization custom field to the passed value. Specify fieldName as <custom_field_key>. See User Fields. Example: my_text_field.

var organization = this.organization();
organization.customField("my_text_field", "text"); // type: text
organization.customField("my_checkbox_field", "yes"); // type: checkbox

Agreement Object

agreement.id()

Returns the agreement ID as an integer.

agreement.name()

Returns the agreement name as a string.

agreement.partnerName()

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

User Object

user.id()

Returns the user ID as an integer.

user.email()

Returns the user email as a string.

user.groups()

Returns the user groups as an array. If there are no groups available, an empty array is returned.

user.organizations()

Returns the user organizations as an array. If there are no organizations available, an empty array is returned.

user.identities()

Returns the user identities as an array.

user.name()

Returns the user name as a string.

user.role()

Returns the user role as a string. Possible values are "end-user", "agent", "admin" or a custom role id if the user has a custom role on the entreprise plan.

user.externalId()

Returns the user external ID as a string.

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.locale()

Returns the user's current locale as a string.

user.details()

Returns the user's details as a string.

user.details(value)

Sets the user details to the passed value.

user.notes()

Returns the user's notes as a string.

user.notes(value)

Sets the user notes to the passed value.

user.alias()

Returns the user's alias as a string.

user.alias(value)

Sets the user alias to the passed value.

user.signature()

Returns the user's signature as a string.

user.signature(value)

Sets the user signature to the passed value.

user.timeZone()

Returns the user's current time zone as a TimeZone Wrapper object.

user.tags()

Returns the user's tags as an array of strings.

user.avatarUrl()

Returns the URL of the user's avatar (or "photo" or "profile image") as a string.

user.customField(fieldName)

Returns the user custom field value as its defined type. Specify fieldName as <custom_field_key>. See User Fields. Example: my_text_field.

var user = this.user();
user.customField("user_text_field");
user.customField(fieldName, value)

Sets the user custom field to the passed value. Specify fieldName as <custom_field_key>. See User Fields. Example: my_text_field.

var user = this.user();
user.customField("my_text_field", "text"); // type: text
user.customField("my_checkbox_field", "yes"); // type: checkbox

Collision User Object

The following methods are in addition to the methods provided by the regular User Object

user.isEditing()

Returns a true or false depending on whether the user is editing the ticket.

user.isIdle()

Returns true or false depending on whether the user is focused on the ticket.

Account Object

currentAccount.planName()

Returns the current planName as a string.

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

Returns the current subdomain as a string.

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

Returns the account timezone as a Time Zone object.

  var timeZone = this.currentAccount().timeZone();
  timeZone.name(); // "Pacific Time (US & Canada)"
  moment('2014-06-01T12:00:00Z').tz(timeZone.ianaName()).format('ha z') // 5am PDT

Brand Object

brand.id()

Returns the id of the Brand

brand.name()

Returns the name of the brand

brand.subdomain()

Returns the subdomain associated with the brand

brand.isDefault()

Returns a boolean specifying if this brand is the default brand for the account

brand.isActive()

Returns a boolean specifying if this brand is active or not

brand.hasHelpCenter()

Returns a boolean specifying if help center is enabled for this brand

brand.url()

Return the url of the brand, including host mapping if present

brand.logo()

Returns an Attachment object representing the brand logo, or null if the brand does not have a logo set

Time Zone Object

timezone.name()

Returns the name of the time zone, e.g. "Pacific Time (US & Canada)"

timezone.translatedName()

Returns the translated name of the time zone

timezone.ianaName()

Returns the name of the time zone according to the IANA time zone database, e.g. "America/Los_Angeles"

timezone.offset()

Returns the number of minutes offset of the time zone relative to GMT, e.g. -420

timezone.formattedOffset()

Returns the string formatted offset of the time zone, e.g. GMT-07:00