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

# Zendesk Integration Guide

> Connect Zendesk to sync support tickets into Hearflow for product-feedback extraction.

Sync Zendesk support tickets so customer issues, requests, and themes flow into Hearflow alongside other feedback signals.

## Prerequisites

* A Zendesk account on a paid plan with API access enabled
* Permission to authorize Zendesk through OAuth
* Your Zendesk subdomain (for example, `acme` from `acme.zendesk.com`). Subdomains follow Zendesk's published spec: lowercase letters, digits, and hyphens, 1–63 characters, must start and end with an alphanumeric character.

## Connect Zendesk

<Steps>
  <Step title="Open Hearflow integrations">
    Go to [Settings → Integrations](/settings) and select Zendesk.
  </Step>

  <Step title="Enter your subdomain">
    Provide your Zendesk subdomain. Hearflow validates it before continuing.
  </Step>

  <Step title="Authorize access">
    Complete the OAuth consent flow to grant Hearflow per-subdomain access.
  </Step>

  <Step title="Confirm initial backfill">
    Hearflow queues a 90-day backfill of historical tickets immediately after setup.
  </Step>
</Steps>

## Authentication

**OAuth 2.0** — The only supported authentication method for new connections. Hearflow authorizes per-subdomain access and refreshes tokens automatically. Credentials are encrypted at rest.

<Warning>
  **API token authentication is deprecated.** In line with Zendesk's August 2025 marketplace policy, third-party apps may no longer authenticate with a customer's API token. New connections must use OAuth — the API-token endpoint now returns `403 Forbidden`.

  Existing API-token integrations continue to sync during a 30-day grace window. A deprecation banner appears in the dashboard with a Reconnect action; reconnect via OAuth before the grace window ends to avoid sync interruption.
</Warning>

## How sync works

**Ticket ingestion** — Public ticket comments are synthesized into transcript-like records and fed through the standard extraction and deduplication pipeline. Internal notes are excluded.

**Initial backfill** — A 90-day backfill of historical tickets runs immediately after the integration is connected.

**Ongoing sync** — A scheduled task polls active Zendesk integrations at 04:00 UTC. Cadence depends on your plan: Starter polls once a week on your workspace's configured sync day; Pro and Enterprise poll daily. See [Workspace Settings → Sync controls](/settings#sync-controls) to choose your weekly sync day.

**Filters** — Tag and group filters (`zendesk_include_tags`, `zendesk_exclude_tags`, `zendesk_include_group_ids`) are honoured by the sync task when configured.

## Reliability

* OAuth tokens refresh automatically before expiry. Zendesk rotates the refresh token on every successful refresh; if a new refresh token is not returned, Hearflow flags the integration for re-authentication rather than reusing an invalidated token.
* Rate-limit (429) and transient server (5xx) errors are retried with exponential backoff.
* Invalid subdomains are surfaced before the OAuth redirect.
* Credential failures mark the integration as errored and prompt re-authentication.

<Note>
  **Data access** — Hearflow reads only public ticket comments from authorized Zendesk subdomains and stores credentials encrypted at rest. Internal notes are never ingested.
</Note>