> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/it-service-management/zendesk.md).
# Zendesk
Zendesk is a customer service and support ticketing platform that helps organizations manage customer interactions across multiple channels. Connecting Zendesk to Harmony enables bidirectional ticket synchronization, AI-powered resolution, and seamless migration from traditional support workflows to autonomous IT operations.
### What the Zendesk integration enables
| Capability | Description |
| ---------------------- | ---------------------------------------------------------------------------------- |
| Ticket Synchronization | Sync tickets bidirectionally between Zendesk and Harmony |
| AI-Powered Resolution | Leverage Harmony's AI to automatically resolve Zendesk tickets |
| SLA Monitoring | Track and maintain SLA compliance across both platforms |
| User & Role Inventory | Surface Zendesk agents and admins, with their roles and account status, in Harmony |
| Sign-In Activity | Track when agents and admins last signed in to Zendesk |
### Prerequisites
Before configuring the Zendesk integration, ensure you have:
* **Zendesk Administrator Access**: An admin account that can create API tokens in Zendesk Admin Center
* **Zendesk API Token**: Created in Admin Center (see Step 2 below)
* **Harmony Account**: Active Harmony workspace with integration permissions
### Connect Zendesk to Harmony
You can now connect Harmony to your Zendesk account, bringing your customer support workflows together in one place. Once connected, Harmony works alongside your existing Zendesk setup to streamline how your team handles support requests.
#### Step 1: Navigate to Integrations
1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **Zendesk** under **IT Service Management** and click **Connect**
#### Step 2: Generate a Zendesk API Token
1. Log in to Zendesk with an administrator account
2. Open **Admin Center** and go to **Apps and integrations** > **APIs** > **Zendesk API**
3. Add a new API token and give it a description (for example, `Harmony`)
4. Copy the token and keep it somewhere safe until you paste it into Harmony
{% hint style="warning" %}
A Zendesk API token works as a password and can be used to act as anyone in the account, including admins. Keep it secure, and delete it in Zendesk if you suspect it has been compromised. Deleting a token deactivates it permanently.
{% endhint %}
#### Step 3: Enter Credentials in Harmony
1. Enter your **Company subdomain** (e.g., `mycompany` from `mycompany.zendesk.com`)
2. Paste your **API token**
3. Enter the **Admin email** of the Zendesk account the token belongs to
4. Click **Connect**
{% hint style="info" %}
Zendesk now marks API tokens as deprecated and recommends migrating to OAuth access tokens. API token authentication is still supported by Zendesk and is what the Harmony integration uses today; Zendesk has not announced a shutdown date.
{% endhint %}
### What Harmony Syncs
**From Zendesk:**
* Agent and admin users (name, email, role, and account status)
* Custom role names, for agents who hold one (Zendesk custom roles require an Enterprise plan)
* Seat status - agents and admins are counted as paid seats
* Sign-in activity, derived from each user's last sign-in timestamp
End users - the customers who submit tickets - are not included in the user inventory. Harmony collects agents and admins only.
User inventory is refreshed every 6 hours, and sign-in activity every hour.
{% hint style="info" %}
Sign-in activity records the user and the time of their most recent sign-in. Zendesk's user record does not expose an IP address for the sign-in, so Harmony does not report one for Zendesk.
{% endhint %}
### Troubleshooting
Tickets Not Syncing
**Issue**: Tickets created in Zendesk don't appear in Harmony
**Solutions**:
* Verify the API token still exists in Zendesk - tokens do not expire, but deleting one deactivates it permanently
* Confirm the **Admin email** entered in Harmony belongs to an active Zendesk admin account
* Check webhook configuration for real-time sync
* Review sync filters and ensure tickets meet criteria
* Confirm network connectivity between systems
Duplicate Tickets
**Issue**: Same ticket appears multiple times in either system
**Solutions**:
* Check custom field mapping for unique identifiers
* Verify webhook triggers aren't duplicated
* Review sync direction settings
* Disable and re-enable integration if necessary
Status Mapping Errors
**Issue**: Ticket statuses don't match between systems
**Solutions**:
* Review status mapping configuration
* Ensure all Zendesk statuses are mapped to Harmony equivalents
* Check for custom statuses that need manual mapping
* Test with a sample ticket to verify behavior
API Rate Limiting
**Issue**: Integration slows down or fails intermittently
**Solutions**:
* Zendesk enforces account-wide API rate limits per plan - for Zendesk Suite: Team 200, Growth 400, Professional 400, Enterprise 700, and Enterprise Plus 2500 requests per minute
* Zendesk's incremental export endpoints, which Harmony uses to read your user list, have their own global limit of 10 requests per minute (30 with the High Volume API add-on)
* Harmony honors Zendesk's rate-limit responses and retries automatically, so short bursts of throttling resolve on their own
* Contact Zendesk about the High Volume API add-on if you consistently hit limits
### Best Practices
Ticket Management
* **Status Consistency**: Maintain consistent status definitions across both platforms
* **Priority Alignment**: Ensure priority levels mean the same thing in both systems
* **SLA Preservation**: Configure SLAs in Harmony to match or exceed Zendesk SLAs
* **Tag Standardization**: Use consistent tagging across both platforms
Performance Optimization
* **Selective Sync**: Only sync tickets that require dual visibility
* **Webhook Usage**: Use webhooks for real-time updates instead of polling
* **Batch Processing**: Process bulk operations during off-hours
* **Archive Strategy**: Archive old tickets to reduce sync overhead
User Experience
* **Clear Communication**: Inform users about which platform to use for different request types
* **Consistent Branding**: Maintain consistent language and branding across both platforms
* **Training**: Provide training on when to use Zendesk vs. Harmony
* **Feedback Loop**: Collect user feedback on the hybrid experience
Migration Strategy
* **Phased Approach**: Migrate ticket types gradually rather than all at once
* **Pilot Program**: Start with a small team or department
* **Success Metrics**: Define clear KPIs for migration success
* **Rollback Plan**: Maintain ability to revert if issues arise
### Data & Privacy
Data Handling
* All ticket data is encrypted in transit (TLS 1.2+) and at rest (AES-256)
* Harmony stores minimal ticket metadata; full ticket content remains in Zendesk
* Personal information is processed according to GDPR and privacy regulations
* Data retention policies can be configured to match your compliance requirements
Compliance
* **GDPR**: Full data subject rights support including access, deletion, and portability
* **SOC 2 Type II**: Both Zendesk and Harmony maintain SOC 2 certification
* **HIPAA**: Available for healthcare organizations (requires Business Associate Agreement)
* **PCI DSS**: Payment data is never stored; compliant with credit card handling requirements
Access Control
* Harmony respects Zendesk's role-based access control
* Zendesk API tokens cannot be scoped - they authenticate as the admin account whose email you configured, so use an account whose permissions match the access you intend to grant
* Audit logs track all integration activities
* Integration can be disabled instantly if security concerns arise
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.harmony.io/integrations/it-service-management/zendesk.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.