ContextQMD
Back to Airbyte

Zendesk Support

docs/integrations/sources/zendesk-support.md

2.0.063.4 KB
Original Source

Zendesk Support

<HideInUI>

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

</HideInUI>

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 Airbyte Cloud)
  • API token (recommended for Airbyte Open Source)
  • 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. :::

<!-- env:cloud -->

For Airbyte Cloud:

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 Airbyte UI.

<!-- /env:cloud --> <!-- env:oss -->

For Airbyte Open Source:

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 Airbyte Open Source, 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.

<!-- /env:oss -->

Set up the Zendesk Support connector in Airbyte

<!-- env:cloud -->

For Airbyte Cloud:

  1. Log into your Airbyte Cloud 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. <!-- /env:cloud --> <!-- env:oss -->

For Airbyte Open Source:

  1. Navigate to the Airbyte Open Source 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.
<!-- /env:oss -->
  1. You can use OAuth or an API token to authenticate your Zendesk Support account.
<!-- env:cloud -->
  • For Airbyte Cloud: 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. <!-- /env:cloud --> <!-- env:oss -->
  • For Airbyte Open Source: 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.
<!-- /env:oss -->
  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, Airbyte will replicate the data for the last two years by default.
  3. (Optional) For Number of concurrent workers, 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.
<!-- /env:oss --> <HideInUI>

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

<details> <summary> Expand to see details about Zendesk Support connector limitations and troubleshooting. </summary>

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 workers 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 Airbyte Forum.
</details>

Changelog

