# Zendesk Destination Config Reference


> Complete Rudder CLI reference for the Zendesk destination config keys, user and organization settings, source types, and secrets.



[Zendesk](https://www.rudderstack.com/docs/destinations/streaming-destinations/zendesk/) is a customer support destination. RudderStack creates and updates Zendesk users from `identify` events and organizations from `group` events, and records `track` events as events on the user's profile, from its servers.

In a Zendesk destination spec:

- `type: zendesk`
- `definition_version: 1`

## Sample configuration

```yaml
version: rudder/v1
kind: destination
metadata:
  name: zendesk-prod
spec:
  id: zendesk-prod
  display_name: Zendesk Production
  type: zendesk
  definition_version: 1
  enabled: true
  config:
    email: "{{ .ZENDESK_EMAIL }}"
    api_token: "{{ .ZENDESK_API_TOKEN }}"
    domain: acme
    source_name: Acme Web

    create_users_as_verified: false
    send_group_calls_without_user_id: false
    remove_users_from_organization: false
    search_by_external_id: true

    connection_mode:
      web: cloud
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - analytics
```

The above example makes the email in each `identify` event the user's primary email in Zendesk — which is what `search_by_external_id` does, despite its name. See [Users and organizations](#users-and-organizations).

## Config keys

`config` accepts only the keys listed below. The [shared config key rules](https://www.rudderstack.com/docs/rudder-cli/destination-types/#config-key-rules) cover unknown keys, defaults, and immutability.

**Info:** Zendesk accepts only `identify`, `group`, and `track` events. `identify` and `track` events need a `userId`, and a `track` event also needs the user's `email` trait.

### Connection

<div class="rs-ckeys">
<div class="rs-ckey" id="email">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">email</p>RequiredSecret</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Email address of the Zendesk agent or admin RudderStack authenticates as, together with <code>api_token</code>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, and must not contain line breaks. The email format isn&rsquo;t checked.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  Supply it as a <code>{{ .VAR }}</code> reference rather than a literal — see <a href="#secrets" >Secrets</a>.
</div>

</div>

<div class="rs-ckey" id="api_token">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">api_token</p>RequiredSecret</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Zendesk API token, used with <code>email</code> for API token authentication.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>A spec that omits this key fails validation with <code>'api_token' is required</code>.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <p>Supply it as a <code>{{ .VAR }}</code> reference rather than a literal — see <a href="#secrets" >Secrets</a>.</p>
<p>See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/zendesk/#connection-settings" >Connection settings</a> for how to generate a token.</p>

</div>

</div>

<div class="rs-ckey" id="domain">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">domain</p>Required</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Your Zendesk subdomain, without <code>.zendesk.com</code> — <code>acme</code> for <code>acme.zendesk.com</code>. The dashboard calls it <strong>Zendesk Subdomain</strong>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal.</li>
<li>Rudder CLI doesn&rsquo;t check the format, so a full host such as <code>acme.zendesk.com</code> passes <code>validate</code>, and then breaks delivery.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="source_name">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">source_name</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Source RudderStack records on the Zendesk events it creates from <code>track</code> calls. When omitted, RudderStack uses <code>Rudder</code>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal.</li>
<li><code>zendesk</code> is reserved, in any capitalization. Rudder CLI accepts it, but RudderStack then fails every <code>track</code> event.</li>
</ul>

</div>

</div>

</div>

### Users and organizations

<div class="rs-ckeys">
<div class="rs-ckey" id="create_users_as_verified">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">create_users_as_verified</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Create users as verified, so Zendesk skips its email verification for them.
</p>

</div>

<div class="rs-ckey" id="send_group_calls_without_user_id">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">send_group_calls_without_user_id</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Let a <code>group</code> event without a <code>userId</code> create or update the organization on its own. When <code>false</code>, a <code>group</code> event needs a <code>userId</code>, and RudderStack adds that user to the organization.
</p>

</div>

<div class="rs-ckey" id="remove_users_from_organization">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">remove_users_from_organization</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Let an <code>identify</code> event remove the user from an organization. The event&rsquo;s traits name the organization&rsquo;s Zendesk ID in <code>company.id</code>, and set <code>company.remove</code> to <code>true</code>.
</p>

<div class="rs-ckey__extra">
  See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/zendesk/#removing-users-from-an-organization" >Removing users from an organization</a>.
</div>

</div>

<div class="rs-ckey" id="search_by_external_id">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">search_by_external_id</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Make the email in an <code>identify</code> event the user&rsquo;s primary email in Zendesk, replacing the previous one. When <code>false</code>, RudderStack adds that email as a secondary email if the user already has a primary one.
</p>

<div class="rs-ckey__extra">
  <p><strong>Warning:</strong> Despite its name, this key doesn't change how RudderStack finds users. It's the setting the dashboard calls <strong>Update user's primary email</strong>.</p>
<p>See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/zendesk/#updating-users-primary-email-in-zendesk" >Updating user&rsquo;s primary email in Zendesk</a>.</p>

</div>

</div>

</div>

### Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under [Source types](#source-types). A key naming a source type this destination doesn't support fails validation.

<div class="rs-ckeys">
<div class="rs-ckey" id="connection_mode">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">connection_mode</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Maps each source type you connect to the mode its events reach Zendesk in, using the modes in <a href="#source-types" >Source types</a>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>An entry is required for each source type you connect — see <a href="#connect-a-source" >Connect a source</a>.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">connection_mode:
  web: cloud
  cloud: cloud</code></pre></div>
</div>
</div>

</div>

<div class="rs-ckey" id="consent_management">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">consent_management</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Consent provider configuration per source type. The entry shape, accepted providers, and the rules on <code>resolution_strategy</code> and <code>consents</code> are shared across all destination types — see <a href="https://www.rudderstack.com/docs/rudder-cli/destination-types/#consent-management" >Consent management</a>.
</p>

</div>

</div>

## Source types

Zendesk accepts events from these source types in the mentioned connection modes:

| Source type | Connection mode |
| :-----| :-----|
| `android` | `cloud` |
| `android_kotlin` | `cloud` |
| `ios` | `cloud` |
| `ios_swift` | `cloud` |
| `web` | `cloud` |
| `unity` | `cloud` |
| `react_native` | `cloud` |
| `flutter` | `cloud` |
| `cordova` | `cloud` |
| `cloud` | `cloud` |
| `warehouse` | `cloud` |

Every source type is `cloud` only — events reach Zendesk from RudderStack's servers, never in device mode.

`warehouse` is the token a [Reverse ETL source](https://www.rudderstack.com/docs/sources/reverse-etl/) resolves to. Rudder CLI manages the destination’s `warehouse` entry — if the destination is connected to a Reverse ETL source, set `connection_mode.warehouse: cloud` in its spec, or `apply` removes it.

Rudder CLI can also declare the Reverse ETL connection itself, for the types listed under [Supported destinations](https://www.rudderstack.com/docs/rudder-cli/yaml-retl-connections/#supported-destinations) — see [Manage Reverse ETL Connections using Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/retl-connections/).

**Info:** The dashboard additionally offers Zendesk to AMP and Shopify sources. Rudder CLI doesn&#39;t manage those connections, so `amp` and `shopify` are invalid here.

## Connect a source

An event stream connection to this destination is checked against two rules at `validate` time.

**The source's type must be supported.** A source's type resolves to one of the tokens above before the check — a JavaScript source resolves to `web`, and webhook and server-side SDK sources resolve to `cloud`. Every type an event stream source can resolve to is supported here, so this check always passes.

**The destination config must carry a `connection_mode` entry for that source type.** This lives on the destination spec, not on the [connection spec](https://www.rudderstack.com/docs/rudder-cli/yaml-connections/). Without it:

```text
destination 'zendesk-prod' config has no 'connection_mode' entry for source type 'web'
```

Zendesk needs no additional config keys to connect a source of any type.

## Secrets

`email` and `api_token` are the secret keys. Write each as a `{{ .VAR }}` reference and supply the value at apply time:

```yaml
config:
  email: "{{ .ZENDESK_EMAIL }}"
  api_token: "{{ .ZENDESK_API_TOKEN }}"
```

```bash
export RUDDER_ZENDESK_EMAIL="..."
export RUDDER_ZENDESK_API_TOKEN="..."
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml
```

Note that:

- `rudder-cli import` writes only the secrets the API returns, as `{{ .VAR }}` references, and leaves the others out. Add any secret key it leaves out, then supply the variables before you apply — see [Secrets](https://www.rudderstack.com/docs/rudder-cli/destination-types/#secrets).

See [How to Use Variable Substitution in Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/variable-substitution/).

## Changes by release

<p>No changes since this type became available.</p>

For changes across every destination type, see [Destination Type Changes by Release](https://www.rudderstack.com/docs/rudder-cli/destination-types/changes/).

## See more

- [Zendesk Destination](https://www.rudderstack.com/docs/destinations/streaming-destinations/zendesk/) for API token setup, attribute mapping, and organization membership
- [Destination Type Reference for Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/destination-types/) for the rules shared across destination types
- [Destination YAML Reference](https://www.rudderstack.com/docs/rudder-cli/yaml-destinations/) for the spec envelope