Zendesk Support

1. How to connect to Zendesk Support?

You can follow the following steps to build a connection with your Zendesk Support. If you need any helps to set up your integration, please contact us.

1. Go to the Resources page and click the Add Resource button.

2. In the "Select a data source" step, select Zendesk Support under Apps.

3. In the "Configure the data source" step, enter the following information:

• Start Date: Retrieve data from a specific date and time. The date should be defined in UTC date and time, such as 2017-01-25T00:00:00Z.

• Email: the email address that is registered for your Zendesk account.

• API Token: The value of the API token generated. See here to get an API token.

• Subdomain: The subdomain for your Zendesk Support. Your subdomain can be identified from the account's URL: https://yoursubdomain.zendesk.com, and you just need to put yoursubdomain in this field (Here you don't need to add "https://" and ".zendesk.com").

4. In the "Select the tables", choose tables that you want to connect. See here for more details on each table.

5. Click Finish Setup. You will see a icon next to your Zendesk Support resource. It may take a few minutes to several hours depending on the data size and the number of your tables. Once your APP's data is ready, you will receive a notification email.

2. How to generate an API token for Zendesk Support?

Zendesk Support and Zendesk Talk can share the same API token. If you have already generated an API token for Zendesk Talk, then you can use the same one to connect to Zendesk Support.

To connect to your Zendesk account on Acho, you have to enable API token access and generate a token in Zendesk. You must be an administrator and API token access must be enabled. Here are the instructions to do so.

1. Click the Admin icon () in the sidebar, then select Channels > API. Or, you can go here directly: https://YourSUBDOMAIN.zendesk.com/agent/admin/api/settings (Remember to change "YourSUBDOMAIN" in the link to your subdomain name)

2. Enable API token access.

3. Click Add API token and find your API tokens as shown below.

4. Click Save.

3. How to set up Data Sync?

Acho supports creating schedulers to retrieve the latest data from your Zendesk Support account at a certain time interval. To see more details, you can visit here.

4. Available Tables

For every third-party App integration, there are many tables that can be imported. Outside of the reference tables, here are some of the most used tables for your analytics.

• Tickets

• Groups

• Users

• Organizations

• Ticket Audits

• Ticket Comments

• Ticket Fields

• Ticket Forms

• Ticket Metrics

• Group Memberships

• Macros

• Satisfaction Ratings

• Tags

• SLA Policies

Tickets

Tickets are the means through which your end-users (customers) communicate with agents in Zendesk Support. Tickets can originate from a number of channels, including email, Help Center, chat, phone call, Twitter, Facebook, or the API.