<details> <summary>Expand to review</summary>
VersionDatePull RequestSubject
5.2.12026-03-1774394Migrate to scopes object array format
5.2.02026-03-1274258Switch tickets stream to Export Search Results endpoint for concurrency and performance. Behavior change: deleted tickets are no longer returned in the tickets stream — use the new deleted_tickets stream instead. Added deleted_tickets as a suggested stream for auto-enablement on Cloud.
5.1.82026-03-1274771Upgrade CDK to 7.13.0
5.1.72026-03-1274766Promoting release candidate 5.1.7-rc.1 to a main version.
5.1.7-rc.12026-03-1074398Pin CDK to 7.8.1.post54 for regression testing of StateDelegatingStream and DeclarativeStream
5.1.62026-03-0973686Add 504 exponential backoff error handling to ticket_comments stream and API budget (10 req/min) for all incremental export streams
5.1.52026-02-2567077Add missing SLA fields (sla, group_sla, status, deleted) to ticket_metric_events schema
5.1.42026-02-2473911Update dependencies
5.1.32026-02-1773508Update dependencies
5.1.22026-02-1072624Update dependencies
5.1.12026-02-0372783Upgrade CDK version to 7.8.1
5.1.02026-02-0271752Add user-configurable page_size option for ticket_comments stream
5.0.32026-01-2872423Update breaking change deadline from Jan 31 to Jan 30
5.0.22026-01-2772380Fix OAuth race condition with concurrent token refresh
5.0.12026-01-2271714Update dependencies
5.0.02026-01-2270990Add OAuth2.0 with refresh token support. Users using OAuth must re-authenticate to use the new flow with rotating refresh tokens.
4.10.182025-12-1870717Update dependencies
4.10.172025-12-0270066Update dependencies
4.10.162025-11-1869538Update dependencies
4.10.152025-10-2968945Update dependencies
4.10.142025-10-2168408Update dependencies
4.10.132025-10-1468019Update dependencies
4.10.122025-10-0766850Update dependencies
4.10.112025-09-2466461Update dependencies
4.10.102025-09-0965729Update dependencies
4.10.92025-08-2665558Update dependencies
4.10.82025-08-2465403Update dependencies
4.10.72025-08-1064867Update dependencies
4.10.62025-08-0264366Update dependencies
4.10.52025-07-2664067Update dependencies
4.10.42025-07-2063673Update dependencies
4.10.32025-07-1263238Update dependencies
4.10.22025-07-0562691Update dependencies
4.10.12025-06-2860736Update dependencies
4.10.02025-06-2662099Promoting release candidate 4.10.0-rc.1 to a main version.
4.10.0-rc.12025-06-1761599Migrate to manifest-only format.
4.9.12025-05-1060014Update dependencies
4.9.02025-05-0556419Adapt file-transfer records to latest protocol, requires platform >= 1.7.0, destination-s3 >= 1.8.0
4.8.72025-05-0459531Update dependencies
4.8.62025-04-2658917Update dependencies
4.8.52025-04-1958547Update dependencies
4.8.42025-04-1358042Update dependencies
4.8.32025-04-0557389Update dependencies
4.8.22025-03-2955157Update dependencies
4.8.12025-03-2556405Fix empty child state migration issue
4.8.02025-03-2556354Migrate posts to low-code
4.7.22025-03-1155676Prepare posts stream for low-code migration
4.7.12025-02-2654696Update requests-mock dependency versionb
4.7.02025-02-2454656Promoting release candidate 4.7.0-rc.1 to a main version.
4.7.0-rc.12025-02-1353620Replace ZendeskSupportAuditLogsIncrementalSync with low-code DatetimeBasedCursor
4.6.02024-12-0947939Add User Identities stream
4.5.02024-12-0248761Add Categories and Sections stream
4.4.42025-02-0851943Update dependencies
4.4.32025-02-0352625Update error message during check for organization_access_enabled
4.4.22025-01-1148309Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
4.4.12024-12-1348889Check if start_date exist in check operation
4.4.02024-11-1148379Make DatetimeBasedCursor syncs concurrent
4.3.32024-10-2847663Update dependencies
4.3.22024-10-2147202Update dependencies and expected records
4.3.12024-10-1246794Update dependencies
4.3.02024-10-0946096Updates TicketMetrics stream for improved reliability for long syncs, updates state cursor field to _ab_updated_at, automatically migrates legacy state
4.2.32024-10-0546408Update dependencies
4.2.22024-09-2845784Update dependencies
4.2.12024-09-1445561Update dependencies
4.2.02024-09-1044610Add Automations and Triggers stream
4.1.12024-09-0745215Update dependencies
4.1.02024-09-0645187Migrate to CDK v5
4.0.22024-08-3144965Update dependencies
4.0.12024-08-2444692Update dependencies
4.0.02024-08-1944096Stream Tags: use cursor based pagination
3.0.12024-08-1744324Update dependencies
3.0.02024-08-1343446TicketMetrics stream: updates cursor field to generated_timestamp
2.7.32024-08-1243900Update dependencies
2.7.22024-08-1043614Update dependencies
2.7.12024-08-0341799Update dependencies
2.7.02024-08-0242975Migrate to CDK v4.3.0
2.6.132024-07-3142892Update BackoffStrategy interface to be up-to-date with latest parent interface.
2.6.122024-07-2542519Update error message for permission issue.
2.6.112024-07-1842100Raise config error on 403/404 status code.
2.6.102024-07-1041436Fix unit test
2.6.92024-07-1041390Update dependencies
2.6.82024-07-0940025Update dependencies
2.6.72024-07-0941032Use latest CDK: 3.0.0
2.6.62024-06-2740592Updated to use latest CDK version, fixed cursor pagination logic
2.6.52024-05-2338607Migrate to cursor based pagination in stream Organization memberships
2.6.42024-05-2038310Fix record filter for Ticket Metrics stream
2.6.32024-05-0236669Schema descriptions
2.6.22024-02-0537761Add stop condition for Ticket Audits when recieved old records; Ignore 403 and 404 status codes.
2.6.12024-04-3037723Add %Y-%m-%dT%H:%M:%S%z to cursor_datetime_formats
2.6.02024-04-2936823Migrate to low code; Add new stream Ticket Activities
2.5.02024-04-2536388Fix data type of field in Tickets stream schema stream.
2.4.12024-04-2037450Fix parsing response for Ticket Metrics stream.
2.4.02024-04-0936897Fix long-running syncs for Ticket Metrics, Ticket Audits and Satisfaction Ratings streams.
2.3.02024-03-2636403Unpin CDK version, add record counts to state messages
2.2.82024-02-0935083Manage dependencies with Poetry.
2.2.72024-02-0534840Fix missing fields in schema
2.2.62024-01-1134064Skip 504 Error for stream Ticket Audits
2.2.52024-01-0834010Prepare for airbyte-lib
2.2.42023-12-2033680Fix pagination issue for streams related to incremental export sync
2.2.32023-12-1433435Fix 504 Error for stream Ticket Audits
2.2.22023-12-0133012Increase number of retries for backoff policy to 10
2.2.12023-11-1032440Made refactoring to improve code maintainability
2.2.02023-10-3131999Extended the CustomRoles stream schema
2.1.12023-10-2331702Base image migration: remove Dockerfile and use the python-connector-base image
2.1.02023-10-1931606Added new field reply_time_in_seconds to the Ticket Metrics stream schema
2.0.02023-09-1530440Remove stream Deleted Tickets
1.7.02023-09-1130259Add stream Deleted Tickets
1.6.02023-09-0930168Make start_date field optional
1.5.12023-09-0530142Handle non-JSON Response
1.5.02023-09-0430138Add new Streams: Article Votes, Article Comments, Article Comment Votes
1.4.02023-09-0430134Add incremental support for streams: custom Roles, Schedules, SLA Policies
1.3.02023-08-3030031Add new streams: Articles, Organization Fields
1.2.22023-08-3029998Fix typo in stream AttributeDefinitions: field condition
1.2.12023-08-3029991Remove Custom availability strategy
1.2.02023-08-2929940Add undeclared fields to schemas
1.1.12023-08-2929904Make Organizations stream incremental
1.1.02023-08-2829891Add stream UserFields
1.0.02023-07-2728774Fix retry logic & update cursor for Tickets stream
0.11.02023-08-1027208Add stream Topics
0.10.72023-08-0929256Update tooltip descriptions in spec
0.10.62023-08-0429031Reverted advancedAuth spec changes
0.10.52023-08-0128910Updated advancedAuth broken references
0.10.42023-07-2528397Handle 404 Error
0.10.32023-07-2428612Fix pagination for stream TicketMetricEvents
0.10.22023-07-1928487Remove extra page from params
0.10.12023-07-1028096Replace offset pagination with cursor pagination
0.10.02023-07-0627991Add streams: PostVotes, PostCommentVotes
0.9.02023-07-0527961Add stream: Post Comments
0.8.12023-06-2727765Bugfix: Nonetype error while syncing more then 100000 organizations
0.8.02023-06-0927156Add stream Posts
0.7.02023-06-2727436Add Ticket Skips stream
0.6.02023-06-2727450Add Skill Based Routing streams
0.5.02023-06-2627735License Update: Elv2 stream stream
0.4.02023-06-1627431Add Organization Memberships stream
0.3.12023-06-0226945Make Ticket Metrics stream to use cursor pagination
0.3.02023-05-2326347Add stream Audit Logs logs`
0.2.302023-05-2326414Added missing handlers when empty json or JSONDecodeError is received
0.2.292023-04-1825214Add missing fields to Tickets stream
0.2.282023-03-2124053Fix stream sla_policies schema data type error (events.value)
0.2.272023-03-2222817Specified date formatting in specification
0.2.262023-03-2024252Handle invalid start_date when checking connection
0.2.252023-02-2822308Add AvailabilityStrategy for all streams
0.2.242023-02-1723246Handle StartTimeTooRecent error for Tickets stream
0.2.232023-02-1523035Handle 403 Error
0.2.222023-02-1422483Fix test; handle 400 error
0.2.212023-01-2722027Set AvailabilityStrategy for streams explicitly to None
0.2.202022-12-2820900Remove synchronous time.sleep, add logging, reduce backoff time
0.2.192022-12-0919967Fix reading response for more than 100k records
0.2.182022-11-2919432Revert changes from version 0.2.15, use a test read instead
0.2.172022-11-2419792Transform ticket_comments.via "-" to null
0.2.162022-09-2817326Migrate to per-stream states.
0.2.152022-08-0315233Added subscription plan check on streams discovery step to remove streams that are not accessible for fetch due to subscription plan restrictions
0.2.142022-07-2715036Convert ticket_audits.previous_value values to string
0.2.132022-07-2114829Convert tickets.custom_fields values to string
0.2.122022-06-3014304Fixed Pagination for Group Membership stream
0.2.112022-06-2414112Fixed "Retry-After" non integer value
0.2.102022-06-1413757Fixed the bug with TicketMetrics stream, HTTP Error 429, caused by lots of API requests
0.2.92022-05-2713261Bugfix for the unhandled ChunkedEncodingError and ConnectionError
0.2.82022-05-2013055Fixed minor issue for stream ticket_audits schema
0.2.72022-04-2712335Adding fixtures to mock time.sleep for connectors that explicitly sleep
0.2.62022-04-1912122Fixed the bug when only 100,000 Users are synced 11895 and fixed bug when start_date is not used on user stream 12059.
0.2.52022-04-0511727Fixed the bug when state was not parsed correctly
0.2.42022-04-0411688Small documentation corrections
0.2.32022-03-2311349Fixed the bug when Tickets stream didn't return deleted records
0.2.22022-03-1711237Fixed the bug when TicketComments stream didn't return all records
0.2.12022-03-1511162Added support of OAuth2.0 authentication method
0.2.02022-03-019456Update source to use future requests
0.1.122022-01-259785Add additional log messages
0.1.112021-12-218987Update connector fields title/description
0.1.92021-12-168616Adds Brands, CustomRoles and Schedules streams
0.1.82021-11-238168Adds TicketMetricEvents stream
0.1.72021-11-238058Added support of AccessToken authentication
0.1.62021-11-188050Fix wrong types for schemas, add TypeTransformer
0.1.52021-10-267679Add ticket_id and ticket_comments
0.1.42021-10-267377Fix initially_assigned_at type in ticket metrics
0.1.32021-10-177097Corrected the connector's specification
0.1.22021-10-166513Fixed TicketComments stream
0.1.12021-09-025787Fixed incremental logic for the ticket_comments stream
0.1.02021-07-214861Created CDK native zendesk connector
</details> </HideInUI>