Zendesk Connector

The Zendesk connector ingests support tickets, ticket comments, and Help Center articles from Zendesk Support into CortexDB as typed episodes. Internal notes are tracked separately from public comments with appropriate visibility controls.

Setup

1. Create a Zendesk API Token

1. In Zendesk Admin Center, go to Apps and integrations > APIs > Zendesk API
2. Enable Token Access
3. Click Add API token and copy the generated token

2. Configure the Connector

export CORTEX_ZENDESK_SUBDOMAIN=mycompany
export [email protected]
export CORTEX_ZENDESK_API_TOKEN=your-api-token
export CORTEX_ZENDESK_TENANT_ID=my-app
export CORTEX_ZENDESK_NAMESPACE=zendesk

3. Start the Connector

cortexdb-connector zendesk \
  --subdomain mycompany \
  --email [email protected] \
  --api-token your-api-token \
  --tenant-id my-app

Or with Docker:

docker run -d \
  --name cortex-zendesk \
  -e CORTEX_ZENDESK_SUBDOMAIN=mycompany \
  -e [email protected] \
  -e CORTEX_ZENDESK_API_TOKEN=your-api-token \
  -e CORTEX_ZENDESK_TENANT_ID=my-app \
  cortexdb/connector-zendesk:latest

What Gets Ingested

| Zendesk Event | Episode Type | Content | |---|---|---| | Ticket | issue | Subject, description, status, priority | | Public comment | comment | Comment body text | | Internal note | comment | Note body text (restricted visibility) | | Help Center article | document | Article title and body |

Episode Metadata

{
  "type": "issue",
  "content": "Ticket [open] [high]: Cannot access billing portal\nUser reports receiving 403 when attempting to access the billing section...",
  "source": "zendesk",
  "timestamp": "2026-03-17T09:22:00Z",
  "metadata": {
    "zendesk_ticket_id": 54321,
    "status": "open",
    "priority": "high",
    "type": "problem",
    "group_id": 1234567,
    "assignee_id": 9876543
  },
  "entities": [
    { "type": "ticket", "id": "54321", "name": "Cannot access billing portal" },
    { "type": "organization", "id": "112233", "name": "112233" },
    { "type": "user", "id": "9876543", "name": "9876543" }
  ]
}

Configuration

| Variable | Default | Description | |---|---|---| | CORTEX_ZENDESK_SUBDOMAIN | Required | Zendesk subdomain | | CORTEX_ZENDESK_EMAIL | Required | Agent email for API auth | | CORTEX_ZENDESK_API_TOKEN | Required | Zendesk API token | | CORTEX_ZENDESK_TENANT_ID | Required | Target tenant | | CORTEX_ZENDESK_NAMESPACE | zendesk | Target namespace | | CORTEX_ZENDESK_BACKFILL_DAYS | 90 | Days of history to backfill | | CORTEX_ZENDESK_INCLUDE_HELP_CENTER | false | Include Help Center articles | | CORTEX_ZENDESK_POLL_INTERVAL_SEC | 60 | Polling interval |

Backfill

On first run, the connector backfills tickets updated within the last CORTEX_ZENDESK_BACKFILL_DAYS days (default 90) using Zendesk's incremental cursor-based export API. Comments are fetched per-ticket. Help Center articles use the standard paginated list endpoint with date filtering. Rate limits (429 responses) are handled with automatic retry using the Retry-After header.