Skip to main content

​
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

CapabilityDescription
Full Zendesk Support API accessA typed API action covering 424 Zendesk Support endpoints, generated from Zendesk’s official OpenAPI specification - tickets, users, organizations, ticket fields, custom statuses, automations, custom objects, brands, audit logs, and more. Rate-limited requests are retried automatically.
Two-way ticket syncUse 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 syncSyncs 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 TicketsA 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 recognitionPaste a Zendesk Help Center article link in Serval and it resolves to the matching synced article automatically.
Anything defined in the Zendesk API 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 and the security and authentication overview for full details.
1

Open the API tokens page

In Zendesk Admin Center, click Apps and integrations in the sidebar, then select APIs → API tokens.
2

Turn on token access

If API token access is not already enabled for your account, enable it from this page.
3

Create the token

Click Add API token and add a description, e.g. “Serval Integration”.
4

Save and copy the token

Click Save to generate the token, then copy it immediately - Zendesk shows the full token only once.
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).
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.

​
Connect in Serval

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

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)”.
2

Domain

Your Zendesk domain (e.g., company.zendesk.com). Enter the canonical .zendesk.com address - host-mapped or vanity domains will not authenticate.
3

Email Address

Email address of a Zendesk admin or agent - the account whose permissions Serval will use.
4

API Token

The API token generated in Zendesk Admin Center. This is a password field.
5

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.
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).
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.”
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.

​
Gotchas and troubleshooting

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.
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.
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.
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.
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.
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.
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.
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.
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 to minimize the number of calls.
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.
Need help? Contact support@serval.com for assistance with your Zendesk integration.