Name	Type	Description
id	integer	Automatically assigned when the ticket is created
allow_attachments	boolean	Permission for agents to add attachments to a comment. Defaults to true
allow_channelback	boolean	Is false if channelback is disabled, true otherwise. Only applicable for channels framework ticket
assignee_id	integer	The agent currently assigned to the ticket
brand_id	integer	Enterprise only. The id of the brand this ticket is associated with
collaborator_ids	array	The ids of users currently CC'ed on the ticket
collaborators	array	POST requests only. Users to add as cc's when creating a ticket. See Setting Collaborators
created_at	string	When this record was created
custom_fields	array	Custom fields for the ticket. See Setting custom field values
description	string	Read-only first comment on the ticket. When creating a ticket, use comment to set the description. See Description and first comment
due_at	string	If this is a ticket of type "task" it has a due date. Due date format uses ISO 8601 format.
email_cc_ids	array	The ids of agents or end-users currently CC'ed on the ticket. See CCs and followers resources in the Support Help Center
external_id	string	An id you can use to link Zendesk Support tickets to local records
follower_ids	array	The ids of agents currently following the ticket. See CCs and followers resources
followup_ids	array	The ids of the follow-ups that are created from this ticket. Ids are only visible once the ticket is closed
forum_topic_id	integer	The topic in the Zendesk Web portal this ticket originated from, if any. The Web portal is deprecated
group_id	integer	The group that this ticket is assigned to
has_incidents	boolean	Is true if a ticket is a problem type and has one or more incidents linked to it. Otherwise, the value is false.
is_public	boolean	Is true if any comments are public, false otherwise
macro_ids	array	POST requests only. List of macro IDs to be recorded in the ticket audit
organization_id	integer	The organization of the requester. You can only specify the ID of an organization associated with the requester. See Organization Memberships
priority	string	The urgency with which the ticket should be addressed. Allowed values are "urgent", "high", "normal", or "low".
problem_id	integer	For tickets of type "incident", the ID of the problem the incident is linked to
raw_subject	string	The dynamic content placeholder, if present, or the "subject" value, if not. See Dynamic Content
recipient	string	The original recipient e-mail address of the ticket
requester_id	integer	The user who requested this ticket
satisfaction_rating	object	The satisfaction rating of the ticket, if it exists, or the state of satisfaction, "offered" or "unoffered". The value is null for plan types that don't support CSAT
sharing_agreement_ids	array	The ids of the sharing agreements used for this ticket
status	string	The state of the ticket. Allowed values are "new", "open", "pending", "hold", "solved", or "closed".
subject	string	The value of the subject field for this ticket
submitter_id	integer	The user who submitted the ticket. The submitter always becomes the author of the first comment on the ticket
tags	array	The array of tags applied to this ticket
ticket_form_id	integer	Enterprise only. The id of the ticket form to render for the ticket
type	string	The type of this ticket. Allowed values are "problem", "incident", "question", or "task".
updated_at	string	When this record last got updated
url	string	The API URL of this ticket
via	object	For more information, see the Via object reference
via_followup_source_id	integer	POST requests only. The id of a closed ticket when creating a follow-up ticket. See Creating a follow-up ticket

Groups

When support requests arrive in Zendesk Support, they can be assigned to a Group. Groups serve as the core element of the ticket workflow; support agents are organized into Groups and tickets can be assigned to a Group only, or to an assigned agent within a Group. A ticket can never be assigned to an agent without also being assigned to a Group.

Name	Type	Description
id	integer	Automatically assigned when creating groups
created_at	string	The time the group was created
default	boolean	If the group is a default for the account
deleted	boolean	Deleted groups get marked as such
description	string	The description of the group
name	string	The name of the group
updated_at	string	The time of the last update of the group
url	string	The API url of this group

Users

Zendesk Support has three types of users: end users (your customers), agents, and administrators.

• End users: End users request support through tickets. End users have access to Help Center where they can view knowledge base articles and community content, access their ticket history, and submit new tickets.

• Agents: Agents work in Zendesk Support to solve tickets. Agents can be divided into multiple groups and can also belong to multiple groups. Agents don't have access to administrative configuration in Zendesk Support such as business rules or automations, but can configure their own macros and views.

• Administrators: Administrators have all the abilities of agents, plus administrative abilities. Accounts on the Enterprise plan and above can configure custom roles to give agents varying degrees of administrative access.

