> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zendesk

> Integration details and setup guide for the Zendesk connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                                                                                                    |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Authentication**                  | OAuth 2.0 or API Token (Basic Authentication)                                                                              |
| **Two-Way Sync**                    | Yes                                                                                                                        |
| **Events Supported**                | Yes (via Webhooks and Triggers)                                                                                            |
| **Realtime**                        | Yes (Webhooks)                                                                                                             |
| **Supports Rate Limiting**          | Yes (varies by plan: 200-700 requests/minute)                                                                              |
| **Authentication Scopes Supported** | `read`, `write`, `tickets:read`, `tickets:write`, `users:read`, `users:write`, `organizations:read`, `organizations:write` |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **Zendesk**:

* **Tickets** - Support tickets and comments
* **Users** - End-users and agents
* **Organizations** - Customer organizations
* **Groups** - Agent groups
* **Articles** - Knowledge base articles
* **Macros** - Ticket automation macros
* **Tags** - Ticket and object tags
* **Custom Fields** - Ticket custom fields

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                                       |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Offers free trial?**                             | Yes. Zendesk offers a 14-day free trial of Support and other products. [Start free trial](https://www.zendesk.com/register/) |
| **Requires paid sandbox**                          | No. Trial accounts can be used for development. Sandbox is available on certain plans.                                       |
| **Requires partnership to obtain authentication?** | No. Anyone can create a Zendesk account and generate API credentials.                                                        |

***

### Authentication (OAuth 2.0 or API Token)

For customers who want to completely whitelabel their OAuth experience, you can provide your own developer keys instead of using Alloy Automation's.

<step>
  ## Step 1: Create a Zendesk Account

  1. Visit **Zendesk** ([https://www.zendesk.com/](https://www.zendesk.com/))
  2. Click **Start free trial**
  3. Complete the registration form
  4. Verify your email
  5. Your Zendesk subdomain will be: `https://your-subdomain.zendesk.com`
</step>

<step>
  ## Step 2: Option A - Generate API Token (Simple)

  1. Log into your Zendesk instance as an admin
  2. Navigate to **Admin** > **Channels** > **API**
  3. Enable **Token Access**
  4. Click **Add API Token**
  5. Provide a description (e.g., "Alloy Integration")
  6. Click **Create**
  7. Copy the API token immediately—you won't be able to view it again
  8. Authentication format: `{email}/token:{api_token}` (Basic Auth)
</step>

<step>
  ## Step 3: Option B - Create OAuth App (Advanced)

  1. Log into your Zendesk instance as an admin
  2. Navigate to **Admin** > **Apps and integrations** > **APIs** > **OAuth Clients**
  3. Click **Add OAuth Client**
  4. Fill in the details:
     * **Client Name**: Your app name
     * **Description**: App description
     * **Redirect URLs**: `https://api.runalloy.com/api/strategy/connector/zendesk/callback`
     * **Company**: Your company name
  5. Select the required scopes:
     * `read` - Read access to all data
     * `write` - Write access to all data
     * Or select specific scopes (tickets, users, organizations)
  6. Click **Save**
  7. Copy the **Unique Identifier** (Client ID) and **Secret** (Client Secret)
</step>

<step>
  ## Step 4: Configure Alloy Automation

  **For API Token:**

  1. In Alloy Automation, configure your Zendesk connector
  2. Provide:
     * **Subdomain**: Your Zendesk subdomain
     * **Email**: Your Zendesk admin email
     * **API Token**: The token you generated
  3. Alloy will format this as Basic Auth: `{email}/token:{api_token}`

  **For OAuth:**

  1. Provide your **Client ID** and **Client Secret**
  2. Provide your **Subdomain**
  3. Initiate the OAuth flow
  4. Log in and authorize the application
</step>

***

## Use Cases

### 1) Omnichannel support ticket creation

Automatically create Zendesk tickets from customer inquiries received via email, chat, social media, or web forms, centralizing all support requests in one platform.

### 2) CRM and support integration

Sync customer data between Zendesk and CRM systems, enriching support tickets with account information, purchase history, and customer lifecycle data for better context.

### 3) Automated ticket routing and escalation

Route tickets to the right teams or agents based on customer attributes, ticket properties, or external data, and automatically escalate high-priority issues.

### 4) Knowledge base synchronization

Keep Zendesk knowledge base articles synchronized with external documentation systems, CMSs, or internal wikis, ensuring consistent support content across platforms.

### 5) Post-resolution workflows

Trigger follow-up actions when tickets are resolved—send satisfaction surveys, update CRM records, create billing adjustments, or notify stakeholders automatically.

***

## API Gotchas

* **Rate Limiting by Plan:** Zendesk enforces rate limits that vary by plan (Team: 200/min, Professional: 400/min, Enterprise: 700/min). Monitor the `X-Rate-Limit` headers and implement exponential backoff for 429 responses.

* **Subdomain Required:** All Zendesk API requests must include your subdomain in the URL (e.g., `https://your-subdomain.zendesk.com/api/v2/`). Ensure you're using the correct subdomain for your instance.

* **Incremental API for Exports:** When exporting large datasets (tickets, users), use the Incremental Export API. It's optimized for bulk exports and uses a `start_time` parameter to fetch changes since a specific timestamp.

* **Side-Loading Related Objects:** Zendesk supports side-loading to include related objects in a single request (e.g., `?include=users,groups`). This reduces API calls but increases response size. Use judiciously.

* **Custom Fields Require IDs:** Zendesk custom fields are identified by numeric IDs, not names. When creating or updating tickets with custom fields, use the field ID (e.g., `custom_fields: [{id: 123456, value: "foo"}]`).

* **Pagination with Cursors:** Zendesk uses cursor-based pagination for most list endpoints. Use the `next_page` or `after_cursor` values from responses to paginate. Offset-based pagination is deprecated for most endpoints.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.