Zendesk Loader
The Zendesk loader pulls support ticket, user, and organization data from your Zendesk Support instance into your data warehouse. It uses Zendesk’s Incremental Exports API for efficient, cursor-based data extraction.
Prerequisites
- A Zendesk Support account (Team, Professional, or Enterprise plan)
- A Zendesk user with Admin or Agent role
- A connected Warehouse (target warehouse) with write permissions on the target schema
Authentication
The Zendesk loader uses API Token authentication.
Obtaining an API Token
- Log in to your Zendesk Support admin panel
- Navigate to Admin > Channels > API
- Enable Token Access if not already enabled
- Click Add API Token
- Give the token a description (e.g., “SignalSmith Loader”)
- Copy the generated token
- In SignalSmith, enter the following:
| Field | Description | Example |
|---|---|---|
| Subdomain | Your Zendesk subdomain | mycompany (from mycompany.zendesk.com) |
| The email address of the Zendesk user | admin@mycompany.com | |
| API Token | The generated API token | aBcDeFgHiJkLmNoPqRsTuVwXyZ |
SignalSmith authenticates using the {email}/token:{api_token} format as specified by Zendesk’s API.
Custom Domain
If your Zendesk instance uses a custom domain (e.g., support.mycompany.com instead of mycompany.zendesk.com), enter the full custom domain in the subdomain field.
Available Objects
| Object | API Name | Description | Default Sync Mode |
|---|---|---|---|
| Tickets | tickets | Support tickets with subject, description, status, and custom fields | Incremental |
| Users | users | End users, agents, and admins in your Zendesk instance | Incremental |
| Organizations | organizations | Customer organizations that group users | Incremental |
| Ticket Comments | ticket_comments | Individual comments/replies on tickets (public and internal) | Incremental |
| Ticket Metrics | ticket_metrics | SLA and performance metrics per ticket (first reply time, resolution time) | Incremental |
| Ticket Fields | ticket_fields | Custom field definitions | Full Refresh |
| Groups | groups | Agent groups for ticket routing | Full Refresh |
| Brands | brands | Brand/subdomain configurations (multi-brand setups) | Full Refresh |
| Tags | tags | Tag definitions used across tickets, users, and organizations | Full Refresh |
| Satisfaction Ratings | satisfaction_ratings | CSAT survey responses | Incremental |
Ticket Comments
Ticket comments are extracted as a separate table with a foreign key to the parent ticket. This includes both public replies visible to the customer and internal notes visible only to agents. The public field distinguishes between the two.
Custom Fields
Zendesk custom fields on tickets are extracted as additional columns in the tickets table. The column name is derived from the field’s API name (e.g., custom_field_12345). The ticket_fields object provides the human-readable labels for mapping.
Configuration
| Setting | Description | Default |
|---|---|---|
| Subdomain | Your Zendesk subdomain or custom domain | — (required) |
| Zendesk user email for authentication | — (required) | |
| API Token | Zendesk API token | — (required) |
| Objects | List of objects to sync | — (you choose during setup) |
| Sync Mode | Full Refresh or Incremental (per object) | Incremental |
| Primary Key | Field(s) that uniquely identify a record | id |
| Target Schema | Warehouse schema for Zendesk tables | — (required) |
| Table Prefix | Optional prefix for table names | zd_ |
| Schedule | Sync frequency | Hourly |
Scheduling Notes
- Incremental Exports API: For tickets, users, and organizations, SignalSmith uses Zendesk’s dedicated Incremental Exports API, which is designed for bulk data extraction. This is more efficient than listing endpoints and provides a reliable cursor for incremental sync.
- Rate limits: Zendesk enforces rate limits of 400 requests per minute for most endpoints. The Incremental Exports API has a separate limit of 10 requests per minute but returns up to 1,000 records per request. SignalSmith handles these limits with automatic backoff.
- Cursor persistence: The incremental export cursor is a Unix timestamp. SignalSmith persists this between runs, so each execution picks up records modified after the last successful sync.
- Deleted tickets: Zendesk’s Incremental Exports API includes soft-deleted tickets. These are marked with
status: "deleted"in your warehouse. Permanently deleted tickets are not included. - Archived tickets: On Enterprise plans, tickets older than 120 days are archived. Archived tickets are included in the initial backfill but may not appear in incremental exports. Run a periodic full refresh if you need to capture archived ticket updates.
Schema Mapping
Zendesk field types are mapped to warehouse-compatible types:
| Zendesk Type | Warehouse Type | Notes |
|---|---|---|
integer | BIGINT | IDs, numeric custom fields |
string | VARCHAR | |
text | TEXT / VARCHAR | Long text fields like descriptions |
boolean | BOOLEAN | |
date | DATE | |
datetime | TIMESTAMP | UTC normalized from ISO 8601 |
array | JSON / VARCHAR | Tags, collaborator IDs |
object | JSON / VARCHAR | Nested structures like via, satisfaction_rating |
tagger | VARCHAR | Custom dropdown fields |
Troubleshooting
| Issue | Solution |
|---|---|
| ”401 Couldn’t authenticate you” | Verify the email, API token, and subdomain are correct. Ensure the email includes /token format is handled by SignalSmith |
| ”403 Forbidden” | The authenticated user may lack permission to access the requested resource. Use an Admin account |
| ”429 Too Many Requests” | SignalSmith handles rate limits automatically. If this persists, reduce the number of objects or sync frequency |
| Missing custom fields on tickets | Custom fields appear as custom_field_{id} columns. Join with the ticket_fields table to get human-readable names |
| Ticket comments not appearing | Ticket comments are a separate object. Ensure you’ve selected “Ticket Comments” in addition to “Tickets” |
| Old tickets missing after incremental sync | Archived tickets may not appear in incremental exports. Schedule a periodic full refresh to capture these |
| Subdomain not recognized | Verify the subdomain matches your Zendesk URL (e.g., mycompany from mycompany.zendesk.com) |
Next Steps
- Create a model to transform your raw Zendesk data
- Build customer support dashboards by joining tickets, users, and organizations
- Combine support data with CRM data for a unified customer view