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.

Setup guide

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

  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 source connector

  1. Log in to your Airbyte Cloud account.
  2. In the left navigation bar, click Sources. In the top-right corner, click + New source.
  3. Find and select Zendesk Support from the list of available sources.
  4. For Source name, enter a name to help you identify this source.
  5. 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.
  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. 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 API returns only the data updated or generated since the last sync).
  2. 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:

Deleted Records Support

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

StreamDeletion indicator field
Brandsis_deleted
Groupsdeleted
Organizationsdeleted_at
Ticket Metric Eventsdeleted
Ticketsstatus==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.

Reference

Config fields reference

Field
Type
Property name
string
subdomain
string
start_date
object
credentials
boolean
ignore_pagination

Changelog

Expand to review
VersionDatePull RequestSubject
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-238050Adds 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