Zendesk Source

Zendesk is a cloud-based customer service platform for enterprises. It provides a cloud-based customer support platform which allows quicker and easier interaction between businesses and customers. Visit website

This is an Object Cloud Source which can export data from its third party tool and import it directly into your Segment warehouse.

This document was last updated on April, 2018. If you notice any gaps, outdated information or simply want to leave some feedback to help us improve our documentation, please let us know!

Getting Started

  1. From your workspace’s sources page, click add source.

  2. Choose Zendesk.

  3. Give the source a nickname and a schema name. The nickname will be used to designate the source in the Segment interface, and the schema name is the namespace you’ll be querying against in your warehouse. Both can be whatever you like, but we recommend sticking to something that reflects the source itself, like Zendesk for nickname and zendesk or zendesk_prod for the schema name.

    Note that you can add multiple instances if you have multiple Zendesk accounts. That’s why we allow you to customize the source’s nickname and schema name!

  4. Enter your Zendesk subdomain. The subdomain you use to access your Zendesk portal (e.g. ‘segment’ for segment.zendesk.com)

    Note If you enter ‘segment.zendesk.com’ as a subdomain instead of just ‘segment’, we will be trying to access host ‘segment.zendesk.com.zendesk.com’ and you will get a credentials error.

  5. When you click Authorize, you’ll be dropped into Zendesk’s OAuth flow. Once you sign in and grant permissions, you’ll be good to go! Make sure the user has Admin authorizations as we use the incremental export API from Zendesk, which requires Admin access.

Rate Limits

The Zendesk source uses both Zendesk’s Core API and Incremental Exports API. The source’s requests to the Incremental API do not count towards your Zendesk account’s rate limits, but requests to the Core API do. By default, we cap our requests to Zendesk’s Core API to a rate of 200 requests per minute to avoid triggering Zendesk’s Rate Limits. If you’d like us to increase or decrease the request rate for your source, please let us know, and we’ll get it set up. We’ll add support for this in the UI soon!

Components

Sync

The Zendesk source is built with a sync component, which means we’ll make requests to their API on your behalf on a 3 hour interval to pull the latest data into Segment. In the initial sync, we’ll grab all the Zendesk objects (and their corresponding properties) according to the Collections Table below. The objects will be written into a separate schema, corresponding to the source instance’s schema name you designated upon creation (ie. zendesk_prod.users).

Our sync component uses an upsert API, so the data in your warehouse loaded via sync will reflect the latest state of the corresponding resource in Zendesk. For example, if ticket_status goes from open to closed between syncs, on its next sync that tickets status will be closed.

The source syncs and warehouse syncs are independent processes. Source runs pull your data into the Segment Hub, and warehouse runs flush that data to your warehouse. Sources will sync with Segment every 3 hours. Depending on your Warehouses plan, we will push the Source data to your warehouse on the interval associated with your billing plan.

At the moment, we don’t support filtering which objects or properties get synced. If you’re interested in this feature, please let us know!

Collections

Collections are the groupings of resources we pull from your source.

CollectionTypeDescription
usersobjectZendesk Support has three types of users: end-users (your customers), agents, and administrators. End-users request support through tickets. 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 have all the abilities of agents, plus administrative abilities.
groupsobjectWhen support requests arrive in Zendesk, they can be assigned to a Group. Groups serve as the core element of 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.
ticketsobjectTickets are the means through which your End-users (customers) communicate with Agents in Zendesk. Note: We pull all tickets updated (or created) in the last year to start by default. If you need more, just let us know and we’ll do a run to pull further back in history.
ticket_fieldsobjectCustomize fields on the ticket form.
activitiesobjectThe activity stream is a per agent event stream. It will give access to the most recent events that relate to the agent polling the API.
attachmentsobjectThis API is for attachments in tickets and forum posts in the Web portal.
organizationsobjectJust as agents can be segmented into groups in Zendesk, your customers (end-users) can be segmented into organizations.
ticket_eventseventsReturns a stream of changes that occurred on tickets. Each event is tied to an update on a ticket and contains all the fields that were updated in that change. Note: We pull 1 year of ticket events to start by default. If you need more, just let us know and we’ll do a run to pull further back in history.
ticket_metricsobjectAll kinds of aggregate metrics about a ticket
satisfaction_ratingsobjectIf you have enabled satisfaction ratings for your account, this end point allows you to quickly retrieve all ratings.
ticket_commentsobjectTicket comments represent the conversation between requesters, collaborators, and agents. It includes the full body of each comment, public and private. Note: This collection is not included by default. To request it, contact us.

In your warehouse, each collection gets its own table. Find below a list of the properties we automatically fetch for each collection. Note this list will not include your custom fields!

groups

