Select spec version:

Zendesk Destination Config Reference

Beta

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

Available Plans

free
growth
enterprise

6 minute read

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.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

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

RequiredSecret

Type: string

Description: Email address of the Zendesk agent or admin RudderStack authenticates as, together with api_token.

Notes:

At most 100 characters, and must not contain line breaks. The email format isn’t checked.
A {{ path || fallback }} template is accepted in place of a literal.

Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.

api_token

RequiredSecret

Type: string

Description: Zendesk API token, used with email for API token authentication.

Notes:

At most 100 characters, and must not contain line breaks.
A spec that omits this key fails validation with 'api_token' is required.

Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.

See Connection settings for how to generate a token.

domain

Required

Type: string

Description: Your Zendesk subdomain, without .zendesk.com — acme for acme.zendesk.com. The dashboard calls it Zendesk Subdomain.

Notes:

At most 100 characters, and must not contain line breaks.
A {{ path || fallback }} template is accepted in place of a literal.
Rudder CLI doesn’t check the format, so a full host such as acme.zendesk.com passes validate, and then breaks delivery.

source_name

Type: string

Description: Source RudderStack records on the Zendesk events it creates from track calls. When omitted, RudderStack uses Rudder.

Notes:

At most 100 characters, and must not contain line breaks.
A {{ path || fallback }} template is accepted in place of a literal.
zendesk is reserved, in any capitalization. Rudder CLI accepts it, but RudderStack then fails every track event.

Users and organizations

create_users_as_verified

Type: boolean

Default value: false

Description: Create users as verified, so Zendesk skips its email verification for them.

send_group_calls_without_user_id

Type: boolean

Default value: false

Description: Let a group event without a userId create or update the organization on its own. When false, a group event needs a userId, and RudderStack adds that user to the organization.

remove_users_from_organization

Type: boolean

Default value: false

Description: Let an identify event remove the user from an organization. The event’s traits name the organization’s Zendesk ID in company.id, and set company.remove to true.

See Removing users from an organization.

search_by_external_id

Type: boolean

Default value: false

Description: Make the email in an identify event the user’s primary email in Zendesk, replacing the previous one. When false, RudderStack adds that email as a secondary email if the user already has a primary one.

Despite its name, this key doesn’t change how RudderStack finds users. It’s the setting the dashboard calls Update user’s primary email.

See Updating user’s primary email in Zendesk.

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode

Type: object

Description: Maps each source type you connect to the mode its events reach Zendesk in, using the modes in Source types.

Notes:

An entry is required for each source type you connect — see Connect a source.

yaml

connection_mode:
  web: cloud
  cloud: cloud

consent_management

Type: object

Description: Consent provider configuration per source type. The entry shape, accepted providers, and the rules on resolution_strategy and consents are shared across all destination types — see Consent management.

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 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 — see Manage Reverse ETL Connections using Rudder CLI.

The dashboard additionally offers Zendesk to AMP and Shopify sources. Rudder CLI doesn’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. Without it:

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.

See How to Use Variable Substitution in Rudder CLI.

Changes by release

No changes since this type became available.

For changes across every destination type, see Destination Type Changes by Release.

See more

Zendesk Destination for API token setup, attribute mapping, and organization membership
Destination Type Reference for Rudder CLI for the rules shared across destination types
Destination YAML Reference for the spec envelope

Zendesk Destination Config Reference

Sample configuration

Config keys

Connection

Users and organizations

Per-source keys

Source types

Connect a source

Secrets

Changes by release

See more

Questions? Let's figure it out together.