---
title: "Zendesk Connector"
description: "Complete Zendesk integration guide for syncing tickets, users, organizations, and support events with Brevo via Tajo."
url: https://tajo.io/docs/connectors/support/zendesk/
markdown: https://tajo.io/docs/connectors/support/zendesk.md
lang: en-US
robots: noindex
---

# Zendesk Connector

Connector status: Planned Not built yet. Tajo does not run this connector today.

| Source field | Destination field | Sample value |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Connect your Zendesk Support instance to Brevo via Tajo for unified customer support data, ticket-based segmentation, satisfaction scoring, and support-triggered marketing automation.

## Overview

| Property | Value |
| --- | --- |
| **Platform** | Zendesk |
| **Category** | Support |
| **Setup Complexity** | Medium |
| **Official Integration** | No |
| **Data Synced** | Tickets, Users, Organizations, Events |
| **API Base URL** | `https://{subdomain}.zendesk.com/api/v2` |

## Features

- **User sync** - Sync Zendesk end-users and agents with Brevo contacts
- **Ticket tracking** - Sync ticket data for support-aware marketing segmentation
- **Organization mapping** - Associate contacts with organizations for B2B workflows
- **Satisfaction scores** - Sync CSAT and NPS data to Brevo attributes
- **Ticket events** - Track ticket creation, resolution, and escalation for automation triggers
- **Help center integration** - Track article views and search behavior
- **Multi-channel support** - Sync data from email, chat, voice, and messaging channels
- **Custom fields** - Map Zendesk custom ticket and user fields to Brevo

## Prerequisites

Before you begin, ensure you have:

1. A Zendesk Support account (Team, Professional, or Enterprise)
2. Admin access to your Zendesk instance
3. API token or OAuth app configured
4. A Brevo account with API access
5. A Tajo account

## Authentication

### API Token Authentication

Use email/token authentication for quick setup.

```bash
curl https://{subdomain}.zendesk.com/api/v2/users.json \
  -u {email}/token:{api_token} \
  -H "Content-Type: application/json"
```

Generate an API token from Zendesk Admin > Apps and Integrations > APIs > Zendesk API.

### OAuth 2.0

Use OAuth for multi-instance integrations with delegated user access.

```bash
# Authorization URL
https://{subdomain}.zendesk.com/oauth/authorizations/new?
  response_type=code&
  client_id={client_id}&
  redirect_uri={redirect_uri}&
  scope=read%20write
```

#### Required Scopes

```
read          # Read access to all resources
write         # Write access to all resources
tickets:read  # Read tickets (granular)
users:read    # Read users (granular)
organizations:read  # Read organizations (granular)
```

## Configuration

### Basic Setup

```yaml
connectors:
  zendesk:
    enabled: true
    subdomain: "yourcompany"
    auth:
      email: "admin@yourcompany.com"
      api_token: "${ZENDESK_API_TOKEN}"

    # Data sync options
    sync:
      users: true
      tickets: true
      organizations: true
      satisfaction_ratings: true

    # Brevo list assignment
    lists:
      all_customers: 30
      active_tickets: 31
      satisfied_customers: 32
```

### Field Mapping

Map Zendesk user fields to Brevo contact attributes:

#### Default Mappings

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | User email address (unique identifier) |
| `name` optional | string | Full name, split into FIRSTNAME/LASTNAME |
| `phone` optional | string | Maps to SMS attribute for WhatsApp/SMS |
| `organization_id` optional | integer | Associated organization for B2B mapping |
| `role` optional | string | User role (end-user, agent, admin) |
| `tags` optional | array | User tags from Zendesk |
| `ticket_restriction` optional | string | Ticket access level |
| `custom_fields` optional | object | Custom user field values |

#### Custom Field Mapping

```yaml
field_mapping:
  # Standard fields
  email: email
  name: FULLNAME
  phone: SMS

  # Support metrics
  open_tickets: OPEN_TICKETS
  total_tickets: TOTAL_TICKETS
  avg_satisfaction: CSAT_SCORE
  last_ticket_date: LAST_SUPPORT_DATE

  # Organization fields
  organization.name: COMPANY_NAME
  organization.tags: COMPANY_TAGS

  # Custom fields
  user_fields.customer_type: CUSTOMER_TYPE
  user_fields.account_tier: ACCOUNT_TIER
```

## API Endpoints

### Ticketing API

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/api/v2/tickets` | List tickets |
| `POST` | `/api/v2/tickets` | Create a ticket |
| `PUT` | `/api/v2/tickets/{id}` | Update a ticket |
| `GET` | `/api/v2/tickets/{id}` | Show a ticket |
| `GET` | `/api/v2/search.json?query={query}` | Search tickets |

### Users API

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/api/v2/users` | List users |
| `POST` | `/api/v2/users` | Create a user |
| `PUT` | `/api/v2/users/{id}` | Update a user |
| `GET` | `/api/v2/users/{id}` | Show a user |
| `GET` | `/api/v2/users/search.json?query={query}` | Search users |

### Organizations API

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/api/v2/organizations` | List organizations |
| `POST` | `/api/v2/organizations` | Create an organization |
| `GET` | `/api/v2/organizations/{id}/users` | List organization members |

### Satisfaction Ratings API

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/api/v2/satisfaction_ratings` | List satisfaction ratings |
| `GET` | `/api/v2/satisfaction_ratings/{id}` | Show a rating |

## Events

### Ticket Events