idAutomatically assigned when creating groups.
urlThe API url of this group.
deletedDeleted groups get marked as such.
nameThe name of the group.
created_atThe time the group was created.
updated_atThe time of the last update of the group.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.

users


idutomatically assigned when the user is created.
urlWe set the “url” field users see in their Warehouse to equal the “id” from Zendesk, rather than the “url” field.
nameThe name of the user.
emailThe primary email address of this user..
time_zoneThe time-zone of this user.
phoneThe primary phone number of this user.
locale_idThe language identifier for this user.
localeThe locale for this user.
organization_idThe id of the organization this user is associated with.
roleThe role of the user. Possible values: “end-user”, “agent”, “admin”.
verifiedThe user’s primary identity is verified or not.
external_idA unique identifier from another system. The API treats the id as case insensitive. Example: ian1 and Ian1 are the same user.
aliasAn alias displayed to end users.
activefalse if the user has been deleted.
sharedIf the user is shared from a different Zendesk Support instance. Ticket sharing accounts only.
shared_agentIf the user is a shared agent from a different Zendesk Support instance. Ticket sharing accounts only.
last_login_atThe last time the user signed in to Zendesk Support.
two_factor_auth_enabledIf two factor authentication is enabled.
signatureThe user’s signature. Only agents and admins can have signatures.
detailsAny details you want to store about the user, such as an address.
notesAny notes you want to store about the user.
custom_role_idA custom role if the user is an agent on the Enterprise plan.
moderatorDesignates whether the user has forum moderation capabilities.
ticket_restrictionSpecifies which tickets the user has access to. Possible values are: “organization”, “groups”, “assigned”, “requested”, null.
only_private_commentstrue if the user can only create private comments.
restricted_agentIf the agent has any restrictions; false for admins and unrestricted agents, true for other agents.
suspendedIf the agent is suspended. Tickets from suspended users are also suspended, and these users cannot sign in to the end user portal.
chat_onlyWhether or not the user is a chat-only agent.
created_atThe time the user was created.
suspendedThe time of the last update of the user.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.

tickets

idAutomatically assigned when the ticket is created.
urlThe API url of this ticket.
external_idAn id you can use to link Zendesk Support tickets to local records.
typeThe type of this ticket. Possible values: “problem”, “incident”, “question” or “task”.
subjectThe value of the subject field for this ticket.
raw_subjectThe dynamic content placeholder, if present, or the “subject” value, if not.
descriptionThe first comment on the ticket.
priorityThe urgency with which the ticket should be addressed. Possible values: “urgent”, “high”, “normal”, “low”.
statusThe state of the ticket. Possible values: “new”, “open”, “pending”, “hold”, “solved”, “closed”.
recipientThe original recipient e-mail address of the ticket.
requester_idThe user who requested this ticket.
submitter_idThe user who submitted the ticket. The submitter always becomes the author of the first comment on the ticket.
assignee_idThe agent currently assigned to the ticket.
organization_idThe organization of the requester. You can only specify the ID of an organization associated with the requestert.
group_idThe group this ticket is assigned to.
collaborator_idsThe ids of users currently cc’ed on the ticket.
forum_topic_idThe topic this ticket originated from, if any.
problem_idFor tickets of type “incident”, the ID of the problem the incident is linked to.
has_incidentsIs true of this ticket has been marked as a problem, false otherwise.
due_atIf this is a ticket of type “task” it has a due date. Due date format uses ISO 8601 format.
tagsThe array of tags applied to this ticket.
sharing_agreement_idsThe ids of the sharing agreements used for this ticket.
created_atWhen this record was created.
updated_atWhen this record last got updated.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.

ticket_fields

idAutomatically assigned upon creation.
urlThe URL for this resource.
typeThe type of the ticket field: “checkbox”, “date”, “decimal”, “integer”, “regexp”, “tagger”, “text”, or “textarea”. *Type is not editable once created.
slugThe title of the ticket field separated by _.
titleThe title of the ticket field.
raw_titleThe dynamic content placeholder, if present, or the “title” value, if not.
descriptionThe description of the purpose of this ticket field, shown to users.
raw_descriptionThe dynamic content placeholder, if present, or the “description” value, if not.
positionA relative position for the ticket fields that determines the order of ticket fields on a ticket. Note that positions 0 to 7 are reserved for system fields.
activeWhether this field is available.
requiredIf it’s required for this field to have a value when updated by agents.
collapsed_for_agentsIf this field should be shown to agents by default or be hidden alongside infrequently used fields. Classic interface only.
regexp_for_validationRegular expression field only. The validation pattern for a field value to be deemed valid..
title_in_portalThe title of the ticket field when shown to end users.
raw_title_in_portalThe dynamic content placeholder, if present, or the “title_in_portal” value, if not.
visible_in_portalWhether this field is available to end users.
editable_in_portalWhether this field is editable by end users.
required_in_portalIf it’s required for this field to have a value when updated by end users.
tagA tag value to set for checkbox fields when checked.
removableIf this field is not a system basic field that must be present for all tickets on the account.
created_atThe time the ticket field was created.
updated_atThe time of the last update of the ticket field.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.

