Zendesk Guide is the knowledge base of Zendesk: the Help Center where companies publish articles, organized in categories and sections, for their customers and agents. The connector reads the Help Center of every brand of your Zendesk account in a single source: its articles (with their HTML body, translations and helpful/not helpful votes), sections, categories and enabled languages. Every row says which brand it came from, so you can analyze the content of all your Help Centers together in your Lakehouse.

This page covers the Help Center. For tickets, users and organizations, use the Zendesk Support connector.

Configuring Zendesk Guide as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Zendesk Guide option from the list of connectors. Click Next and you’ll be prompted to add your access.

1. Add account access

The connector authenticates with a Zendesk API token and the email of the user it belongs to. To create a token, go to Admin Center → Apps and integrations → APIs → Zendesk API, open the Settings tab, enable Token access and click Add API token. See Zendesk’s API token documentation for details. The same token reads the Help Center of every brand of the account: you don’t need one token per brand.

Use the email of a Zendesk admin. The connector reads what that user can see: agents only see the brands they belong to, and only admins see the Help Center address of each brand (needed to filter Brands by address).

The following configurations are available:

API Token: the Zendesk API token. Required.
User email: the email of the Zendesk user the token belongs to. Required.
Company subdomain: the main subdomain of your Zendesk account, taken from https://{subdomain}.zendesk.com. The brands of the account are discovered from it. Required.
Brands: optional. Leave it empty to sync every brand that has an active Help Center. To sync only some brands, add one entry per brand, using its Help Center address (for example help.example.com; a full URL of the Help Center also works), its Zendesk subdomain or its brand ID. You can use this to split your brands across several sources.

An entry of Brands that matches no brand of the account is ignored and reported in the run log. If no entry matches any brand, the run fails before reading anything, so that a typo never empties your tables.

Once you’re done, click Next.

2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

Tip: The stream can be found more easily by typing its name.

The connector always lists the brands and their languages to know which Help Centers to read, even when you don’t select the Brands and Locales streams. Select the streams and click Next.

3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
Sync Type: every stream is FULL_TABLE: each sync replaces the table with what your Help Centers currently hold, so deleted articles also leave the table. Read more about Sync Types here.

Once you are done configuring, click Next.

4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can define some additional settings:

Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.

Once you are ready, click Next to finalize the setup.

5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

For you to be able to see it on your Catalog, you need at least one successful source run.

Streams and Fields

Below you’ll find all available data streams from Zendesk Guide and their corresponding fields. API reference: Zendesk Help Center API.

Zendesk serves each brand’s Help Center separately, so the connector reads every brand on its own and adds brand_id and brand_name to each row. Categories, sections and articles have one row per item and language: an article translated into two languages appears twice, with the same id and a different locale. The Help Center has its own request limit in Zendesk, separate from Zendesk Support, so this source does not slow down your ticket extractions.

Brands

The brands of your Zendesk account, with the state of each brand’s Help Center. When Brands is filled, only the listed brands.Table: brands · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the brand.
`name`	String	Name of the brand.
`subdomain`	String	Zendesk subdomain of the brand (`{subdomain}.zendesk.com`).
`host_mapping`	String	Custom address of the brand’s Help Center, if any (visible to admins only).
`brand_url`	String	URL of the brand.
`has_help_center`	Boolean	Whether the brand has a Help Center.
`help_center_state`	String	State of the brand’s Help Center: `enabled`, `disabled` or `restricted`.
`active`	Boolean	Whether the brand is active.
`default`	Boolean	Whether this is the default brand of the account.
`is_deleted`	Boolean	Whether the brand was deleted.
`signature_template`	String	Signature template used in the brand’s emails.
`ticket_form_ids`	Array	Identifiers of the ticket forms available to the brand.
`url`	String	API URL of the brand.
`created_at`	Datetime	When the brand was created.
`updated_at`	Datetime	When the brand was last updated.

Locales

The languages enabled on each brand’s Help Center. The connector reads categories, sections and articles in each of them.Table: locales · Primary key: brand_id, locale · Sync: Full table

Field	Type	Description
`brand_id`	Integer	Identifier of the brand that owns the Help Center.
`brand_name`	String	Name of the brand that owns the Help Center.
`locale`	String	Language enabled on the Help Center (for example `pt-br`).
`is_default`	Boolean	Whether this is the Help Center’s default language.

