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

# Zendesk

> Connect Zendesk to Serval for full Support API access in workflows, two-way help desk ticket sync, and Zendesk Guide knowledge sync.

## About Zendesk

Zendesk is a customer-service platform for support ticketing and self-service knowledge. Serval connects to a single Zendesk instance and, through one connection, covers both Zendesk Support (tickets, comments, users, organizations, custom statuses) and Zendesk Guide (Help Center categories, sections, and articles). Zendesk is registered in Serval as both a ticket source and a knowledge source.

**Authentication:** API token - the email address of a Zendesk agent or admin plus an API token, sent together as HTTP Basic auth. There is no OAuth flow and no scopes: everything Serval can do is bounded by that user's role in Zendesk.

**Data sync:** Workflow API calls run on demand. Ticket sync is a two-way background sync - Serval checks connected channels for new and updated tickets every 30 seconds and pushes Serval-side changes (new tickets, comments, status, priority, and field updates, including custom statuses) back to Zendesk. Zendesk Guide knowledge sync discovers all Help Center categories, sections, and articles, then ingests article content per item - newly discovered items start out excluded from sync, so you opt in exactly the content you want indexed.

## What the Zendesk integration enables

| Capability                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Full Zendesk Support API access        | A typed API action covering 424 Zendesk Support endpoints, generated from [Zendesk's official OpenAPI specification](https://developer.zendesk.com/zendesk/oas.yaml) - tickets, users, organizations, ticket fields, custom statuses, automations, custom objects, brands, audit logs, and more. Rate-limited requests are retried automatically.                                                                                                                                    |
| Two-way ticket sync                    | Use Zendesk as a Serval help desk channel. Serval pulls tickets and comments in the background (with an incremental sync for channels configured to capture historical and new tickets, and a bulk backfill if a channel falls more than 48 hours behind) and writes Serval-side ticket creates, updates, and comments back to Zendesk. Priorities map between systems (Zendesk urgent/high/normal/low ↔ Serval urgent/high/medium/low; Serval "none" is written to Zendesk as low). |
| Zendesk Guide knowledge sync           | Syncs Help Center categories, sections, and articles into Serval's knowledge base, preserving the category → section → article hierarchy. Each item has an include-in-sync setting, and newly discovered items start out excluded, so you scope exactly which Guide content Serval indexes.                                                                                                                                                                                          |
| Shipped workflow: List Zendesk Tickets | A pre-installed workflow (runs without approval by default) that lists all tickets with cursor pagination and optional filters: an external ID, and a support-type scope of all, agent, or ai\_agent (defaults to agent).                                                                                                                                                                                                                                                            |
| Help Center article link recognition   | Paste a Zendesk Help Center article link in Serval and it resolves to the matching synced article automatically.                                                                                                                                                                                                                                                                                                                                                                     |

Anything defined in the [Zendesk API](https://developer.zendesk.com/api-reference/) can be accessed through Serval.

## Get your credentials

You need two things: the email address of the Zendesk agent or admin Serval should act as, and a Zendesk API token. Zendesk API tokens are account-level - they authenticate in combination with a verified user's email address, and Serval's access mirrors that user's role. You must be a Zendesk administrator to create tokens, and API token access must be turned on for your account. See [Zendesk's API token guide](https://support.zendesk.com/hc/en-us/articles/4408889192858) and the [security and authentication overview](https://developer.zendesk.com/api-reference/introduction/security-and-auth/) for full details.

<Steps>
  <Step title="Open the API tokens page">
    In Zendesk Admin Center, click **Apps and integrations** in the sidebar, then select **APIs → API tokens**.
  </Step>

  <Step title="Turn on token access">
    If API token access is not already enabled for your account, enable it from this page.
  </Step>

  <Step title="Create the token">
    Click **Add API token** and add a description, e.g. "Serval Integration".
  </Step>

  <Step title="Save and copy the token">
    Click **Save** to generate the token, then copy it immediately - Zendesk shows the full token only once.
  </Step>
</Steps>

<Warning>
  Zendesk displays the API token only once, at creation time. Copy it before closing the window - Serval never displays it again either (it is shown obfuscated, with only the last 4 characters visible).
</Warning>

<Note>
  Serval's access exactly mirrors the connecting user's Zendesk role. For two-way ticket sync and Guide knowledge sync, use an admin or an agent whose permissions cover reading and updating tickets and reading the Help Center.
</Note>

## Connect in Serval

Open the Zendesk integration in Serval and fill in the connect form.

<Steps>
  <Step title="Instance Name (optional)">
    A friendly name for this Zendesk integration instance (e.g., "Production Zendesk"); if empty, we will use the domain. When set, the connection displays as "Name (domain)".
  </Step>

  <Step title="Domain">
    Your Zendesk domain (e.g., company.zendesk.com). Enter the canonical `.zendesk.com` address - host-mapped or vanity domains will not authenticate.
  </Step>

  <Step title="Email Address">
    Email address of a Zendesk admin or agent - the account whose permissions Serval will use.
  </Step>

  <Step title="API Token">
    The API token generated in Zendesk Admin Center. This is a password field.
  </Step>

  <Step title="Submit">
    Save the connection. If saving fails, the error begins with "Failed to install integration" (first-time connect) or "Failed to update integration" (editing an existing connection), followed by details when available.
  </Step>
</Steps>

<Note>
  None of the fields are marked required and there is no inline format checking - the form will submit even with missing or mistyped values. Mistakes are caught afterward by the health checks (see below).
</Note>

When you edit an existing connection, the form opens pre-filled with your saved settings: Instance Name, Domain, and Email Address show their stored values, and the API Token appears masked with only the last 4 characters visible. The masked token is ignored when you save, so the stored secret is preserved unless you paste in a new one - and if you clear the Domain or Instance Name, the stored value is kept too. Serval only replaces the stored credential when a real (unmasked) API token is submitted together with an email address: to rotate the token, paste the new token over the masked value and save; to switch the connecting account, change the Email Address **and** re-enter the API token in the same save. Changing the email alone is silently ignored - no error, no change.

## Verifying the connection

Serval runs four health checks against your Zendesk connection.

**Test Zendesk Connection** - confirms the domain, email, and token work by fetching the connected user's profile.

* Success: "Successfully authenticated with Zendesk as \[name]"
* Failure: "Unable to authenticate with Zendesk. Please verify your API credentials (email and API token) are correct."

**List Zendesk Tickets** - confirms the account can list tickets (a small sample of ticket fields is recorded for diagnostics).

* Success: "Successfully listed tickets from Zendesk (sample size: \[number])"
* Failure: "Unable to list tickets from Zendesk. Please verify your API credentials have permission to read tickets. This is required for the integration to function."

**List Zendesk Organizations** - confirms the account can list organizations.

* Success: "Successfully listed organizations from Zendesk (sample size: \[number])"
* Failure: "Unable to list organizations from Zendesk. Please verify your API credentials have permission to read organizations."

**List Zendesk Knowledge Articles** - confirms the account can read Zendesk Guide knowledge base articles.

* Success: "Successfully listed knowledge articles from Zendesk Guide (sample size: \[number])"
* Failure: "Unable to list knowledge articles from Zendesk Guide. Please verify your API credentials have permission to read the knowledge base, or that Zendesk Guide is enabled for your account."

<Tip>
  If the first three checks pass but **List Zendesk Knowledge Articles** fails, the most likely cause is that Zendesk Guide is not enabled for your account, or the connecting user cannot read the Help Center. Ticket features continue to work - only knowledge sync is affected.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Changing the email address alone does nothing">
    Serval only rebuilds the stored credential when a real (unmasked) API token is submitted alongside an email address. The edit form pre-fills your current email, so rotating the token is easy: paste the new token over the masked value and save. But if you change only the Email Address and leave the masked token in place, the save is silently ignored - no error appears and the old email/token pair stays in effect. To switch the connecting account, always re-enter the API token together with the new email, then re-run the health checks.
  </Accordion>

  <Accordion title="No inline form validation - mistakes surface as health-check failures">
    None of the four connect-form fields are required and there are no format checks, so the form saves even with missing or malformed values. If something is wrong, the health checks will tell you - start with **Test Zendesk Connection**, which validates the domain, email, and token together.
  </Accordion>

  <Accordion title="Domain must be a real .zendesk.com domain">
    Serval only sends credentials to `*.zendesk.com` addresses, and all traffic is routed to the subdomain derived from your configured Domain. Host-mapped or vanity Help Center domains will not authenticate - always enter the canonical `company.zendesk.com` form.
  </Accordion>

  <Accordion title="Permissions mirror the connecting Zendesk user">
    There are no OAuth scopes. Everything Serval can read or write is bounded by the role of the agent or admin whose email and token you supplied. Writing tickets back to Zendesk (creates, updates, custom statuses, ticket fields) and syncing Guide knowledge each require the corresponding Zendesk permissions on that account.
  </Accordion>

  <Accordion title="Zendesk Guide must be enabled for knowledge features">
    Knowledge sync and the knowledge-articles health check both read the Help Center. If Guide is not enabled for your account (or the connecting user cannot read it), the ticket checks pass while the knowledge check fails - its failure message calls this out explicitly.
  </Accordion>

  <Accordion title="Knowledge items start excluded from sync">
    When Serval first discovers your Help Center content, every category, section, and article is created with sync turned off. Nothing is indexed until you explicitly include the items you want - so an empty knowledge base right after connecting is expected, not a failure.
  </Accordion>

  <Accordion title="Editing the connection keeps existing values">
    The edit form opens pre-filled, and clearing a field does not wipe anything: a cleared Domain keeps the existing domain, a cleared Instance Name keeps the existing display name, and the masked API token is ignored on save so the stored secret is preserved. You never need to re-type the token just to change the display name.
  </Accordion>

  <Accordion title="Zendesk shows the API token only once">
    Copy the token when you create it in the Zendesk Admin Center. Serval never displays it again either - reads show it obfuscated, with only the last 4 characters visible. If the token is lost, create a new one in Zendesk and paste it into the API Token field in Serval.
  </Accordion>

  <Accordion title="Rate limits are handled automatically">
    When Zendesk rate-limits a request, Serval retries automatically - waiting the time Zendesk specifies, or backing off progressively when no wait time is given. Very high-volume workflows can still exhaust your instance's limit; workflows that fetch large amounts of data should use [cursor pagination](https://developer.zendesk.com/api-reference/introduction/pagination/) to minimize the number of calls.
  </Accordion>

  <Accordion title="Help Center reads sit outside the typed action surface">
    The typed API action covers the 424 Zendesk Support endpoints from Zendesk's official specification; Zendesk Guide (Help Center) endpoints are not part of that typed list. Guide content is still fully reachable - the built-in health check and the knowledge sync use it directly, and custom workflow calls to Guide work through the same authenticated connection, just without typed assistance.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Zendesk integration.