<a id="zendesk-source-connector"></a>

# Zendesk Source Connector for Confluent Platform

Zendesk Support is a system for tracking, prioritizing, and solving customer
support tickets. The Kafka Connect Zendesk Source connector copies data into
Apache Kafka® from various Zendesk support tables such as `tickets`,
`ticket_audits`, `ticket_fields`, `groups`,  `organizations`,
`satisfaction_ratings`, and others, using the [Zendesk Support API](https://developer.zendesk.com/rest_api/docs/support/introduction). You can
find the list of supported Zendesk tables in the [supported tables section](#zendesk-source-connector-resources).

#### IMPORTANT
<!-- WARNING: THIS IS A SHARED FILE AND THE SOURCE IS LOCATED IN DOCS-COMMON. DO NOT ADD TO ANY OTHER REPO. -->

Effective July 6, 2025, only self-managed connector versions that meet or exceed the minimum version listed on the
[Supported Connector Versions](https://docs.confluent.io/platform/7.8/connect/supported-connector-version.html#supported-connector-versions-till-cp-7-8)
page receive support from Confluent. Older, unsupported connector versions have been removed from Confluent Marketplace and
are no longer available for download.

<a id="zendesk-source-connector-feature"></a>

## Features

The Zendesk Source connector offers the following features:

- [At least once delivery](#zendesk-source-at-least-once-delivery)
- [Quick turnaround](#zendesk-source-quick-turnaround)
- [Schema detection and evolution](#zendesk-source-schema-detection)
- [Real-time and historical lookup](#zendesk-source-real-time-historical-lookup)
- [Automatic retries](#zendesk-source-automatic-retries)
- [Intelligent backoffs](#zendesk-source-intelligent-backoffs)
- [Resource balance and throughput](#zendesk-source-resource-throughput)
- [Client-side encryption](#zendesk-source-csfle-sm)

<a id="zendesk-source-at-least-once-delivery"></a>

### At least once delivery

The connector guarantees no loss of messages from Zendesk to Kafka. Messages may
be reprocessed because of task failure or API limits, which may cause
duplication.

<a id="zendesk-source-quick-turnaround"></a>

### Quick turnaround

The Zendesk connector ensures that data between your Zendesk Tables and
corresponding Kafka topics are synced quickly, without unnecessary lag. The poll
frequency on each table has been specifically configured based on the size of
the table, so that larger and more dynamic tables, like `Tickets`, are polled
more frequently than the static tables like `Organizations`.

<a id="zendesk-source-schema-detection"></a>

### Schema detection and evolution

The connector supports automatic schema detection and backward compatible schema
evolution for all supported tables.

<a id="zendesk-source-real-time-historical-lookup"></a>

### Real-time and historical lookup

The connector supports fetching all the past historical records for all tables.
It can also be configured to pull in data from only a specified time in the past
(see [configuration property](configuration.md#zendesk-source-connector-config)
`zendesk.since`).

<a id="zendesk-source-automatic-retries"></a>

### Automatic retries

In case of a connection error between the API server and Kafka Connect, the
connector may receive a `not OK` response from the API server or no response at
all. In such cases, the connector can be made robust using the automatic retry
mechanism with linear backoff using [configuration properties](configuration.md#zendesk-source-connector-config) `max.retries` and `retry.backoff.ms`.

<a id="zendesk-source-intelligent-backoffs"></a>

### Intelligent backoffs

If there are too many requests because of [support API rate limits](https://developer.zendesk.com/rest_api/docs/support/introduction#rate-limits),
the connector intelligently spaces out the HTTP fetch operations to ensure a
smooth balance between recency, API limits, and back pressure.

<a id="zendesk-source-resource-throughput"></a>

### Resource balance and throughput

Some resources within Zendesk are created and updated at a much greater rate
than other Zendesk resources. These resources can be balanced among the workers,
with reduced hot-spotting, by keeping the resources in configuration
`zendesk.tables` sorted by the order of their expected cardinality. Also, the
`task.max`, `max.in.flight.requests`, and `max.batch.size` configuration
properties can be used to improve overall throughput.

<a id="zendesk-source-csfle-sm"></a>

### Client-side encryption

This connector supports Client-Side Field Level Encryption (CSFLE) and Client-Side Payload Encryption (CSPE). For more information, see [Manage Client-Side Encryption](https://docs.confluent.io/platform/current/connect/manage-csfle.html).

<a id="zendesk-source-connector-resources"></a>

## Supported Tables

The following tables from Zendesk are supported in this version of the
Kafka Connect Zendesk Source connector:

- custom_roles
- groups
- group_memberships
- organizations
- organization_subscriptions
- organization_memberships
- satisfaction_ratings
- tickets
- ticket_audits
- ticket_fields
- ticket_metrics
- users

## Limitations

For Schema Registry-based output formats, the connector tries to deduce the schema based on
the source API response returned. The connector registers a new schema for every
NULL and NOT NULL value of an optional field in the API response. For this
reason, the connector may register schema versions at a much higher rate than
expected.

<a id="zendesk-connector-license"></a>

## License

You can use this connector for a 30-day trial period without a license key.

After 30 days, you must purchase a connector subscription which includes [Confluent enterprise license](/platform/current/installation/license.html#enterprise-subscription-license) keys to subscribers, along with [enterprise-level support](https://www.confluent.io/subscription/) for Confluent Platform and your connectors. If you are a subscriber, you can contact [Confluent Support](https://support.confluent.io/) for more information.

For license properties, see [Confluent Platform license](configuration.md#zendesk-source-connector-license-config) and
for information about the license topic, see
[License topic configuration](configuration.md#zendesk-source-license-topic-configuration).

## Configuration properties

For a complete list of configuration properties for this connector, see
[Configuration Reference for Zendesk Source Connector for Confluent Platform](configuration.md#zendesk-source-connector-config).

For an example of how to get Kafka Connect connected to [Confluent Cloud](/cloud/current/index.html), see
[Connect Self-Managed Kafka Connect to Confluent Cloud](/cloud/current/cp-component/connect-cloud-config.html#distributed-cluster).

<a id="zendesk-source-connector-install"></a>

## Install the Zendesk Source connector

You can install this connector by using the [Confluent Hub client installatiion
instructions](https://docs.confluent.io/home/connect/confluent-hub/client.html) or by manually
downloading the ZIP file.

### Prerequisites

- You must install the connector on every machine where Connect will run.
- Kafka Broker: Confluent Platform 3.3.0 or later, or Kafka 0.11.0 or later.
- Kafka Connect: Confluent Platform 4.1.0 or later, or Kafka 1.1.0 or later.
- Java 8+. Note that Java 8 is deprecated in versions 7.2 and later of Confluent Platform. For
  more details, view [Java compatibility with Confluent Platform](/platform/current/installation/versions-interoperability.html#java)
   by version.
- Zendesk account type: Certain tables, such as `custom_roles`, can only be
  accessed if the Zendesk account is an `Enterprise` account. For more
  details, see [Custom Agent Roles](https://developer.zendesk.com/rest_api/docs/support/custom_roles).
- Zendesk API: [Support APIs](https://https://developer.zendesk.com/rest_api/docs/support/introduction)
  should be enabled for the Zendesk account. Also, either `oauth2` or
  `password` mechanism should be enabled in the Zendesk account. For
  more information, see [Using the API dashboard: Enabling password or token
  access](https://support.zendesk.com/hc/en-us/articles/115002555167-Using-the-API-dashboard).
- Zendesk settings: Some settings may need to be enabled to ensure export is
  possible. Example, `satisfaction_ratings` can only be exported if it is
  enabled. For more details, see [Support API: Satisfaction Ratings](https://developer.zendesk.com/rest_api/docs/support/satisfaction_ratings).
- Because every table requires a different role to be fetched by the connector,
  Confluent recommends you check the [Zendesk API](https://developer.zendesk.com/api-reference/custom-data/custom-objects-api/permissions/)
  for the role required to use this connector.

### Install the connector using the Confluent CLI

To install the `latest` connector version, navigate to your Confluent Platform installation directory and run the following command:

```bash
confluent connect plugin install confluentinc/kafka-connect-zendesk:latest
```

You can install a specific version by replacing `latest` with a version
number as shown in the following example:

```bash
confluent connect plugin install confluentinc/kafka-connect-zendesk:1.3.0
```

### Install the connector manually

[Download and extract the ZIP file](https://www.confluent.io/hub/confluentinc/kafka-connect-zendesk) for your
connector and then follow the manual connector installation
[instructions](/kafka-connectors/self-managed/install.html).

<a id="zendesk-source-connector-quickstart"></a>

## Quick Start

In this quick start guide, the Zendesk connector is used to consume records from
a Zendesk resource called `tickets` and send the records to a Kafka topic named
`ZD_tickets`.

To run this quick start, ensure you have a [Zendesk Developer Account](https://developer.zendesk.com/).

1. Install the connector through the [Confluent Hub Client](https://docs.confluent.io/current/connect/managing/confluent-hub/client.html).
   ```bash
   # run from your confluent platform installation directory
   confluent connect plugin install confluentinc/kafka-connect-zendesk:latest
   ```
2. Start the Confluent Platform.
   ```bash
   confluent local start
   ```
3. Check the status of all services.
   ```bash
   confluent local services status
   ```
4. Configure your connector by first creating a JSON file named `zendesk.json` with the following properties.
   ```bash
   // substitute <> with your config
   {
       "name": "ZendeskConnector",
       "config": {
           "connector.class": "io.confluent.connect.zendesk.ZendeskSourceConnector",
           "key.converter": "org.apache.kafka.connect.storage.StringConverter",
           "value.converter": "org.apache.kafka.connect.json.JsonConverter",
           "value.converter.schemas.enable": "false",
           "confluent.topic.bootstrap.servers": "127.0.0.1:9092",
           "confluent.topic.replication.factor": 1,
           "confluent.license": "<license>", // leave it empty for evaluation license
           "tasks.max": 1,
           "poll.interval.ms": 1000,
           "topic.name.pattern": "ZD_${entityName}",
           "zendesk.auth.type": "basic",
           "zendesk.url": "https://<sub-domain>.zendesk.com",
           "zendesk.user": "<username>",
           "zendesk.password": "<password>",
           "zendesk.tables": "tickets",
           "zendesk.since": "2019-08-01"
       }
   }
   ```
5. Start the Zendesk Source connector by loading the connector’s configuration with the following command:
   ```bash
   confluent local load zendesk --config zendesk.json
   ```
6. Confirm that the connector is in a `RUNNING` state.
   ```bash
   confluent local status ZendeskConnector
   ```
7. Create one ticket record using Zendesk API as follows.
   ```bash
   curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
     -d '{"ticket": {"subject": "My printer is on fire!", "comment": { "body": "The smoke is very colorful." }}}' \
     -H "Content-Type: application/json" -v -u {email_address}:{password} -X POST
   ```
8. Confirm the messages were delivered to the `ZD_tickets` topic in Kafka. Note, it may take a minute before the record populates the topic.
   ```bash
   confluent local consume ZD_tickets --from-beginning
   ```