# Zendesk integration

## About this integration

Zendesk is a customer service platform that helps you build better customer relationships. This integration helps you send data to Zendesk, helping you identify your users and enrich their profiles with data from your sources. This helps you provide your customers with better support.

[Mode How we forward source data to the destination: through Customer.io's servers or directly from our JavaScript client.](/cdp/destinations/getting-started/#connection-mode)

[Web sources Indicates whether or not this integration supports our the JavaScript client.](/cdp/sources/getting-started/#types-of-sources)

[API sources Indicates whether or not this integration supports our server libraries (Go, NodeJS, Python), API, Mobile SDK, and other data sources.](/cdp/sources/getting-started/#types-of-sources)

[Supported calls The API methods this integration supports.](/cdp/sources/source-spec/source-events/)

[Integration name The name of this integration if you want to enable or disable it in the `integrations` object.](/cdp/sources/source-spec/common-fields/#the-integrations-object)

Standard

[track](/api/cdp/#operation/track), [identify](/api/cdp/#operation/identify), and [group](/api/cdp/#operation/group)

Zendesk

## Getting started[](#getting-started)

1.  Go to **[Data & Integrations > Integrations](https://fly.customer.io/workspaces/last/journeys/integrations/all/directory)** and select the **Zendesk** entry in the *Directory* tab.
    
2.  (Optional) Select the data sources that you want to connect to your outbound integration. You can always connect data sources later. We’ll only show you data sources that work with your integration.
    
3.  Configure your integration.
    
    1.  **Subdomain**: The subdomain of your Zendesk instance. For example, if your Zendesk URL is [https://example.zendesk.com](https://example.zendesk.com), your subdomain is `example`.
4.  Click **Enable Destination**.
    

## Actions[](#actions)

When you’re done setting things up, you can go to the *Actions* tab to see how we map incoming data to your integration.

You may need to add actions for this integration

While we often have default triggers for actions, we don't always add those actions as defaults. You may need to add actions to make sure that you're sending all the data that you want to send to your integration. See our [actions](/integrations/data-out/actions/) page for help setting up actions.

Action

Default Trigger

Description

Create Ticket

`type = “track”` and  
`event = “Ticket Created”`

Create a new ticket.

Track Event

`type = “track”` and  
`event != “Ticket Created”` and  
`event != “Ticket Updated”`

Track a custom event for an existing user.

Update Organization Membership (via identify)

`type = “identify”` and  
`traits.company.id != null`

Associate a user to an organization, or remove them if `traits.company.remove` is true.

Update Ticket

`type = “track”` and  
`event = “Ticket Updated”`

Update an existing ticket.

Upsert Organization

`type = “group”`

Upsert an organization. If `userId` is supplied we also associate the user with the organization.

Upsert User

`type = “identify”`

Insert or update a user record in Zendesk using the provided user email.

## Identify Zendesk Users[](#identify-zendesk-users)

When you call our `identify` API, we add or update a user record in Zendesk. To add people to Zendesk, your calls must include:

*   `traits.email`—the email address of the person.
*   A `name` or `first_name` and `last_name` traits. If the incoming calls includes a `first_name` and `last_name`, we parse it into the `name` field.

When updating user records in Zendesk, we match users based on their `email` address of a person you identify (typically `$.traits.email`) or their `external_id` (typically `$.userId`). A Zendesk profile can have multiple email addresses, but each address is unique to an individual user in your Zendesk instance.

```json
{
  "action": "identify",
  "userId": "12345",
  "traits": {
    "name": "Homer Simpson",
    "email": "homer.simpson@example.com",
    "timezone": "America/Springfield",
    "organizationId": 6789,
    "phone": "555-555-1234"
  }
}
```

### Mapping traits to Zendesk users[](#mapping-traits-to-zendesk-users)

We map incoming traits from your integrations to the following standard Zendesk user attributes.

Customer.io Trait

Zendesk User Attribute

email

email

name

name

organizationId

organization\_id

timezone

time\_zone

phone

phone

userId

external\_id

To store other traits in Zendesk, you must first define them as **User Fields**. If your `identify` call sends a trait that you haven’t added to your Zendesk configuration, Zendesk will discard it.

You can add your custom traits in Zendesk under **Admin Center** > **People** > **Configuration** > **User Fields**.

[![add user fields to zendesk](https://docs.customer.io/images/zendesk-user-fields.png)](#e1276997199062a71797e448060c3dcb-lightbox)

When Customer.io sends data to Zendesk, you should see the populated attributes in the customer’s context. See [Adding custom fields to users](https://support.zendesk.com/hc/en-us/articles/203662066) in Zendesk help for more information.

[![User fields shown on a zendesk user](https://docs.customer.io/images/zendesk-user.png)](#abd1490f720c61f8ea5000f0923c36e4-lightbox)

### Adding or Removing Users to/from a Zendesk Organization[](#adding-or-removing-users-tofrom-a-zendesk-organization)

You can add a user to a Zendesk organization by passing `traits.company.id` in your `identify` calls. You can also remove people from an organization by setting `traits.company.remove: true`.

Add person to organization

Remove person from organization

```json
{
  "action": "identify",
  "userId": "12345",
  "traits": {
    "company": {
      "id": "6789"
    }
  }
}
```

```json
{
  "action": "identify",
  "userId": "12345",
  "traits": {
    "company": {
      "id": "6789",
      "remove": true
    }
  }
}
```

 Removing a person from an organization unassigns their tickets

When you remove someone from an organization, Zendesk schedules a job to unassign all that person’s working tickets and sets the `organization_id` on those tickets to `null`

### Zendesk Verification Email at User Creation[](#zendesk-verification-email-at-user-creation)

By default, Zendesk sends a verification email to users when you create them.

You can prevent people you `identify` from receiving these verification emails by enabling the **Skip Verify Email** setting. The user’s email may still require verification if the “Create Users as Verified” option is false.

### Create Users as Verified[](#create-users-as-verified)

By default all users are created as unverified and may receive a verification email (if the `Skip Verify Email` is false). If you have already verified your user’s email by other means you may wish to create them as verified in Zendesk.

To do so, set the **Create Users as Verified** setting to true on the default `Create or Update User` action on your Zendesk integration.

## Track[](#track)

A `track` call represents an event—something someone does on your website or in your app that you want to report to Zendesk. When you make a `track` call, you’re sending information about a user’s activity to Zendesk.

Events must be associated with a user in Zendesk. If you provide a `context.zendesk_user_id` we will directly track the event under that ID.

Otherwise, if you provide an `email` and/or `external_id` we will search for the user and track the event with the found user. If no user is found an error will be returned.

```json
{
  "action": "track",
  "userId": "1234",
  "event": "Article Read",
  "properties": {
    "title": "How to use Customer.io",
    "course": "Intro to Customer.io"
  }
}
```

### Mapping track events to Zendesk Sunshine[](#mapping-track-events-to-zendesk-sunshine)

 Zendesk Sunshine is not required

You can use Sunshine by sending an `email` as described below, but this integration works without it as well.

If you want to map a track call to a Zendesk Sunshine event by email, you can set the user’s email address in as `properties.email` in your call. This helps Zendesk tie the event to a user. If your event does not include `properties.email`, we send the `userId` as `external_id`.

When your call includes an email address, a track call (from our JavaScript library) might look like this:

```js
cioanalytics.track('Article Read', {
  title: 'How to use Customer.io',
  course: 'Intro to Customer.io',
  properties: {
    email : 'person@example.com',
  }
});
```

## Group[](#group)

When you send a `group` call, we insert or update an organization in Zendesk. We use the `groupId` in your call to match organization records in Zendesk. If the `groupId` doesn’t exist, we create a new organization; if it exists, we update the existing organization.

Create an organization without users

Create an organization and add a user

```json
{
  "action": "group",
  "groupId": "xyz999",
  "traits": {
    "name": "SF Giants",
    "url": "https://mlb.com/giants"
  }
}
```

```json
{
  "action": "group",
  "groupId": "abc123",
  "userId": "1234",
  "traits": {
    "name": "SF Giants",
    "url": "https://mlb.com/giants"
  }
}
```

### Organization attributes[](#organization-attributes)

Organizations in Zendesk have standard attributes. We map to the subset of these attributes listed below.

Segment Field Name

Zendesk Field Name

name

name

domainNames      

domain\_names

tags         

tags        

groupId

external\_id

url

url

deleted

deleted

When you pass traits in your `group` calls, we’ll first try to map traits to known, existing fields in Zendesk—either the standard fields above or custom fields you’ve already created. If a custom field does not exist, we’ll create it.

We format incoming traits to camelCase or snake\_case as necessary; if you don’t see custom fields populate in Zendesk, you may need to check the way you format traits in your `group` calls.