984fdd506f
Co-authored-by: octavia-bot-hoard[bot] <230633153+octavia-bot-hoard[bot]@users.noreply.github.com>
57 KiB
57 KiB
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 two authentication methods:
- OAuth 2.0
- API token
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.
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
-
Log in to your Zendesk account.
-
Click the Zendesk Products icon (four squares) in the top-right corner, then select Admin Center.
-
In the left navbar, click Apps and Integrations, then select APIs > Zendesk API.
-
In the Settings tab, toggle the option to enable token access.
-
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. :::
-
Click Save.
Set up the Zendesk Support connector in Airbyte
For Airbyte Cloud:
- Log into your Airbyte Cloud account.
- Click Sources and then click + New source.
- On the Set up the source page, select Zendesk Support from the Source type dropdown.
- Enter a name for the Zendesk Support connector.
For Airbyte Open Source:
- Navigate to the Airbyte Open Source dashboard.
- Click Sources and then click + New source.
- On the Set up the source page, select Zendesk Support from the Source type dropdown.
- Enter a name for the Zendesk Support connector.
- You can use OAuth or an API token to authenticate your Zendesk Support account.
- For Airbyte Cloud: To authenticate using OAuth, select OAuth 2.0 from the Authentication dropdown, then click Authenticate your Zendesk Support account to sign in with Zendesk Support and authorize your account.
- 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.
- 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/, thenMY_SUBDOMAINis your subdomain. - (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. - 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:
- Incremental (standard server-side, where API returns only the data updated or generated since the last sync).
- Client-Side Incremental (API returns all available data and connector filters out only new records). :::
Supported Streams
The Zendesk Support source connector supports the following streams:
- Account Attributes
- Articles (Incremental)
- Article Votes (Incremental)
- Article Comments (Incremental)
- Article Comment Votes (Incremental)
- Attribute Definitions
- Audit Logs(Incremental) (Only available for enterprise accounts)
- Automations
- Brands
- Custom Roles (Incremental)
- Groups (Incremental)
- Group Memberships (Incremental)
- Macros (Incremental)
- Organizations (Incremental)
- Organization Fields (Incremental)
- Organization Memberships (Incremental)
- Posts (Incremental)
- Post Comments (Incremental)
- Post Comment Votes (Incremental)
- Post Votes (Incremental)
- Satisfaction Ratings (Incremental)
- Schedules (Incremental)
- SLA Policies (Incremental)
- Tags
- Tickets (Incremental)
- Ticket Audits (Client-Side Incremental)
- Ticket Comments (Incremental)
- Ticket Fields (Incremental)
- Ticket Forms (Incremental)
- Ticket Metrics (Incremental)
- Ticket Metric Events (Incremental)
- Topics (Incremental)
- Triggers (Incremental)
- Ticket Skips (Incremental)
- Users (Incremental)
- UserIdentities (Incremental)
- UserFields
- Categories
- Sections
Deleted Records Support
The Zendesk Support connector fetches deleted records in the following streams:
| Stream | Deletion indicator field |
|---|---|
| Brands | is_deleted |
| Groups | deleted |
| Organizations | deleted_at |
| Ticket Metric Events | deleted |
| Tickets | status==deleted |
Limitations & Troubleshooting
Expand to see details about Zendesk Support connector limitations and troubleshooting.
Connector limitations
Rate limiting
The connector is restricted by normal Zendesk requests limitation.
The Zendesk connector ideally 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.
Troubleshooting
- Check out common troubleshooting issues for the Zendesk Support source connector on our Airbyte Forum.
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 4.10.17 | 2025-12-02 | 70066 | Update dependencies |
| 4.10.16 | 2025-11-18 | 69538 | Update dependencies |
| 4.10.15 | 2025-10-29 | 68945 | Update dependencies |
| 4.10.14 | 2025-10-21 | 68408 | Update dependencies |
| 4.10.13 | 2025-10-14 | 68019 | Update dependencies |
| 4.10.12 | 2025-10-07 | 66850 | Update dependencies |
| 4.10.11 | 2025-09-24 | 66461 | Update dependencies |
| 4.10.10 | 2025-09-09 | 65729 | Update dependencies |
| 4.10.9 | 2025-08-26 | 65558 | Update dependencies |
| 4.10.8 | 2025-08-23 | 65403 | Update dependencies |
| 4.10.7 | 2025-08-09 | 64867 | Update dependencies |
| 4.10.6 | 2025-08-02 | 64366 | Update dependencies |
| 4.10.5 | 2025-07-26 | 64067 | Update dependencies |
| 4.10.4 | 2025-07-20 | 63673 | Update dependencies |
| 4.10.3 | 2025-07-12 | 63238 | Update dependencies |
| 4.10.2 | 2025-07-05 | 62691 | Update dependencies |
| 4.10.1 | 2025-06-28 | 60736 | Update dependencies |
| 4.10.0 | 2025-06-26 | 62099 | Promoting release candidate 4.10.0-rc.1 to a main version. |
| 4.10.0-rc.1 | 2025-06-17 | 61599 | Migrate to manifest-only format. |
| 4.9.1 | 2025-05-10 | 60014 | Update dependencies |
| 4.9.0 | 2025-05-05 | 56419 | Adapt file-transfer records to latest protocol, requires platform >= 1.7.0, destination-s3 >= 1.8.0 |
| 4.8.7 | 2025-05-04 | 59531 | Update dependencies |
| 4.8.6 | 2025-04-26 | 58917 | Update dependencies |
| 4.8.5 | 2025-04-19 | 58547 | Update dependencies |
| 4.8.4 | 2025-04-13 | 58042 | Update dependencies |
| 4.8.3 | 2025-04-05 | 57389 | Update dependencies |
| 4.8.2 | 2025-03-29 | 55157 | Update dependencies |
| 4.8.1 | 2025-03-25 | 56405 | Fix empty child state migration issue |
| 4.8.0 | 2025-03-25 | 56354 | Migrate posts to low-code |
| 4.7.2 | 2025-03-11 | 55676 | Prepare posts stream for low-code migration |
| 4.7.1 | 2025-02-26 | 54696 | Update requests-mock dependency versionb |
| 4.7.0 | 2025-02-24 | 54656 | Promoting release candidate 4.7.0-rc.1 to a main version. |
| 4.7.0-rc.1 | 2025-02-13 | 53620 | Replace ZendeskSupportAuditLogsIncrementalSync with low-code DatetimeBasedCursor |
| 4.6.0 | 2024-12-09 | 47939 | Add User Identities stream |
| 4.5.0 | 2024-12-02 | 48761 | Add Categories and Sections stream |
| 4.4.4 | 2025-02-08 | 51943 | Update dependencies |
| 4.4.3 | 2025-02-03 | 52625 | Update error message during check for organization_access_enabled |
| 4.4.2 | 2025-01-11 | 48309 | Starting 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.1 | 2024-12-13 | 48889 | Check if start_date exist in check operation |
| 4.4.0 | 2024-11-11 | 48379 | Make DatetimeBasedCursor syncs concurrent |
| 4.3.3 | 2024-10-28 | 47663 | Update dependencies |
| 4.3.2 | 2024-10-21 | 47202 | Update dependencies and expected records |
| 4.3.1 | 2024-10-12 | 46794 | Update dependencies |
| 4.3.0 | 2024-10-09 | 46096 | Updates TicketMetrics stream for improved reliability for long syncs, updates state cursor field to _ab_updated_at, automatically migrates legacy state |
| 4.2.3 | 2024-10-05 | 46408 | Update dependencies |
| 4.2.2 | 2024-09-28 | 45784 | Update dependencies |
| 4.2.1 | 2024-09-14 | 45561 | Update dependencies |
| 4.2.0 | 2024-09-10 | 44610 | Add Automations and Triggers stream |
| 4.1.1 | 2024-09-07 | 45215 | Update dependencies |
| 4.1.0 | 2024-09-06 | 45187 | Migrate to CDK v5 |
| 4.0.2 | 2024-08-31 | 44965 | Update dependencies |
| 4.0.1 | 2024-08-24 | 44692 | Update dependencies |
| 4.0.0 | 2024-08-19 | 44096 | Stream Tags: use cursor based pagination |
| 3.0.1 | 2024-08-17 | 44324 | Update dependencies |
| 3.0.0 | 2024-08-13 | 43446 | TicketMetrics stream: updates cursor field to generated_timestamp |
| 2.7.3 | 2024-08-12 | 43900 | Update dependencies |
| 2.7.2 | 2024-08-10 | 43614 | Update dependencies |
| 2.7.1 | 2024-08-03 | 41799 | Update dependencies |
| 2.7.0 | 2024-08-02 | 42975 | Migrate to CDK v4.3.0 |
| 2.6.13 | 2024-07-31 | 42892 | Update BackoffStrategy interface to be up-to-date with latest parent interface. |
| 2.6.12 | 2024-07-25 | 42519 | Update error message for permission issue. |
| 2.6.11 | 2024-07-18 | 42100 | Raise config error on 403/404 status code. |
| 2.6.10 | 2024-07-10 | 41436 | Fix unit test |
| 2.6.9 | 2024-07-10 | 41390 | Update dependencies |
| 2.6.8 | 2024-07-09 | 40025 | Update dependencies |
| 2.6.7 | 2024-07-09 | 41032 | Use latest CDK: 3.0.0 |
| 2.6.6 | 2024-06-27 | 40592 | Updated to use latest CDK version, fixed cursor pagination logic |
| 2.6.5 | 2024-05-23 | 38607 | Migrate to cursor based pagination in stream Organization memberships |
| 2.6.4 | 2024-05-20 | 38310 | Fix record filter for Ticket Metrics stream |
| 2.6.3 | 2024-05-02 | 36669 | Schema descriptions |
| 2.6.2 | 2024-02-05 | 37761 | Add stop condition for Ticket Audits when recieved old records; Ignore 403 and 404 status codes. |
| 2.6.1 | 2024-04-30 | 37723 | Add %Y-%m-%dT%H:%M:%S%z to cursor_datetime_formats |
| 2.6.0 | 2024-04-29 | 36823 | Migrate to low code; Add new stream Ticket Activities |
| 2.5.0 | 2024-04-25 | 36388 | Fix data type of field in Tickets stream schema stream. |
| 2.4.1 | 2024-04-20 | 37450 | Fix parsing response for Ticket Metrics stream. |
| 2.4.0 | 2024-04-09 | 36897 | Fix long-running syncs for Ticket Metrics, Ticket Audits and Satisfaction Ratings streams. |
| 2.3.0 | 2024-03-26 | 36403 | Unpin CDK version, add record counts to state messages |
| 2.2.8 | 2024-02-09 | 35083 | Manage dependencies with Poetry. |
| 2.2.7 | 2024-02-05 | 34840 | Fix missing fields in schema |
| 2.2.6 | 2024-01-11 | 34064 | Skip 504 Error for stream Ticket Audits |
| 2.2.5 | 2024-01-08 | 34010 | Prepare for airbyte-lib |
| 2.2.4 | 2023-12-20 | 33680 | Fix pagination issue for streams related to incremental export sync |
| 2.2.3 | 2023-12-14 | 33435 | Fix 504 Error for stream Ticket Audits |
| 2.2.2 | 2023-12-01 | 33012 | Increase number of retries for backoff policy to 10 |
| 2.2.1 | 2023-11-10 | 32440 | Made refactoring to improve code maintainability |
| 2.2.0 | 2023-10-31 | 31999 | Extended the CustomRoles stream schema |
| 2.1.1 | 2023-10-23 | 31702 | Base image migration: remove Dockerfile and use the python-connector-base image |
| 2.1.0 | 2023-10-19 | 31606 | Added new field reply_time_in_seconds to the Ticket Metrics stream schema |
| 2.0.0 | 2023-09-15 | 30440 | Remove stream Deleted Tickets |
| 1.7.0 | 2023-09-11 | 30259 | Add stream Deleted Tickets |
| 1.6.0 | 2023-09-09 | 30168 | Make start_date field optional |
| 1.5.1 | 2023-09-05 | 30142 | Handle non-JSON Response |
| 1.5.0 | 2023-09-04 | 30138 | Add new Streams: Article Votes, Article Comments, Article Comment Votes |
| 1.4.0 | 2023-09-04 | 30134 | Add incremental support for streams: custom Roles, Schedules, SLA Policies |
| 1.3.0 | 2023-08-30 | 30031 | Add new streams: Articles, Organization Fields |
| 1.2.2 | 2023-08-30 | 29998 | Fix typo in stream AttributeDefinitions: field condition |
| 1.2.1 | 2023-08-30 | 29991 | Remove Custom availability strategy |
| 1.2.0 | 2023-08-29 | 29940 | Add undeclared fields to schemas |
| 1.1.1 | 2023-08-29 | 29904 | Make Organizations stream incremental |
| 1.1.0 | 2023-08-28 | 29891 | Add stream UserFields |
| 1.0.0 | 2023-07-27 | 28774 | Fix retry logic & update cursor for Tickets stream |
| 0.11.0 | 2023-08-10 | 27208 | Add stream Topics |
| 0.10.7 | 2023-08-09 | 29256 | Update tooltip descriptions in spec |
| 0.10.6 | 2023-08-04 | 29031 | Reverted advancedAuth spec changes |
| 0.10.5 | 2023-08-01 | 28910 | Updated advancedAuth broken references |
| 0.10.4 | 2023-07-25 | 28397 | Handle 404 Error |
| 0.10.3 | 2023-07-24 | 28612 | Fix pagination for stream TicketMetricEvents |
| 0.10.2 | 2023-07-19 | 28487 | Remove extra page from params |
| 0.10.1 | 2023-07-10 | 28096 | Replace offset pagination with cursor pagination |
| 0.10.0 | 2023-07-06 | 27991 | Add streams: PostVotes, PostCommentVotes |
| 0.9.0 | 2023-07-05 | 27961 | Add stream: Post Comments |
| 0.8.1 | 2023-06-27 | 27765 | Bugfix: Nonetype error while syncing more then 100000 organizations |
| 0.8.0 | 2023-06-09 | 27156 | Add stream Posts |
| 0.7.0 | 2023-06-27 | 27436 | Add Ticket Skips stream |
| 0.6.0 | 2023-06-27 | 27450 | Add Skill Based Routing streams |
| 0.5.0 | 2023-06-26 | 27735 | License Update: Elv2 stream stream |
| 0.4.0 | 2023-06-16 | 27431 | Add Organization Memberships stream |
| 0.3.1 | 2023-06-02 | 26945 | Make Ticket Metrics stream to use cursor pagination |
| 0.3.0 | 2023-05-23 | 26347 | Add stream Audit Logs logs` |
| 0.2.30 | 2023-05-23 | 26414 | Added missing handlers when empty json or JSONDecodeError is received |
| 0.2.29 | 2023-04-18 | 25214 | Add missing fields to Tickets stream |
| 0.2.28 | 2023-03-21 | 24053 | Fix stream sla_policies schema data type error (events.value) |
| 0.2.27 | 2023-03-22 | 22817 | Specified date formatting in specification |
| 0.2.26 | 2023-03-20 | 24252 | Handle invalid start_date when checking connection |
| 0.2.25 | 2023-02-28 | 22308 | Add AvailabilityStrategy for all streams |
| 0.2.24 | 2023-02-17 | 23246 | Handle StartTimeTooRecent error for Tickets stream |
| 0.2.23 | 2023-02-15 | 23035 | Handle 403 Error |
| 0.2.22 | 2023-02-14 | 22483 | Fix test; handle 400 error |
| 0.2.21 | 2023-01-27 | 22027 | Set AvailabilityStrategy for streams explicitly to None |
| 0.2.20 | 2022-12-28 | 20900 | Remove synchronous time.sleep, add logging, reduce backoff time |
| 0.2.19 | 2022-12-09 | 19967 | Fix reading response for more than 100k records |
| 0.2.18 | 2022-11-29 | 19432 | Revert changes from version 0.2.15, use a test read instead |
| 0.2.17 | 2022-11-24 | 19792 | Transform ticket_comments.via "-" to null |
| 0.2.16 | 2022-09-28 | 17326 | Migrate to per-stream states. |
| 0.2.15 | 2022-08-03 | 15233 | Added subscription plan check on streams discovery step to remove streams that are not accessible for fetch due to subscription plan restrictions |
| 0.2.14 | 2022-07-27 | 15036 | Convert ticket_audits.previous_value values to string |
| 0.2.13 | 2022-07-21 | 14829 | Convert tickets.custom_fields values to string |
| 0.2.12 | 2022-06-30 | 14304 | Fixed Pagination for Group Membership stream |
| 0.2.11 | 2022-06-24 | 14112 | Fixed "Retry-After" non integer value |
| 0.2.10 | 2022-06-14 | 13757 | Fixed the bug with TicketMetrics stream, HTTP Error 429, caused by lots of API requests |
| 0.2.9 | 2022-05-27 | 13261 | Bugfix for the unhandled ChunkedEncodingError and ConnectionError |
| 0.2.8 | 2022-05-20 | 13055 | Fixed minor issue for stream ticket_audits schema |
| 0.2.7 | 2022-04-27 | 12335 | Adding fixtures to mock time.sleep for connectors that explicitly sleep |
| 0.2.6 | 2022-04-19 | 12122 | Fixed 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.5 | 2022-04-05 | 11727 | Fixed the bug when state was not parsed correctly |
| 0.2.4 | 2022-04-04 | 11688 | Small documentation corrections |
| 0.2.3 | 2022-03-23 | 11349 | Fixed the bug when Tickets stream didn't return deleted records |
| 0.2.2 | 2022-03-17 | 11237 | Fixed the bug when TicketComments stream didn't return all records |
| 0.2.1 | 2022-03-15 | 11162 | Added support of OAuth2.0 authentication method |
| 0.2.0 | 2022-03-01 | 9456 | Update source to use future requests |
| 0.1.12 | 2022-01-25 | 9785 | Add additional log messages |
| 0.1.11 | 2021-12-21 | 8987 | Update connector fields title/description |
| 0.1.9 | 2021-12-16 | 8616 | Adds Brands, CustomRoles and Schedules streams |
| 0.1.8 | 2021-11-23 | 8050 | Adds TicketMetricEvents stream |
| 0.1.7 | 2021-11-23 | 8058 | Added support of AccessToken authentication |
| 0.1.6 | 2021-11-18 | 8050 | Fix wrong types for schemas, add TypeTransformer |
| 0.1.5 | 2021-10-26 | 7679 | Add ticket_id and ticket_comments |
| 0.1.4 | 2021-10-26 | 7377 | Fix initially_assigned_at type in ticket metrics |
| 0.1.3 | 2021-10-17 | 7097 | Corrected the connector's specification |
| 0.1.2 | 2021-10-16 | 6513 | Fixed TicketComments stream |
| 0.1.1 | 2021-09-02 | 5787 | Fixed incremental logic for the ticket_comments stream |
| 0.1.0 | 2021-07-21 | 4861 | Created CDK native zendesk connector |