Zendesk Source

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. When you click Connect, you’ll be dropped into Zendesk’s OAuth flow. Once you sign in and grant permissions, you’ll be good to go!

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

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!

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!

Collections

Collections are the groupings of resources we pull from your source. In your warehouse, each collection gets its own table.

For a complete visual breakdown of the Zendesk collections, all their properties, and ID linkages between objects, view the visual schema here or download it in PDF form here.

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

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!