Pipeloom Docs
ConnectorsSources

Zendesk Support

Set up the Zendesk Support source connector.

Sync modes, namespaces and the columns Pipeloom adds are explained once in Connector concepts; workspace variables and custom components in Orchestration.

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

Prerequisites

  • A Zendesk account. An Administrator role is recommended for full access to all streams. Non-admin accounts can still sync, but streams that require admin permissions are automatically skipped.
  • 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 Pipeloom)
  • API token (recommended for Pipeloom)
  • OAuth 2.0 Legacy (for existing OAuth connections that haven't migrated to the refresh token flow)

:::note Zendesk requires the refresh token flow for all customers as of April 30, 2026. Legacy OAuth access tokens don't expire and can't be refreshed, so migrate existing connections to OAuth 2.0 with Refresh Token. :::

For Pipeloom:

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, see Generate OAuth credentials. :::

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.

Generate OAuth credentials

Pipeloom runs the OAuth flow for you. On self-managed Pipeloom, you create the credentials yourself and enter a client ID, client secret, and refresh token.

  1. Register an OAuth client in Admin Center. See Registering your application with Zendesk. Note the client's unique identifier and secret.
  2. Complete Zendesk's authorization code flow with the read scope, and include expires_in in the token request. Zendesk only issues a refresh token when the access token expires, and clients created before April 30, 2026 have no default expiration, so a request without expires_in returns a token you can't refresh. The maximum value is 172800 (48 hours), which is what the connector requests in Pipeloom.
  3. Save the refresh_token from the response.

When you configure the source, select OAuth2.0 with Refresh Token and enter the client ID, client secret, and refresh token. Leave Access Token and Token Expiry Date empty. The connector exchanges the refresh token for an access token on its first request, then writes the new access token, refresh token, and expiry back to the source configuration.

:::caution Zendesk refresh tokens are single-use. Every refresh returns a new refresh token and invalidates the previous one, so a refresh token can only be used by one source. Don't copy the same value into a second source or a second Pipeloom deployment. :::

Set up the Zendesk Support connector in Pipeloom

For Pipeloom:

  1. Navigate to the Pipeloom 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.

  5. You can use OAuth or an API token to authenticate your Zendesk Support account.

  • For Pipeloom: 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. To authenticate using OAuth instead, select OAuth2.0 with Refresh Token and enter the client ID, client secret, and refresh token you generated.
  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, Pipeloom 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 4 and the minimum is 2. 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. (Optional) For Tickets Search Lookback Window (days), enter the number of days the tickets_search stream re-scans on each sync. The default is 0. This setting only affects the opt-in tickets_search stream. See Tickets stream: change tracking.
  6. 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 Between versions 5.2.0 and 5.4.x, the tickets stream did not include deleted tickets. As of version 5.5.0 the tickets stream again includes deleted tickets (see below). The deleted_tickets stream remains available and should be paired with the opt-in tickets_search stream, which does not return deleted tickets. :::

Tickets stream: change tracking

The tickets stream uses Zendesk's Incremental Ticket Export endpoint, which tracks changes by generated_timestamp. Zendesk bumps generated_timestamp on every ticket change, including automation-, macro-, and system-driven updates (e.g. auto-solve batches), so the stream reliably re-syncs every update.

:::warning Versions 5.2.0–5.4.x used the Export Search Results endpoint and tracked changes by updated_at. Because Zendesk only updates updated_at (and re-indexes the ticket for search) when a change generates a ticket event, automation/macro/system-driven updates were both silently dropped from incremental syncs and returned with stale field values (e.g. status) on historical reads, since search/export is served from Zendesk's search index rather than the live record. This was fixed in 5.5.0 by reverting the tickets stream to generated_timestamp. On upgrade, a one-time state migration automatically backfills records missed or left stale since 2026-03-01 — no manual reset is required. See the migration guide. :::

The former Export Search Results behavior is preserved as the tickets_search stream. It offers higher throughput (100 req/min vs the incremental endpoint's 10 req/min, plus 30-day time-range partitions that sync concurrently) and a configurable Tickets Search Lookback Window (days) setting, but it shares the 5.2.0–5.4.x limitations: it can miss automation/macro/system-driven updates in incremental mode and can return stale statuses on historical reads. Use tickets_search only when throughput matters more than completeness, and pair it with the deleted_tickets stream (Export Search excludes deleted tickets).

tickets_search isn't enabled by default. To use it, enable it on your connection's Schema tab. Enabling both tickets and tickets_search syncs the same tickets twice, so most people should enable only one of them.

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: 4) controls how many streams sync in parallel. If your plan supports higher rate limits, increase this value for faster syncs. The minimum is 2 and the maximum is 40. A single thread leaves no other stream emitting while the tickets stream reads, so a saved value of 1 is treated as 2 from the first sync after upgrading to 5.6.0, and the stored configuration is updated to match. If the source settings form flags the field before that first sync, set it to 2 or more.

Zendesk's incremental export endpoints have a stricter rate limit of 10 requests per minute, regardless of plan tier. This applies to the tickets, ticket_comments, ticket_events, ticket_metric_events, users, and organizations streams that use incremental exports. The opt-in tickets_search 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.

Permissions and stream skipping

Some streams require administrator-level permissions in Zendesk (for example, account_attributes, attribute_definitions, audit_logs, and ticket_forms). If the authenticated user does not have access to a stream's endpoint, the connector skips that stream and continues syncing the remaining streams. Skipped streams are logged with a message indicating the permission issue.

To sync all available streams, authenticate with a Zendesk account that has an Administrator role.

Side conversations access

Side conversations are included in Zendesk Suite Professional and above, and are available to Support Professional and above through the Collaboration add-on. You also have to activate side conversations in Admin Center, and on Enterprise plans a custom role can restrict which agents may use them.

Zendesk grants access to side conversations per ticket, so this stream can read some tickets and be refused on others. As of version 5.5.2, the connector logs a message for the ticket, skips it, and keeps syncing the rest of the stream when Zendesk returns:

  • 403, when Zendesk denies access to that ticket's side conversations.
  • 404, when the ticket no longer exists. The tickets stream returns deleted tickets, so this is expected.
  • 422, when the ticket type doesn't support side conversations.

If your account doesn't have side conversations at all, Zendesk refuses every ticket this way, so the stream ends up empty rather than failing.

Versions before 5.5.2 failed the whole sync on a 403 or 404 (the 422 case has been skipped since 5.4.1). Because side_conversations reads its parent tickets incrementally, that failure also stopped the parent cursor from advancing, so every following sync restarted from the same ticket and failed again. Upgrade to 5.5.2 or later if your syncs fail this way.

Search index delay in the tickets_search stream

The opt-in tickets_search stream reads from Zendesk's search index, which can take a few minutes to reflect newly created or updated tickets. Tickets indexed after a sync's cursor has moved past their updated_at value aren't picked up on the next sync. Set Tickets Search Lookback Window (days) to at least 1 to re-scan a trailing window on every sync. The lookback window doesn't recover automation-, macro-, or system-driven updates, because those never change updated_at. The default tickets stream isn't affected: it reads the live ticket record instead of the search index.

Troubleshooting

OAuth authentication fails with invalid_grant

Zendesk invalidates a refresh token as soon as it's used, so authentication fails with invalid_grant whenever the connector holds a token Zendesk has already rotated. Common causes:

  • The same refresh token is configured in more than one source, or in more than one Pipeloom deployment. Generate separate OAuth credentials for each source.
  • The source was configured manually with a refresh token that had already been used.
  • The source was set up on a connector version earlier than 5.5.1. Those versions didn't record the access token's expiry when you authorized the source, so the connector treated the token as expired and refreshed it during the initial connection test, consuming the refresh token that was saved in the configuration.

To recover, upgrade to version 5.5.1 or later, then re-authenticate the source in Pipeloom or replace the refresh token on self-managed Pipeloom.

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

IP allow list

If you use Pipeloom and your organization restricts access to specific IPs, add the Pipeloom IP addresses to your allow list.

Stripe

Set up the Stripe source connector.

Destinations

Destination connector reference.

On this page

PrerequisitesSetup guideSet up Zendesk SupportGenerate an API tokenGenerate OAuth credentialsSet up the Zendesk Support connector in PipeloomFor Pipeloom:Supported sync modesSupported StreamsDeleted Records SupportTickets stream: change trackingLimitations & TroubleshootingConnector limitationsRate limitingPermissions and stream skippingSide conversations accessSearch index delay in the tickets_search streamTroubleshootingOAuth authentication fails with invalid_grantIP allow list