> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zendesk Guide as a data source

> Bring your Zendesk Help Center articles, from every brand, to your Lakehouse.

<img height="50" src="https://mintcdn.com/nekt/7mEKNLLgCLNOIMcj/assets/logo/logo-zendesk-support.png?fit=max&auto=format&n=7mEKNLLgCLNOIMcj&q=85&s=6dccc1d3df5b3244a764686e17be15e5" data-path="assets/logo/logo-zendesk-support.png" />

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.

<Note>
  This page covers the Help Center. For tickets, users and organizations, use the [Zendesk Support](https://docs.nekt.com/sources/zendesk) connector.
</Note>

## Configuring Zendesk Guide as a Source

In the [Sources](https://app.nekt.ai/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](https://developer.zendesk.com/api-reference/introduction/security-and-auth/#api-token) for details.

The same token reads the Help Center of every brand of the account: you don't need one token per brand.

<Note>
  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).
</Note>

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.

<Note>
  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.
</Note>

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](https://docs.nekt.com/get-started/core-concepts/types-of-sync).

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](https://docs.nekt.com/get-started/core-concepts/triggers), 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](https://docs.nekt.com/get-started/core-concepts/resource-control).

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

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

<Warning>For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.</Warning>

# Streams and Fields

Below you'll find all available data streams from Zendesk Guide and their corresponding fields. API reference: [Zendesk Help Center API](https://developer.zendesk.com/api-reference/help_center/help-center-api/introduction/).

<Note>
  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.
</Note>

<AccordionGroup>
  <Accordion title="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. |
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="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. |
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.