> ## 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 as a data source

> Bring data from Zendesk to Nekt.

Zendesk is a customer service and support platform that helps businesses provide excellent customer experiences. It provides tools for ticket management, customer communication, knowledge base creation, and support analytics to improve customer satisfaction and support operations.

## Configuring Zendesk 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 option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

Authenticate Nekt against your Zendesk Support account using an API token. See [Zendesk API token authentication](https://developer.zendesk.com/api-reference/introduction/security-and-auth/#api-token) for how to create a token.

The following configurations are available:

* **API Token:** The token used to authenticate against the Zendesk Support API.

* **User email:** The email of the Zendesk user associated with the token.

* **Company subdomain:** The subdomain of your Zendesk Support URL, `https://{subdomain}.zendesk.com`. See [Zendesk endpoint conventions](https://developer.zendesk.com/api-reference/introduction/doc-conventions/#endpoints).

* **Start Date:** The earliest date and time from which incremental streams should begin on the first sync (combined with saved state on later runs).

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.

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**: you can choose between INCREMENTAL and FULL\_TABLE.
  * Incremental: every time the extraction happens, we'll get only the new data - which is good if, for example, you want to keep every record ever fetched.
  * Full table: every time the extraction happens, we'll get the current state of the data - which is good if, for example, you don't want to have deleted data in your catalog.

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/runs/scheduling-and-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).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

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 and their corresponding fields:

<AccordionGroup>
  <Accordion title="Tickets">
    Stream for support tickets: status, routing, requester and assignee, custom fields, tags, satisfaction, and channel metadata. Incremental sync uses the cursor-based ticket export and `generated_timestamp`.

    **Key Fields:**

    * `id` - Unique identifier for the ticket
    * `generated_timestamp` - Unix timestamp used for incremental cursor sync
    * `status`, `priority`, `type` - Workflow fields
    * `custom_status_id` - Custom ticket status when enabled
    * `subject`, `raw_subject`, `description` - Subject and first public comment body
    * `external_id`, `encoded_id` - External system and encoded identifiers

    **People and routing:**

    * `requester_id`, `submitter_id`, `assignee_id` - User identifiers
    * `organization_id`, `group_id` - Organization and group
    * `collaborator_ids`, `follower_ids`, `email_cc_ids` - Collaboration
    * `sharing_agreement_ids` - Sharing agreements on the ticket

    **Custom and system fields:**

    * `custom_fields` - Array of `{ id, value }` for custom fields (values stored as serialized strings)
    * `fields` - All field id/value pairs from the API (values stored as serialized strings)

    **Scheduling and metadata:**

    * `due_at` - Due date and time
    * `satisfaction_rating` - Nested `comment`, `id`, `score`
    * `tags` - Ticket tags
    * `ticket_form_id`, `brand_id`, `forum_topic_id` - Form, brand, and legacy forum link
    * `is_public`, `allow_channelback`, `allow_attachments` - Channel behavior
    * `from_messaging_channel` - Whether the ticket originated from messaging
    * `has_incidents`, `problem_id`, `followup_ids` - Problem and incident links

    **Timestamps and API:**

    * `created_at`, `updated_at` - Record timestamps
    * `url` - API URL of the ticket resource

    **Via (channel):**

    * `via.channel`, `via.source` - How the ticket was created (`from`, `to`, `rel`, addresses, subject, related ids)
  </Accordion>

  <Accordion title="Ticket Metrics">
    Stream for per-ticket operational metrics from the Ticket Metrics API. Join to **Tickets** on `ticket_id`.

    **Key Fields:**

    * `id` - Unique identifier for the metrics row
    * `ticket_id` - Related ticket

    **Assignment and activity:**

    * `assigned_at`, `initially_assigned_at`, `assignee_updated_at` - Assignment timeline
    * `assignee_stations`, `group_stations` - Count of assignee or group changes
    * `latest_comment_added_at`, `requester_updated_at`, `status_updated_at`, `custom_status_updated_at` - Activity timestamps

    **Resolution and engagement:**

    * `first_resolution_time_in_minutes`, `full_resolution_time_in_minutes`, `on_hold_time_in_minutes`, `agent_wait_time_in_minutes`, `requester_wait_time_in_minutes`, `reply_time_in_minutes` - Objects with `business` and/or `calendar` minute counts
    * `reply_time_in_seconds` - Object with `calendar` seconds where applicable
    * `reopens`, `replies` - Counts
    * `solved_at` - When the ticket reached solved

    **Metadata:**

    * `created_at`, `updated_at`, `url`
  </Accordion>

  <Accordion title="Ticket Fields">
    Stream for ticket field definitions (system and custom), including options and linked custom statuses.

    **Key Fields:**

    * `id`, `type`, `title`, `raw_title`, `key` - Identity and field type
    * `active`, `required`, `removable`, `position` - Behavior and sort order
    * `description`, `raw_description`, `agent_description` - Help text
    * `regexp_for_validation` - Input validation pattern

    **Portal:**

    * `visible_in_portal`, `editable_in_portal`, `required_in_portal`, `title_in_portal`, `raw_title_in_portal`, `collapsed_for_agents`

    **Options and statuses:**

    * `system_field_options` - Array of `{ name, value }`
    * `custom_field_options` - Array of `{ id, name, raw_name, value, default }`
    * `custom_statuses` - Custom status definitions when linked (`id`, labels, `status_category`, `active`, `default`, timestamps, `url`)

    **Other:**

    * `sub_type_id`, `tag`
    * `created_at`, `updated_at`, `url`
  </Accordion>

  <Accordion title="Users">
    Stream for agents and end users. Incremental sync uses the cursor-based user export on `updated_at`.

    **Key Fields:**

    * `id` - Unique identifier for the user
    * `name`, `email`, `phone`, `alias`
    * `external_id`, `active`, `suspended`, `verified`
    * `organization_id`, `default_group_id`, `role`, `role_type`, `custom_role_id`

    **Locale and profile:**

    * `locale`, `locale_id`, `time_zone`, `iana_time_zone`
    * `details`, `notes`, `signature`, `tags`
    * `photo` - Attachment metadata (`url`, `id`, `file_name`, `content_url`, size, dimensions, `thumbnails`, etc.)

    **Access and security:**

    * `moderator`, `ticket_restriction`, `restricted_agent`, `only_private_comments`
    * `shared`, `shared_agent`, `shared_phone_number`
    * `two_factor_auth_enabled`, `last_login_at`, `report_csv`

    **Custom fields:**

    * `user_fields` - Array of `{ key, value }` (values serialized as strings)

    **Metadata:**

    * `created_at`, `updated_at`, `url`
  </Accordion>

  <Accordion title="Organizations">
    Stream for customer organizations. Incremental sync uses the incremental organizations API on `updated_at`.

    **Key Fields:**

    * `id`, `name`, `details`, `notes`
    * `external_id`, `domain_names`, `tags`
    * `group_id` - Associated group
    * `shared_tickets`, `shared_comments` - Visibility flags

    **Lifecycle:**

    * `created_at`, `updated_at`, `deleted_at`

    **Custom fields:**

    * `organization_fields` - Array of `{ key, value }` (values serialized as strings)

    **Metadata:**

    * `url`
  </Accordion>

  <Accordion title="Organization Fields">
    Stream for organization custom field definitions.

    **Key Fields:**

    * `id`, `key`, `type`, `title`, `raw_title`
    * `active`, `system`, `position`
    * `description`, `raw_description`, `regexp_for_validation`
    * `system_field_options`, `custom_field_options` - Same shapes as **Ticket Fields** where applicable
    * `created_at`, `updated_at`, `url`
  </Accordion>

  <Accordion title="User Fields">
    Stream for user custom field definitions.

    **Key Fields:**

    * `id`, `key`, `type`, `title`, `raw_title`
    * `active`, `system`, `position`
    * `description`, `raw_description`, `regexp_for_validation`
    * `created_at`, `updated_at`, `url`
  </Accordion>
</AccordionGroup>

# Data Model

The following diagram illustrates the relationships between the core data streams in Zendesk. The arrows indicate the join keys that link the different entities, providing a clear overview of the data structure.

```mermaid theme={null}
graph TD;
    subgraph "Core Entities"
        Tickets("Tickets");
        Users("Users");
        Organizations("Organizations");
    end

    subgraph "Metrics and Definitions"
        TicketMetrics("Ticket Metrics");
        TicketFields("Ticket Fields");
        UserFields("User Fields");
        OrganizationFields("Organization Fields");
    end

    Tickets -- "requester_id / assignee_id / submitter_id" --> Users;
    Tickets -- "organization_id" --> Organizations;
    Users -- "organization_id" --> Organizations;
    TicketMetrics -- "ticket_id" --> Tickets;
    Tickets -- "custom_fields[].id" --> TicketFields;
    Users -- "user_fields[].key" --> UserFields;
    Organizations -- "organization_fields[].key" --> OrganizationFields;
```

# Use Cases for Data Analysis

This guide outlines valuable business intelligence use cases when consolidating Zendesk data, along with ready-to-use SQL queries that you can run on [Explorer](https://app.nekt.ai/explorer).

### 1. Ticket Detail and Resolution Metrics

Join tickets to ticket metrics to analyze resolution time, replies, and reopens.

**Business Value:**

* Track full and first resolution time by priority or group
* Identify tickets with high reopen counts
* Combine with **Users** and **Organizations** for owner- or account-level views

<Accordion title="SQL query">
  <Tabs>
    <Tab title="AWS">
      ```sql theme={null}
      SELECT
         t.id AS ticket_id,
         t.subject,
         t.status,
         t.priority,
         t.organization_id,
         m.full_resolution_time_in_minutes.calendar AS full_resolution_calendar_mins,
         m.first_resolution_time_in_minutes.calendar AS first_resolution_calendar_mins,
         m.replies,
         m.reopens,
         m.solved_at
      FROM
         nekt_raw.zendesk_tickets t
         LEFT JOIN nekt_raw.zendesk_ticket_metrics m
            ON t.id = m.ticket_id
      WHERE
         t.updated_at >= CURRENT_TIMESTAMP - INTERVAL '30' DAY
      ORDER BY
         t.updated_at DESC
      ```
    </Tab>

    <Tab title="GCP">
      ```sql theme={null}
      SELECT
         t.id AS ticket_id,
         t.subject,
         t.status,
         t.priority,
         t.organization_id,
         m.full_resolution_time_in_minutes.calendar AS full_resolution_calendar_mins,
         m.first_resolution_time_in_minutes.calendar AS first_resolution_calendar_mins,
         m.replies,
         m.reopens,
         m.solved_at
      FROM
         `nekt_raw.zendesk_tickets` t
         LEFT JOIN `nekt_raw.zendesk_ticket_metrics` m
            ON t.id = m.ticket_id
      WHERE
         t.updated_at >= TIMESTAMP_SUB (CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
      ORDER BY
         t.updated_at DESC
      ```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="Sample Result">
  | ticket\_id | subject          | status | priority | organization\_id | full\_resolution\_calendar\_mins | first\_resolution\_calendar\_mins | replies | reopens | solved\_at          |
  | ---------: | ---------------- | ------ | -------- | ---------------: | -------------------------------: | --------------------------------: | ------: | ------: | ------------------- |
  |      10042 | Billing question | solved | normal   |              501 |                              180 |                                45 |       4 |       0 | 2024-11-20 14:22:00 |
  |      10041 | Login failure    | open   | urgent   |              502 |                             NULL |                              NULL |       1 |       0 | NULL                |
  |      10040 | Refund request   | solved | high     |              501 |                             1440 |                               120 |       6 |       1 | 2024-11-19 09:05:00 |
</Accordion>

### 2. Ticket Volume by Organization

Aggregate recent ticket activity by organization for account health and workload reporting.

**Business Value:**

* Compare ticket volume across customers
* Spot organizations with rising open priority or urgent tickets
* Prioritize CSM or support outreach

<Accordion title="SQL query">
  <Tabs>
    <Tab title="AWS">
      ```sql theme={null}
      SELECT
         o.id AS organization_id,
         o.name AS organization_name,
         COUNT(*) AS ticket_count,
         SUM(CASE WHEN t.status IN ('new', 'open', 'pending', 'hold') THEN 1 ELSE 0 END) AS open_ticket_count,
         SUM(CASE WHEN t.priority = 'urgent' THEN 1 ELSE 0 END) AS urgent_ticket_count
      FROM
         nekt_raw.zendesk_tickets t
         INNER JOIN nekt_raw.zendesk_organizations o ON t.organization_id = o.id
      WHERE
         t.updated_at >= CURRENT_TIMESTAMP - INTERVAL '30' DAY
      GROUP BY
         o.id,
         o.name
      ORDER BY
         ticket_count DESC
      ```
    </Tab>

    <Tab title="GCP">
      ```sql theme={null}
      SELECT
         o.id AS organization_id,
         o.name AS organization_name,
         COUNT(*) AS ticket_count,
         SUM(
            CASE WHEN t.status IN ('new', 'open', 'pending', 'hold') THEN 1 ELSE 0 END
         ) AS open_ticket_count,
         SUM(CASE WHEN t.priority = 'urgent' THEN 1 ELSE 0 END) AS urgent_ticket_count
      FROM
         `nekt_raw.zendesk_tickets` t
         INNER JOIN `nekt_raw.zendesk_organizations` o ON t.organization_id = o.id
      WHERE
         t.updated_at >= TIMESTAMP_SUB (CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
      GROUP BY
         o.id,
         o.name
      ORDER BY
         ticket_count DESC
      ```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="Sample Result">
  | organization\_id | organization\_name | ticket\_count | open\_ticket\_count | urgent\_ticket\_count |
  | ---------------: | ------------------ | ------------: | ------------------: | --------------------: |
  |              501 | Acme Corp          |           128 |                  22 |                     3 |
  |              502 | Northwind          |            94 |                  18 |                     1 |
  |              503 | Contoso            |            61 |                   9 |                     0 |
</Accordion>

This analysis helps you:

* Prioritize accounts with the highest recent volume or urgent load
* Balance team workload across segments
* Follow up when open or urgent counts trend upward

You can extend these patterns with **Users** (assignee or requester) and **Ticket Fields** to decode custom field ids in `custom_fields`.

## Implementation Notes

### Data Quality Considerations

* Custom field payloads (`custom_fields`, `fields`, `user_fields`, `organization_fields`) may arrive as serialized strings in the lake; parse as JSON when needed for typing
* For trend reporting on tickets, ensure **Start Date** and triggers cover the window you analyze (for example, at least 30 days)
* Join **Ticket Metrics** to **Tickets** for SLA-style metrics; metrics rows are keyed by `ticket_id`

### API Limits & Performance

* Zendesk returns HTTP 429 when rate limits are reached; the connector retries with backoff using response headers when available
* Selecting only the streams you need reduces extraction time and API usage
* Incremental streams (**Tickets**, **Users**, **Organizations**) advance from **Start Date** on first sync, then from saved replication state

## Skills for agents

<Snippet file="agent-skills-intro.mdx" />

<Card title="Download Zendesk skills file" icon="wand-magic-sparkles" href="/sources/zendesk.md">
  Zendesk connector documentation as plain markdown, for use in AI agent contexts.
</Card>