| Event | Trigger | Use Case |
| --- | --- | --- |
| `ticket.created` | New ticket submitted | Support acknowledgment |
| `ticket.updated` | Ticket status changed | Status notification |
| `ticket.solved` | Ticket marked solved | CSAT survey trigger |
| `ticket.reopened` | Solved ticket reopened | Escalation alert |

### User Events

| Event | Trigger | Use Case |
| --- | --- | --- |
| `user.created` | New user registered | Welcome to support |
| `user.updated` | User profile changed | Attribute sync |
| `user.merged` | Users merged | Deduplication |

### Satisfaction Events

| Event | Trigger | Use Case |
| --- | --- | --- |
| `satisfaction_rating.created` | CSAT submitted | Feedback processing |
| `satisfaction_rating.bad` | Negative rating | Recovery outreach |
| `satisfaction_rating.good` | Positive rating | Advocacy campaigns |

## Code Examples

### Initialize Connector

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Zendesk
await tajo.connectors.connect('zendesk', {
  subdomain: 'yourcompany',
  email: 'admin@yourcompany.com',
  apiToken: process.env.ZENDESK_API_TOKEN
});
```

### Sync Users and Tickets

```javascript
// Full sync of users and ticket data
await tajo.connectors.sync('zendesk', {
  type: 'full',
  resources: ['users', 'tickets', 'organizations'],
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('zendesk');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   usersSynced: 8400,
//   ticketsSynced: 34200,
//   organizationsSynced: 1200
// }
```

### Handle Zendesk Webhooks

```javascript
app.post('/webhooks/zendesk', async (req, res) => {
  const signature = req.get('X-Zendesk-Webhook-Signature');

  // Verify webhook signature
  if (!verifyZendeskSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  await tajo.connectors.handleWebhook('zendesk', {
    type: req.body.type,
    ticketId: req.body.ticket_id,
    userId: req.body.user_id,
    payload: req.body
  });

  res.status(200).send('OK');
});
```

## Rate Limits

Zendesk rate limits vary by plan:

| Plan | Rate Limit | Details |
| --- | --- | --- |
| Team | 200 requests/minute | Per API token |
| Professional | 400 requests/minute | Per API token |
| Enterprise | 700 requests/minute | Per API token |
| High Volume Add-on | 2,500 requests/minute | Per API token |

Additional limits:

- **Search API**: 6 requests/minute for anonymous, 100/minute for authenticated
- **Incremental exports**: 10 requests/minute
- **Batch API**: 100 records per batch request
- **Webhook delivery**: Automatic retry with exponential backoff

Rate Limit Headers

Monitor the `X-Rate-Limit-Remaining` and `Retry-After` headers to manage your API usage.

## Troubleshooting

### Common Issues

| Issue | Cause | Solution |
| --- | --- | --- |
| 401 Unauthorized | Invalid API token | Regenerate token in Zendesk Admin |
| 403 Forbidden | Insufficient permissions | Check agent or admin role requirements |
| User not synced | User is an agent, not end-user | Filter by role in sync configuration |
| Webhook not received | Trigger/target not configured | Set up webhook target in Zendesk Admin |
| Search returns empty | Indexing delay | Wait 1-2 minutes for search index update |

### Debug Mode

Enable verbose logging:

```yaml
connectors:
  zendesk:
    debug: true
    log_level: verbose
    log_webhooks: true
```

### Test Connection

```bash
tajo connectors test zendesk
# ✓ API connection successful
# ✓ Users readable
# ✓ Tickets readable
# ✓ Organizations readable
# ✓ Webhooks configured
```

## Best Practices

1. **Use incremental exports** - Use the Incremental API for large-scale data sync
2. **Filter end-users only** - Exclude agents and admins from Brevo contact sync
3. **Sync CSAT data** - Use satisfaction scores for customer health segmentation
4. **Map organizations** - Leverage organization data for B2B marketing campaigns
5. **Implement webhook retries** - Handle temporary failures gracefully
6. **Use side-loading** - Include related records in API responses to reduce request count

## Security

- **API Token Authentication** - Token-based access tied to admin email
- **OAuth 2.0** - Token-based delegated access with scope controls
- **Webhook signing** - HMAC signature verification for webhook payloads
- **TLS encryption** - All API communication encrypted via HTTPS
- **IP whitelisting** - Restrict API access by IP range

## Related Resources

- [Zendesk API Documentation](https://developer.zendesk.com/api-reference)
- [Zendesk Webhooks Guide](https://developer.zendesk.com/api-reference/webhooks/introduction/)
- [Intercom Connector](https://tajo.io/docs/connectors/support/intercom)
- [Customer Sync Skill](https://tajo.io/docs/skills/data-sync/customer-sync)
- [Brevo Contacts API](https://tajo.io/docs/contact-management)

## Open-Source Implementation Map

No official open-source repository was found in the current Tajo connector catalog for Zendesk. Keep this page focused on the verified public API contract and vendor documentation until an official schema, SDK, MCP server, or public integration repository is available.

### Tajo Revamp Checklist

- Verify authentication and scope requirements against the vendor documentation before each connector release.
- Document primary sync objects, external IDs, pagination strategy, and rate limits explicitly.
- Add smoke tests from public API examples rather than undocumented behavior.
- Capture webhook signature verification and replay protection when the vendor supports webhooks.
- Record gaps where no official public repository or schema exists so future maintainers know what still needs source-backed validation.