ticket_metrics

idAutomatically assigned.
ticket_idId of the associated ticket.
group_stationsNumber of groups this ticket passed through.
assignee_stationsNumber of assignees this ticket had.
reopensTotal number of times the ticket was reopened.
repliesTotal number of times ticket was replied to.
reply_time_in_minutes_calendarNumber of minutes to the first reply outside of business hours.
reply_time_in_minutes_businessNumber of minutes to the first reply during business hours.
first_resolution_time_in_minutes_calendarNumber of minutes to the first resolution time outside of business hours.
first_resolution_time_in_minutes_businessNumber of minutes to the first resolution time during business hours.
full_resolution_time_in_minutes_calendarNumber of minutes to the full resolution outside of business hours.
full_resolution_time_in_minutes_businessNumber of minutes to the full resolution during business hours.
agent_wait_time_in_minutes_calendarNumber of minutes the agent spent waiting outside of business hours.
agent_wait_time_in_minutes_businessNumber of minutes the agent spent waiting during business hours.
requester_wait_time_in_minutes_calendarNumber of minutes the requester spent waiting during business hours.
requester_wait_time_in_minutes_businessNumber of minutes the requester spent waiting outside of business hours.
on_hold_time_in_minutes_calendarNumber of minutes the ticket was on hold during business hours.
on_hold_time_in_minutes_businessNumber of minutes the ticket was on hold outside of business hours.
created_atWhen this record was created.
updated_atWhen this record last got updated.
assignee_updated_atWhen the assignee last updated the ticket.
requester_updated_atWhen the requester last updated the ticket.
status_updated_atWhen the status was last updated.
initially_assigned_atWhen the ticket was initially assigned.
assigned_atWhen the ticket was last assigned.
solved_atWhen the ticket was solved.
latest_comment_added_atWhen the latest comment was added.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.

ticket_events

idAutomatically assigned.
ticket_event_idAutomatically assigned when the ticket is updated.
ticket_idId of the associated ticket.
timestampTime when the ticket was updated.
updater_idId of the user who updated the ticket.
ticket_event_viaHow the event was created.
context_clientRefers to the “client” used to submit this ticket change (i.e. browser name and type).
context_locationPlain text name of where the request was made, if available (i.e. country, city).
context_latitudeLatitude of the location where the ticket was changed.
context_longitudeLongitude of the location where the ticket was changed.
viaHow the event was created.
via_reference_id

activities

idAutomatically assigned upon creation.
urlThe API url of this activity.
verbThe type of activity. Can be tickets.assignment, tickets.comment, or tickets.priority_increase.
titleDescription of this activity.
created_atWhen this record was created.
updated_atWhen this record last got updated.

attachments

idAutomatically assigned upon creation.
file_nameThe name of the image file.
content_urlA full URL where the attachment image file can be downloaded.
content_typeThe content type of the image. Example value: image/png.
inlineIf true, the attachment is excluded from the attachment list and the attachment’s URL can be referenced within the comment of a ticket. Default is false.
sizeThe size of the image file in bytes.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.

organizations

idAutomatically assigned when the organization is created.
external_idA unique external id to associate organizations to an external record.
urlThe API url of this organization.
nameA unique name for the organization.
detailsAny details obout the organization, such as the address.
notesAny notes you have about the organization.
group_idNew tickets from users in this organization are automatically put in this group.
shared_ticketsEnd users in this organization are able to see each other’s tickets.
shared_commentsEnd users in this organization are able to see each other’s comments on tickets.
created_atThe time the organization was created.
updated_atThe time of the last update of the organization.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.

satisfaction_ratings

idAutomatically assigned when the organization is created.
urlThe API url of this rating.
assignee_idThe id of agent assigned to at the time of rating.
group_idThe id of group assigned to at the time of rating.
requester_idThe id of ticket requester submitting the rating.
ticket_idThe id of ticket being rated.
scoreThe rating: “offered”, “unoffered”, “good” or “bad”.
created_atThe time the satisfaction rating got created.
updated_atThe time the satisfaction rating got updated.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.

ticket_comments

idAutomatically assigned when the comment is created.
ticket_event_idAutomatically assigned when the comment is created.
ticket_idThe id of ticket being commented.
typeComment or VoiceComment. The JSON object for voice comments is different.
bodyThe comment string.
publictrue 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.
author_idThe id of the comment author.
viaHow the comment was created.
created_atThe time the comment was created.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.

Adding Destinations

Currently only Warehouses are supported for object-cloud sources


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!