id	string	The time zone for the use
id	integer	Automatically assigned when the user is created
active	integer	false if the user has been deleted
alias	boolean	An alias displayed to end-users
chat_only	string	Whether or not the user is a chat-only agent
created_at	boolean	The time the user was created
custom_role_id	string	A custom role if the user is an agent on the Enterprise plan or above
default_group_id	integer	The id of the user's default group
details	integer	Any details you want to store about the user, such as an address
email	string	The user's primary email address. The primary email is specified when you create the user. On update, a secondary email is added.
external_id	string	A unique identifier from another system. The API treats the id as case insensitive. Example: "ian1" and "Ian1" are the same users
iana_time_zone	string	The time zone for the user
last_login_at	string	The last time the user signed in to Zendesk Support
locale	string	The user's locale. A BCP-47 compliant tag for the locale.
locale_id	integer	The user's language identifier
moderator	boolean	Designates whether the user has forum moderation capabilities
name	string	The user's name
notes	string	Any notes you want to store about the user
only_private_comments	boolean	true if the user can only create private comments
organization_id	integer	The id of the user's organization. If the user has more than one organization membership, the id of the user's default organization.
phone	string	The user's primary phone number. The phone number follows a format with a country dial prefix, an area code, and a subscriber number. For example, [phone].
photo	object	The user's profile picture which is represented as an Attachment object
report_csv	boolean	Whether or not the user can access the CSV report on the Search tab of the Reporting page in the Support admin interface. See Analyzing Help Center search results in Help Center. Only available on the Support Professional or Suite Growth plan or above.
restricted_agent	boolean	If the agent has any restrictions; false for admins and unrestricted agents, true for other agents
role	string	The user's role. Possible values are "end-user", "agent", or "admin"
role_type	integer	The user's role id. 0 for custom agents, 1 for the light agent, 2 for the chat agent, and 3 for the chat agent added to the Support account as a contributor.
shared	boolean	If the user is shared from a different Zendesk Support instance. Ticket sharing accounts only
shared_agent	boolean	If the user is a shared agent from a different Zendesk Support instance. Ticket sharing accounts only
shared_phone_number	boolean	Whether the phone number is shared or not. If true, the phone number can be linked with multiple users. Otherwise, the phone number is only lined with a single user.
signature	string	The user's signature. Only agents and admins can have signatures
suspended	boolean	If the agent is suspended. Tickets from suspended users are also suspended, and these users cannot sign in to the end user portal
tags	array	The user's tags. Only present if your account has user tagging enabled
ticket_restriction	string	Specifies which tickets the user has access to. Possible values are: "organization", "groups", "assigned", "requested", null
time_zone	string	The user's time zone. A time_zone name consists of a string such as "Eastern Time (US & Canada)".
two_factor_auth_enabled	boolean	If two-factor authentication is enabled
updated_at	string	The time the user was last updated
url	string	The user's API URL
user_fields	object	Values of custom fields in the user's profile.
verified	boolean	Any of the user's identities are verified. See User Identities

Organizations

Just as agents can be segmented into groups in Zendesk Support, your customers (end-users) can be segmented into organizations. You can manually assign customers to an organization or automatically assign them to an organization by their email address domain. Organizations can be used in business rules to route tickets to groups of agents or to send email notifications.

Name	Type	Description
id	integer	Automatically assigned when the organization is created
created_at	string	The time the organization was created
details	string	Any details about the organization, such as the address
domain_names	array	An array of domain names associated with this organization
external_id	string	A unique external id to associate organizations to an external record
group_id	integer	New tickets from users in this organization are automatically put in this group
name	string	A unique name for the organization
notes	string	Any notes you have about the organization
organization_fields	object	Custom fields for this organization
shared_comments	boolean	End users in this organization are able to see each other's comments on tickets
shared_tickets	boolean	End users in this organization are able to see each other's tickets
tags	array	The tags of the organization
updated_at	string	The time of the last update of the organization
url	string	The API URL of this organization

Ticket Audits

Audits are 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.

Name	Type	Description
id	integer	Automatically assigned when creating audits
author_id	integer	The user who created the audit
created_at	string	The time the audit was created
events	array	An array of the events that happened in this audit. See the Ticket Audit events reference
metadata	object	Metadata for the audit, custom, and system data
ticket_id	integer	The ID of the associated ticket
via	object	Describes how the object was created. See the Via object reference

Ticket Comments

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

Name	Type	Description
id	integer	Automatically assigned when the comment is created
attachments	array	Attachments, if any. See Attachment
author_id	integer	The id of the comment author.
body	string	The comment string
created_at	string	The time the comment was created
html_body	string	The comment formatted as HTML
metadata	object	System information (web client, IP address, etc.) and comment flags, See the details for comment flags.
plain_body	string	The comment as plain text
public	boolean	true if a public comment; false if an internal note. The initial value set on ticket creation persists for any additional comment unless you change it
type	string	Comment or VoiceComment. The JSON object for adding voice comments to tickets is different. See Adding voice comments to tickets
uploads	array	List of tokens received from uploading files for comment attachments. The files are attached by creating or updating tickets with the tokens. See Attaching files in Tickets
via	object	Describes how the object was created. See the Via object reference