Categories

The categories of each Help Center, the top level of its organization. One row per category and language.Table: categories · Primary key: id, locale · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the category.
`brand_id`	Integer	Identifier of the brand whose Help Center holds the category.
`brand_name`	String	Name of the brand whose Help Center holds the category.
`name`	String	Name of the category in this language.
`description`	String	Description of the category in this language.
`locale`	String	Language the category is displayed in.
`source_locale`	String	Language the category was originally created in.
`outdated`	Boolean	Whether the category is out of date (deprecated by Zendesk).
`position`	Integer	Position of the category when listing categories.
`html_url`	String	URL of the category in the Help Center.
`url`	String	API URL of the category.
`created_at`	Datetime	When the category was created.
`updated_at`	Datetime	When the category was last updated.

Sections

The sections of each Help Center, which group articles inside a category (and can be nested in other sections). One row per section and language.Table: sections · Primary key: id, locale · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the section.
`brand_id`	Integer	Identifier of the brand whose Help Center holds the section.
`brand_name`	String	Name of the brand whose Help Center holds the section.
`category_id`	Integer	Identifier of the category the section belongs to.
`parent_section_id`	Integer	Identifier of the parent section, when the section is nested in another one.
`name`	String	Name of the section in this language.
`description`	String	Description of the section in this language.
`locale`	String	Language the section is displayed in.
`source_locale`	String	Language the section was originally created in.
`outdated`	Boolean	Whether the section is out of date (deprecated by Zendesk).
`position`	Integer	Position of the section when listing sections.
`theme_template`	String	Theme template used to display the section.
`html_url`	String	URL of the section in the Help Center.
`url`	String	API URL of the section.
`created_at`	Datetime	When the section was created.
`updated_at`	Datetime	When the section was last updated.

Articles

The articles of each Help Center, with their HTML body, one row per article and language. Besides what Zendesk sends, the connector adds the article’s category and splits its votes into helpful and not helpful.Table: articles · Primary key: id, locale · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the article.
`brand_id`	Integer	Identifier of the brand whose Help Center holds the article.
`brand_name`	String	Name of the brand whose Help Center holds the article.
`title`	String	Title of the article in this language.
`name`	String	Name of the article in this language (same as the title).
`body`	String	HTML body of the article in this language.
`locale`	String	Language the article is displayed in.
`source_locale`	String	Language the article was originally created in.
`section_id`	Integer	Identifier of the section the article belongs to.
`category_id`	Integer	Identifier of the category of the article’s section (added by Nekt).
`author_id`	Integer	Identifier of the user who wrote the article.
`draft`	Boolean	Whether the article is a draft in this language.
`promoted`	Boolean	Whether the article is promoted (featured).
`position`	Integer	Position of the article within its section.
`comments_disabled`	Boolean	Whether comments are disabled on the article.
`vote_sum`	Integer	Net votes: helpful votes minus not helpful votes.
`vote_count`	Integer	Total number of votes on the article.
`helpful_votes`	Integer	Number of “helpful” votes (added by Nekt from `vote_sum` and `vote_count`).
`not_helpful_votes`	Integer	Number of “not helpful” votes (added by Nekt from `vote_sum` and `vote_count`).
`label_names`	Array	Labels attached to the article.
`content_tag_ids`	Array	Identifiers of the content tags attached to the article.
`user_segment_id`	Integer	Identifier of the user segment that can view the article (empty means everyone).
`user_segment_ids`	Array	Identifiers of the user segments that can view the article.
`permission_group_id`	Integer	Identifier of the permission group that defines who can edit and publish the article.
`outdated`	Boolean	Whether the article is out of date (deprecated by Zendesk).
`outdated_locales`	Array	Languages whose translation is marked as out of date.
`html_url`	String	URL of the article in the Help Center.
`url`	String	API URL of the article.
`created_at`	Datetime	When the article was created.
`updated_at`	Datetime	When the article was last updated.
`edited_at`	Datetime	When the article’s content was last edited in this language.

Get started

Context

Activate

Workspace

Resources

Zendesk Guide as a data source

Configuring Zendesk Guide as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

​Configuring Zendesk Guide as a Source

​1. Add account access

​2. Select streams

​3. Configure data streams

​4. Configure data source

​5. Check your new source

​Streams and Fields

Configuring Zendesk Guide as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields