# Zendesk Integration

The integration between Zendesk and YouTrack helps you keep customer communication synced between both tools.

When the integration with Zendesk is enabled and configured in YouTrack, it works as follows:

* When a new ticket appears in Zendesk, it creates a new ticket in YouTrack.

* The ticket in YouTrack has a link to the corresponding ticket in Zendesk.

* Ticket updates are synced both ways: changes from YouTrack are synced to Zendesk, and vice versa.

## Prerequisites

To create a new integration with Zendesk, make sure you meet the following prerequisites.

* Your YouTrack is accessible to inbound connections.

* The Zendesk user account you use to create an OAuth client has the Admin role.

## Setup

To enable and configure the Zendesk integration, follow these steps:

1. Create a [Helpdesk project](helpdesk.html) in YouTrack.

2.  [Create an OAuth client](#create-zendesk-oauth-client) in Zendesk.

3. [Connect to a Zendesk site](#connect-to-zendesk).

4. Create a [mapping](#create-mapping) between a Helpdesk project in YouTrack and a Zendesk brand.

### Create an OAuth Client in Zendesk

YouTrack uses the OAuth client credentials to request access tokens from Zendesk. The OAuth client must be confidential and allow read and write access.

Procedure: To create an OAuth client in Zendesk:

1. In Admin Center in Zendesk, select `Apps and integrations > APIs > OAuth clients`.

2. Click the Add OAuth client button.

3. Enter a name for the client and set Client kind to Confidential.

4. In the Scopes setting, allow read and write access.

5. Click the Save button.

6. Copy the client identifier and secret. You need to enter these values in YouTrack.

> **Note:**
> The full client secret is displayed only once. Store it securely before you leave the page.

For details, see [Registering your application with Zendesk](https://support.zendesk.com/hc/en-us/articles/4408845965210-Using-OAuth-authentication-with-your-application#topic_s21_lfs_qk).

### Connect to a Zendesk Site

To set up an integration with Zendesk, you need to connect to your Zendesk site first.

> **Warning:**
> Zendesk is phasing out API-token authentication and plans to deactivate all remaining Support API tokens on April 30, 2027. Use OAuth 2.0 for new connections and migrate existing API-token connections before this date. For details, see the [Zendesk announcement](https://support.zendesk.com/hc/en-us/articles/10851263566234-Announcing-the-removal-of-API-tokens-as-an-authentication-method-for-API-requests).

Procedure: To connect to a Zendesk site:

1. From the main navigation menu in YouTrack, select ![](https://resources.jetbrains.com/help/img/youtrack/2026.2/settings.svg) `Administration > Integrations > Zendesk Integration`.

2. Click the New Zendesk Integration button.

* The New Integration form opens.

![New Zendesk integration form with the relevant fields and action controls displayed.](https://resources.jetbrains.com/help/img/youtrack/2026.2/new-zendesk-integration-form.png)

3. Enter the following settings:

| Setting | Description |
| --- | --- |
| URL | The URL of your Zendesk site. |
| Authentication type | The method used to authenticate the connection.       * OAuth 2.0 uses a Zendesk OAuth client and is selected by default.    * API token uses the email address and API token for a Zendesk user account.    |
| Client ID | The identifier of the OAuth client created in Zendesk. This setting is available when the authentication type is OAuth 2.0. |
| Client secret | The secret of the OAuth client created in Zendesk. This setting is available when the authentication type is OAuth 2.0. |
| Email | The email address for the user account you use to connect to Zendesk. This setting is available when the authentication type is API token. |
| Token | The API token that authenticates the Zendesk user account. This setting is available when the authentication type is API token. |
| Import script package | The package that contains the scripts for importing data from Zendesk. The default package is `@jetbrains/youtrack-zendesk-client/zendesk-integration-client`.  |

4. Click the Save button.

* Your YouTrack is connected to the Zendesk site.

* In the background, a new import configuration has been added to your YouTrack. When you add a mapping to the Zendesk integration, YouTrack will update the project mapping in the import configuration, and the import will run continuously. To check the details of this import configuration, open the ![](https://resources.jetbrains.com/help/img/youtrack/2026.2/settings.svg) Administration menu and select `Integrations > Imports`. To learn more about imports in YouTrack, see [Imports](imports.html).

### Create a Mapping

To configure an integration of a YouTrack project with a brand in Zendesk, set up a mapping.

Procedure: To create a mapping:

1. From the main navigation menu, select ![](https://resources.jetbrains.com/help/img/youtrack/2026.2/settings.svg) `Administration > Integrations > Zendesk Integration`.

2. On the Zendesk Integration page, click the New Mapping button.

* The New Mapping dialog opens.

![The New Mapping dialog with the relevant fields and action controls displayed.](https://resources.jetbrains.com/help/img/youtrack/2026.2/zendesk-new-mapping.png)

3. Provide values for the following settings:

| Setting | Description |
| --- | --- |
| YouTrack project | The Helpdesk project in YouTrack where tickets from Zendesk will be imported. |
| Zendesk brand | The tickets from this Zendesk brand will be synced with the tickets in YouTrack. |
| Status field | The name of the custom field in YouTrack that stores the ticket status from Zendesk.  |
| Additional filter | Additional criteria for choosing which Zendesk tickets are shared with the selected YouTrack project. For filtering, use the [Zendesk query language](https://support.zendesk.com/hc/en-us/articles/4408886879258-Zendesk-Support-search-reference).  |
| Sync tags | Enable this option to sync tags between YouTrack and Zendesk. |
| Sync custom fields | Enable this option to sync custom fields and their values between YouTrack and Zendesk.  |
| Group | All tickets in YouTrack created from tickets in Zendesk will have default visibility restricted to this user group.  |

4. Click the Save button.

![YouTrack interface showing a zendesk integration mapping.](https://resources.jetbrains.com/help/img/youtrack/2026.2/zendesk-mapping-created.png)

* A mapping between a YouTrack project and a Zendesk brand is created. The Zendesk integration is set up and active.

* In the background, the import configuration that connects YouTrack and Zendesk is updated. The project mapping in the import configuration now connects the selected YouTrack project and the Zendesk brand. The import configuration between YouTrack and Zendesk is set up and active. ![Zendesk import configuration page showing its configuration fields and current values.](https://resources.jetbrains.com/help/img/youtrack/2026.2/zendesk-import-configuration.png) To check the details of this import configuration, open the ![](https://resources.jetbrains.com/help/img/youtrack/2026.2/settings.svg) Administration menu and select `Integrations > Imports`.

* In the background, the `Send issue updates back to Zendesk` workflow rule is attached to the YouTrack project. ![Workflows page showing zendesk client workflow.](https://resources.jetbrains.com/help/img/youtrack/2026.2/zendesk-workflow.png) This workflow is provided by the Zendesk Migration Manager app, which is also attached to the YouTrack project. To check the details of the workflow rule and the Zendesk Migration Manager app, navigate to the settings page for your YouTrack project and check the Workflows and Apps tabs, respectively.

## Use the Zendesk Integration

### Zendesk Integration in Action

When a ticket appears in Zendesk, YouTrack processes it and determines whether it matches an existing mapping.

![YouTrack interface showing a ticket in zendesk.](https://resources.jetbrains.com/help/img/youtrack/2026.2/zdi-zendesk-ticket.png)

If the Zendesk ticket matches the settings in the mapping, a corresponding ticket is created in YouTrack.

YouTrack creates new tickets as follows:

* YouTrack stores the current state of the Zendesk ticket in the custom field set in the integration settings.

* If YouTrack finds a user account matching the original requester's email, this user is set as the ticket reporter. Otherwise, YouTrack creates a new reporter account.

The Origin field in YouTrack displays the original ticket number and a link to the corresponding ticket in Zendesk.

![YouTrack interface showing link to zendesk ticket in issue.](https://resources.jetbrains.com/help/img/youtrack/2026.2/zdi-issue-links.png)

When you write a comment or change a custom field value in the YouTrack ticket, the change is imported into Zendesk and vice versa. For more details on how the integration works and syncs data, see [Technical Details](#technical-details).

If you write an internal comment to a ticket in Zendesk, it appears in YouTrack as a private comment visible to the project team.

### Technical Details

Behind Zendesk integration, there are two script packages:

* An import script pulls changes from Zendesk to YouTrack.

* A workflow propagates changes from YouTrack to Zendesk.

| Direction | Details |
| --- | --- |
|  Zendesk to YouTrack  |    Powered by the `@jetbrains/youtrack-zendesk-client/zendesk-integration-client` script package      Asynchronous. Changes from Zendesk get pulled to YouTrack periodically in small batches.     All data from Zendesk tickets gets pulled to YouTrack. For the full list of entities and their attributes that YouTrack imports from Zendesk, see [Imported Entities](import-from-zendesk.html#imported-entities).     |
|  YouTrack to Zendesk  |    Powered by the `Zendesk client` workflow package.      Synchronous. Changes from YouTrack get pulled to Zendesk immediately.     All changes from YouTrack get pulled to Zendesk with the following exceptions:       * Zendesk integration doesn't create any new tickets in Zendesk.    * Zendesk integration doesn't create any new user accounts in Zendesk.    |

## Available Actions

When you select a Zendesk integration from the list, the following actions are available:

| Action | Description |
| --- | --- |
| Edit | Edit the connection settings. |
| Delete | Delete the Zendesk integration and all the mappings. Tickets, users, and groups that are already imported remain in YouTrack. The links to Zendesk tickets are removed from tickets in YouTrack.  |

When you select a mapping from the list, the following actions are available:

| Action | Description |
| --- | --- |
| Edit | Edit the mapping settings. |
| Disable | Disable the mapping. The Zendesk integration is paused. No updates are synced between YouTrack and Zendesk. |
| Enable | Enable the mapping. The Zendesk integration is active again. Updates that were made while the integration was inactive are pulled into YouTrack. |
| Delete | Delete the mapping. Tickets, users, and groups that are already imported remain in YouTrack. |