Ticket Fields

Ticket fields are used for creating ticket forms where end users provide the subject and description of their question or support issue. There are two types of ticket fields. System ticket fields are the standard, default fields that agents see in a ticket. Custom ticket fields can be created in addition to system ticket fields to gather additional information from the person who is requesting support.

Name	Type	Description
id	integer	Automatically assigned when created
active	boolean	Whether this field is available
agent_description	string	A description of the ticket field that only agents can see
collapsed_for_agents	boolean	If true, the field is shown to agents by default. If false, the field is hidden alongside infrequently used fields. Classic interface only
created_at	string	The time the custom ticket field was created
custom_field_options	array	Required and presented for a custom ticket field of type "multiselect" or "tagger"
description	string	Describes the purpose of the ticket field to users
editable_in_portal	boolean	Whether this field is editable by end users in Help Center
position	integer	The relative position of the ticket field on a ticket. Note that for accounts with ticket forms, positions are controlled by the different forms
raw_description	string	The dynamic content placeholder if present, or the description value if not. See Dynamic Content
raw_title	string	The dynamic content placeholder if present, or the title value if not. See Dynamic Content
raw_title_in_portal	string	The dynamic content placeholder if present, or the "title_in_portal" value if not. See Dynamic Content
regexp_for_validation	string	For "regexp" fields only. The validation pattern for a field value to be deemed valid
removable	boolean	If false, this field is a system field that must be present on all tickets
required	boolean	If true, agents must enter a value in the field to change the ticket status to solved
required_in_portal	boolean	If true, end users must enter a value in the field to create the request
sub_type_id	integer	For system ticket fields of type "priority" and "status". Defaults to 0. A "priority" sub type of 1 removes the "Low" and "Urgent" options. A "status" sub type of 1 adds the "On-Hold" option
system_field_options	array	Presented for a system ticket field of type "tickettype", "priority" or "status"
tag	string	For "checkbox" fields only. A tag added to tickets when the checkbox field is selected
title	string	The title of the ticket field
title_in_portal	string	The title of the ticket field for end users in Help Center
type	string	System or custom field type. Editable for custom field types and only on creation. See Create Ticket Field
updated_at	string	The time the custom ticket field was last updated
url	string	The URL for this resource
visible_in_portal	boolean	Whether this field is visible to end users in Help Center

Ticket Forms

Ticket forms allow an admin to define a subset of ticket fields for display to both agents and end users. Currently, ticket forms are only available on Zendesk Enterprise accounts or Zendesk accounts with the Productivity Pack add-on.

Name	Type	Description
id	integer	Automatically assigned when creating ticket form
active	boolean	If the form is set as active
agent_conditions	array	Array of condition sets for agent workspaces
created_at	string	The time the ticket form was created
default	boolean	Is the form the default form for this account
display_name	string	The name of the form that is displayed to an end user
end_user_conditions	array	Array of condition sets for end user products
end_user_visible	boolean	Is the form visible to the end user
in_all_brands	boolean	Is the form available for use in all brands on this account
name	string	The name of the form
position	integer	The position of this form among other forms in the account, i.e. dropdown
raw_display_name	string	The dynamic content placeholder, if present, or the "display_name" value, if not. See Dynamic Content
raw_name	string	The dynamic content placeholder, if present, or the "name" value, if not. See Dynamic Content
restricted_brand_ids	array	ids of all brands that this ticket form is restricted to
ticket_field_ids	array	ids of all ticket fields which are in this ticket form. The products use the order of the ids to show the field values in the tickets
updated_at	string	The time of the last update of the ticket form
url	string	URL of the ticket form

Ticket Metrics

Returns a specific metric, or the metrics of a specific ticket.

