Skip to main content

Zendesk Support

This page contains the setup guide and reference information for the Zendesk Support source connector.

Prerequisites​

  • A Zendesk account with an Administrator role.
  • The unique Zendesk subdomain associated with the account.

Setup guide​

Set up Zendesk Support​

The Zendesk Support source connector supports three authentication methods:

  • OAuth 2.0 with refresh token (recommended for Calabi Connect)
  • API token (recommended for Calabi Connect)
  • OAuth 2.0 Legacy (for existing OAuth connections that haven't migrated to the refresh token flow)
note

Zendesk is enforcing OAuth token expiration and requiring the refresh token flow. If you use the legacy OAuth method, plan to migrate to OAuth 2.0 with refresh token before Zendesk's deadline.

For Calabi Connect:

We highly recommend using OAuth to authenticate your Zendesk Support account, as it simplifies the setup process and allows you to authenticate directly from the Calabi Connect UI.

For Calabi Connect:

We recommend using an API token to authenticate your Zendesk Support account. Please follow the steps below to generate this key.

note

If you prefer to authenticate with OAuth for Calabi Connect, you can follow the steps laid out in this Zendesk article to obtain your client ID, client secret and access token. Please ensure you set the scope to read when generating the access token.

Generate an API token​

  1. Log in to your Zendesk account.

  2. Click the Zendesk Products icon (four squares) in the top-right corner, then select Admin Center.

  3. In the left navbar, click Apps and Integrations, then select APIs > Zendesk API.

  4. In the Settings tab, toggle the option to enable token access.

  5. Click the Add API token button. You may optionally provide a token description.

    caution

    Be sure to copy the token and save it in a secure location. You will not be able to access the token's value after you close the page.

  6. Click Save.

Set up the Zendesk Support connector in Calabi Connect​

For Calabi Connect:​

  1. Log into your Calabi Connect account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Zendesk Support from the Source type dropdown.
  4. Enter a name for the Zendesk Support connector.

For Calabi Connect:​

  1. Navigate to the Calabi Connect dashboard.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Zendesk Support from the Source type dropdown.
  4. Enter a name for the Zendesk Support connector.
  1. You can use OAuth or an API token to authenticate your Zendesk Support account.
  • For Calabi Connect: To authenticate using OAuth, select OAuth 2.0 with Refresh Token from the Authentication dropdown, then click Authenticate your Zendesk Support account to sign in with Zendesk Support and authorize your account.
  • For Calabi Connect: To authenticate using an API key, select API Token from the Authentication dropdown and enter the API token you generated, as well as the email address associated with your Zendesk Support account.
  1. For Subdomain, enter your Zendesk subdomain. This is the subdomain found in your account URL. For example, if your account URL is https://MY_SUBDOMAIN.zendesk.com/, then MY_SUBDOMAIN is your subdomain.
  2. (Optional) For Start Date, use the provided datepicker or enter a UTC date and time programmatically in the format YYYY-MM-DDTHH:mm:ssZ. The data added on and after this date will be replicated. If this field is left blank, Calabi Connect will replicate the data for the last two years by default.
  3. (Optional) For Number of concurrent threads, enter the number of parallel threads to use for the sync. The default is 3. Increase this value if your Zendesk plan supports higher rate limits. See Rate limiting for details.
  4. (Optional) For Page Size (ticket_comments), enter the number of records per page for the ticket_comments stream. The default is 100 and the maximum is 1000. Lower values may help prevent timeouts on large Zendesk instances.
  5. Click Set up source and wait for the tests to complete.

Supported sync modes​

The Zendesk Support source connector supports the following sync modes:

  • Full Refresh | Overwrite
  • Full Refresh | Append
  • Incremental Sync | Append
  • Incremental Sync | Deduped History
note

There are two types of incremental sync:

  1. Incremental (standard server-side, where the API returns only data updated or created since the last sync).
  2. Client-Side Incremental (the API returns all available data, and the connector filters out only new records).

Supported Streams​

The Zendesk Support source connector supports the following streams:

Deleted Records Support​

The Zendesk Support connector fetches deleted records in the following streams:

StreamDeletion indicator field
Brandsis_deleted
Deleted TicketsAll records are deleted
Groupsdeleted
Organizationsdeleted_at
Ticket Metric Eventsdeleted
note

As of version 5.2.0, the tickets stream no longer includes deleted tickets. Use the deleted_tickets stream instead. See the migration guide for details.

Limitations & Troubleshooting​

Expand to see details about Zendesk Support connector limitations and troubleshooting.

Connector limitations​

Rate limiting​

Zendesk applies rate limits based on your plan tier:

PlanRequests per minute
Team200
Growth / Professional400
Enterprise700
Enterprise Plus / High Volume API add-on2500

The connector's Number of concurrent threads setting (default: 3) controls how many streams sync in parallel. If your plan supports higher rate limits, increase this value for faster syncs. The maximum is 40.

Zendesk's incremental export endpoints have a stricter rate limit of 10 requests per minute, regardless of plan tier. This applies to the ticket_comments, ticket_metric_events, users, and organizations streams that use incremental exports. The tickets stream uses the Export Search Results endpoint, which has a separate rate limit of 100 requests per minute. The deleted_tickets stream has a rate limit of 10 requests per minute. The connector includes a built-in API budget that automatically throttles requests to stay within these limits.

If the connector receives a 429 (Too Many Requests) response, it respects the Retry-After header and waits before retrying. The ticket_comments stream also retries on 504 (Gateway Timeout) errors with exponential backoff, which can occur on large Zendesk instances.

The connector should not run into Zendesk API limitations under normal usage. Create an issue if you see any rate limit issues that are not automatically retried successfully.

Search index delay​

The tickets stream uses Zendesk's Export Search Results endpoint. Zendesk's search index can take up to a few minutes to reflect newly created or updated tickets. During incremental syncs, this delay does not cause data loss because the connector's cursor ensures that records are picked up on the next sync.

Troubleshooting​

  • Check out common troubleshooting issues for the Zendesk Support source connector on our Calabi Connect Forum.