Name	Type	Description
id	integer	Automatically assigned when the client is created
agent_wait_time_in_minutes	object	Number of minutes the agent spent waiting during calendar and business hours
assigned_at	string	When the ticket was assigned
assignee_stations	integer	Number of assignees the ticket had
assignee_updated_at	string	When the assignee last updated the ticket
created_at	string	When the record was created
first_resolution_time_in_minutes	object	Number of minutes to the first resolution time during calendar and business hours
full_resolution_time_in_minutes	object	Number of minutes to the full resolution during calendar and business hours
group_stations	integer	Number of groups the ticket passed through
initially_assigned_at	string	When the ticket was initially assigned
latest_comment_added_at	string	When the latest comment was added
on_hold_time_in_minutes	object	Number of minutes on hold
reopens	integer	Total number of times the ticket was reopened
replies	integer	The number of public replies added to a ticket by an agent
reply_time_in_minutes	object	Number of minutes to the first reply during calendar and business hours
requester_updated_at	string	When the requester last updated the ticket
requester_wait_time_in_minutes	object	Number of minutes the requester spent waiting during calendar and business hours
solved_at	string	When the ticket was solved
status_updated_at	string	When the status of the ticket was last updated
ticket_id	integer	Id of the associated ticket
updated_at	string	When the record was last updated
url	string	The API url of the ticket metric

Group Memberships

A membership links an agent to a group. Groups can have many agents, as agents can be in many groups.

Name	Type	Description
id	integer	Automatically assigned upon creation
created_at	string	The time the group was created
default	boolean	If true, tickets assigned directly to the agent will assume this membership's group
group_id	integer	The id of a group
updated_at	string	The time of the last update of the group
url	string	The API url of this record
user_id	integer	The id of an agent

Macros

A macro consists of one or more actions that modify the values of a ticket's fields. Macros are applied to tickets manually by agents. For example, you can create macros for support requests that agents can answer with a single, standard response.

Name	Type	Description
id	integer	The ID automatically assigned when a macro is created
actions	array	Each action describes what the macro will do. See Actions reference
active	boolean	Useful for determining if the macro should be displayed
created_at	string	The time the macro was created
description	string	The description of the macro
position	integer	The position of the macro
restriction	object	Access to this macro. A null value allows unrestricted access for all users in the account
title	string	The title of the macro
updated_at	string	The time of the last update of the macro
url	string	A URL to access the macro's details

Satisfaction Ratings

If you have enabled satisfaction ratings for your account, this end point allows you to quickly retrieve all ratings.

Name	Type	Description
id	integer	Automatically assigned upon creation
assignee_id	integer	The id of agent assigned to at the time of rating
comment	string	The comment received with this rating, if available
created_at	string	The time the satisfaction rating got created
group_id	integer	The id of group assigned to at the time of rating
reason	string	The reason for a bad rating given by the requester in a follow-up question. Satisfaction reasons must be enabled
reason_code	integer	The default reasons the user can select from a list menu for giving a negative rating. See Reason codes in the Satisfaction Reasons API. Can only be set on ratings with a score of "bad".
requester_id	integer	The id of ticket requester submitting the rating
score	string	The rating "offered", "unoffered", "good" or "bad"
ticket_id	integer	The id of ticket being rated
updated_at	string	The time the satisfaction rating got updated
url	string	The API url of this rating

Tags

You must enable the tagging of users and organizations in Zendesk Support for the API calls to work. In Support, click the Admin icon in the sidebar, select Settings > Customers, and enable the option.

Name	Type	Description
tags	array	An array of strings

SLA Policies

A Service Level Agreement (SLA) is a documented agreement between a support provider and their customers that specifies performance measures for support. There can be multiple SLA policies per Zendesk Support account.

Name	Type	Description
id	integer	Automatically assigned when created
created_at	string	The time the SLA policy was created
description	string	The description of the SLA policy
filter	object	An object that describes the conditions that a ticket must match in order for an SLA policy to be applied to that ticket. See Filter.
policy_metrics	array	Array of Policy Metric objects
position	integer	Position of the SLA policy that determines the order they will be matched. If not specified, the SLA policy is added as the last position
title	string	The title of the SLA policy
updated_at	string	The time of the last update of the SLA policy
url	string	URL of the SLA Policy reacord