Agent skill

zendesk

Zendesk API for customer support. Use when user mentions "Zendesk", "support ticket", "customer service", or help desk.

View SKILL.md on GitHub Repository
Stars 50
Forks 8

Install this agent skill to your Project

npx add-skill https://github.com/vm0-ai/vm0-skills/tree/main/zendesk

SKILL.md

Zendesk API

Manage customer support tickets, users, organizations, and support operations via the Zendesk Support REST API.

Official docs: https://developer.zendesk.com/api-reference/

When to Use

Use this skill when you need to:

  • Manage tickets - Create, update, search, and close support tickets
  • Handle users - Create end-users, agents, and manage user profiles
  • Organize accounts - Manage organizations and their members
  • Support groups - Create and manage agent groups for ticket routing
  • Search data - Find tickets, users, and organizations with powerful search
  • Bulk operations - Create or update multiple resources at once
  • Automate support - Build integrations and automate workflows
  • Track metrics - Access ticket data for reporting and analytics

Prerequisites

Getting Your API Token

⚠️ Important: You must enable Token Access before creating tokens.

  1. Log in to Zendesk Admin Center (admin access required)
  2. Navigate to Apps and integrations → APIs → Zendesk API
  3. Click the Settings tab
  4. Under Token Access, toggle Enabled (this is required!)
  5. Click Add API token
  6. Enter a description (e.g., "VM0 Integration")
  7. Click Save and copy the token immediately (shown only once)
bash
export ZENDESK_EMAIL="your-email@company.com"
export ZENDESK_API_TOKEN="your_api_token"
export ZENDESK_SUBDOMAIN="yourcompany"

Find Your Subdomain

Your subdomain is in your Zendesk URL:

https://yourcompany.zendesk.com
         ^^^^^^^^^^^
         subdomain

Verify Token

Test your credentials:

bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" | jq '{count: .count, tickets: .tickets | length}

Expected response: Ticket count and list

Alternative verification (list users):

bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/users.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" | jq '.users[] | {id, name, email, role}

Note: The /users/me.json endpoint may return anonymous user for API token authentication. Use /tickets.json or /users.json to verify token validity.

✅ This skill has been tested and verified with a live Zendesk workspace. All core endpoints work correctly.

How to Use

All examples assume environment variables are set.

Base URL: https://{subdomain}.zendesk.com/api/v2/

Authentication: API Token via -u flag

bash
-u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)"

Note: The -u flag automatically handles Base64 encoding for you.

Core APIs

1. List Tickets

Get all tickets (paginated):

bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" | jq '.tickets[] | {id, subject, status, priority}

With pagination:

bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets.json?page=1&per_page=50" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)"

2. Get Ticket

Retrieve a specific ticket:

bash
TICKET_ID="123"

curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets/${TICKET_ID}.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)"

3. Create Ticket

Create a new support ticket:

Write to /tmp/zendesk_request.json:

json
{
  "ticket": {
    "subject": "My printer is on fire!",
    "comment": {
      "body": "The smoke is very colorful."
    },
    "priority": "urgent"
  }
}

Then run:

bash
curl -s -X POST "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

Create ticket with more details:

Write to /tmp/zendesk_request.json:

json
{
  "ticket": {
    "subject": "Need help with account",
    "comment": {
      "body": "I cannot access my account settings."
    },
    "priority": "high",
    "status": "open",
    "type": "problem",
    "tags": ["account", "access"]
  }
}

Then run:

bash
curl -s -X POST "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

4. Update Ticket

Update an existing ticket:

bash
TICKET_ID="123"

Write to /tmp/zendesk_request.json:

json
{
  "ticket": {
    "status": "solved",
    "comment": {
      "body": "Issue has been resolved. Thank you!",
      "public": true
    }
  }
}

Then run:

bash
curl -s -X PUT "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

Change priority and assignee:

bash
TICKET_ID="123"
ASSIGNEE_ID="456"

Write to /tmp/zendesk_request.json:

json
{
  "ticket": {
    "priority": "high",
    "assignee_id": ASSIGNEE_ID_PLACEHOLDER
  }
}

Then run:

bash
sed -i '' "s/ASSIGNEE_ID_PLACEHOLDER/${ASSIGNEE_ID}/" /tmp/zendesk_request.json

curl -s -X PUT "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

5. Delete Ticket

Permanently delete a ticket:

bash
TICKET_ID="123"

curl -s -X DELETE "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets/${TICKET_ID}.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)"

6. Create Multiple Tickets

Bulk create tickets:

Write to /tmp/zendesk_request.json:

json
{
  "tickets": [
    {
      "subject": "Ticket 1",
      "comment": {
        "body": "First ticket"
      }
    },
    {
      "subject": "Ticket 2",
      "comment": {
        "body": "Second ticket"
      }
    }
  ]
}

Then run:

bash
curl -s -X POST "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets/create_many.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

7. List Users

Get all users:

bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/users.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" | jq '.users[] | {id, name, email, role}

8. Get Current User

Get authenticated user details:

bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/users/me.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)"

9. Create User

Create an end-user:

Write to /tmp/zendesk_request.json:

json
{
  "user": {
    "name": "John Customer",
    "email": "john@example.com",
    "role": "end-user"
  }
}

Then run:

bash
curl -s -X POST "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/users.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

Create an agent:

Write to /tmp/zendesk_request.json:

json
{
  "user": {
    "name": "Jane Agent",
    "email": "jane@company.com",
    "role": "agent"
  }
}

Then run:

bash
curl -s -X POST "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/users.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

10. Update User

Update user information:

bash
USER_ID="456"

Write to /tmp/zendesk_request.json:

json
{
  "user": {
    "name": "Updated Name",
    "phone": "+1234567890"
  }
}

Then run:

bash
curl -s -X PUT "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/users/${USER_ID}.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

11. Search Users

Search for users by query:

bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/users/search.json?query=john" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" | jq '.users[] | {id, name, email}

12. List Organizations

Get all organizations:

bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/organizations.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" | jq '.organizations[] | {id, name, domain_names}

13. Create Organization

Create a new organization:

Write to /tmp/zendesk_request.json:

json
{
  "organization": {
    "name": "Acme Inc",
    "domain_names": ["acme.com", "acmeinc.com"],
    "details": "Important customer"
  }
}

Then run:

bash
curl -s -X POST "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/organizations.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

14. Update Organization

Update organization details:

bash
ORG_ID="789"

Write to /tmp/zendesk_request.json:

json
{
  "organization": {
    "name": "Acme Corporation",
    "notes": "Premium customer since 2020"
  }
}

Then run:

bash
curl -s -X PUT "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/organizations/${ORG_ID}.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

15. List Groups

Get all agent groups:

bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/groups.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" | jq '.groups[] | {id, name}

16. Create Group

Create a new agent group:

Write to /tmp/zendesk_request.json:

json
{
  "group": {
    "name": "Support Team"
  }
}

Then run:

bash
curl -s -X POST "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/groups.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

17. Search API

Search for open tickets:

Write to /tmp/zendesk_query.txt:

type:ticket status:open
bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/search.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[] | {id, subject, status}

Search for high priority tickets:

bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/search.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[]

Search tickets with keywords:

bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/search.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[]

Search users by email domain:

bash
curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/search.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[]

18. Get Ticket Comments

List all comments on a ticket:

bash
TICKET_ID="123"

curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets/${TICKET_ID}/comments.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" | jq '.comments[] | {id, body, author_id, public}

19. Assign Ticket to Group

Assign a ticket to a group:

bash
TICKET_ID="123"
GROUP_ID="456"

Write to /tmp/zendesk_request.json:

json
{
  "ticket": {
    "group_id": GROUP_ID_PLACEHOLDER
  }
}

Then run:

bash
sed -i '' "s/GROUP_ID_PLACEHOLDER/${GROUP_ID}/" /tmp/zendesk_request.json

curl -s -X PUT "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

20. Bulk Update Tickets

Update multiple tickets at once:

Write to /tmp/zendesk_request.json:

json
{
  "ticket": {
    "status": "solved"
  }
}

Then run:

bash
curl -s -X PUT "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets/update_many.json?ids=123,124,125" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

Common Workflows

Create Ticket and Assign to Agent

Write to /tmp/zendesk_request.json:

json
{
  "ticket": {
    "subject": "New issue",
    "comment": {
      "body": "Need help"
    }
  }
}

Then run:

bash
# Create ticket
TICKET_RESPONSE=$(curl -s -X POST "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json)

TICKET_ID=$(echo $TICKET_RESPONSE | jq -r '.ticket.id')

# Assign to agent
ASSIGNEE_ID="789"

Write to /tmp/zendesk_request.json:

json
{
  "ticket": {
    "assignee_id": ASSIGNEE_ID_PLACEHOLDER,
    "status": "open"
  }
}

Then run:

bash
sed -i '' "s/ASSIGNEE_ID_PLACEHOLDER/${ASSIGNEE_ID}/" /tmp/zendesk_request.json

curl -s -X PUT "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

Find and Close Old Tickets

bash
# Search for old open tickets (30+ days)
OLD_TICKETS="$(curl -s "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/search.json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq -r '.results[].id' | paste -sd "," -)"

Write to /tmp/zendesk_request.json:

json
{
  "ticket": {
    "status": "closed"
  }
}

Then run:

bash
# Bulk close them
curl -s -X PUT "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets/update_many.json?ids=${OLD_TICKETS}" -H "Content-Type: application/json" -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" -d @/tmp/zendesk_request.json

Search Query Syntax

Ticket Search Operators

  • type:ticket - Search tickets only
  • status:open - Filter by status (open, pending, solved, closed)
  • priority:high - Filter by priority (low, normal, high, urgent)
  • assignee:name - Find tickets assigned to specific agent
  • group:name - Find tickets in specific group
  • tags:keyword - Search by tag
  • created>2024-01-01 - Created after date
  • created<30 - Created in last 30 days
  • "exact phrase" - Search exact text

User Search Operators

  • type:user - Search users only
  • role:agent - Filter by role (end-user, agent, admin)
  • email:*@domain.com - Search by email domain
  • name:john - Search by name

Combining Operators

Use spaces for AND logic:

bash
query=type:ticket status:open priority:high

Rate Limits

Plan Requests/Minute
Team 200
Growth 400
Professional 400
Enterprise 700
Enterprise Plus 2,500

Special Limits:

  • Update Ticket: 30 updates per 10 minutes per user per ticket
  • Account-wide ceiling: 100,000 requests/minute

Rate Limit Headers

X-Rate-Limit: 700                    # Your account's limit
X-Rate-Limit-Remaining: 685          # Requests remaining
Retry-After: 45                      # Seconds to wait if exceeded

Handling Rate Limits

bash
# Use curl retry flags
curl "https://$(printenv ZENDESK_SUBDOMAIN).zendesk.com/api/v2/tickets.json" \
  -u "$(printenv ZENDESK_EMAIL)/token:$(printenv ZENDESK_API_TOKEN)" \
  --retry 3 --retry-delay 5

Guidelines

  1. Enable API token access first: In Admin Center, ensure Token Access is enabled before using tokens
  2. Always use HTTPS: TLS 1.2+ required
  3. Monitor rate limits: Check X-Rate-Limit-Remaining header
  4. Use bulk operations: create_many, update_many endpoints save API calls
  5. Implement exponential backoff: Honor Retry-After header on 429 responses
  6. Paginate large datasets: Default limit is 100, max per_page is 100
  7. Secure your tokens: Store in environment variables, never in code
  8. Use specific searches: Narrow queries with filters to reduce response size
  9. Verify with reliable endpoints: Use /tickets.json or /users.json to test tokens (not /users/me.json)
  10. Status values: open, pending, hold, solved, closed
  11. Priority values: low, normal, high, urgent
  12. User roles: end-user, agent, admin (need agent or admin role for API access)
  13. Ticket types: problem, incident, question, task
  14. Authentication format: email/token:api_token (curl -u handles encoding)
  15. New workspaces: Fresh Zendesk accounts come with sample tickets for testing

API Reference

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

vm0-ai/vm0-skills

brave-search

Brave Search API for web search. Use when user says "search web", "Brave search", or asks to "find on web" without specifying Google.

50 8
Explore
vm0-ai/vm0-skills

supadata

Supadata API for YouTube/web data. Use when user mentions "Supadata", "YouTube data", "channel stats", or web scraping data.

50 8
Explore
vm0-ai/vm0-skills

roadmap-planning

Build and prioritize product roadmaps using scoring models like RICE, ICE, and value-effort matrices. Activate when creating a product roadmap, prioritizing features, sequencing initiatives, mapping dependencies, balancing team capacity, choosing between Now/Next/Later or quarterly planning, or communicating roadmap tradeoffs to executives and stakeholders.

50 8
Explore
vm0-ai/vm0-skills

qdrant

Qdrant API for vector search. Use when user mentions "Qdrant", "vector database", "semantic search", or embeddings storage.

50 8
Explore
vm0-ai/vm0-skills

calendly

Calendly scheduling API. Use when user mentions "Calendly", "calendly.com", "schedule a meeting", "booking link", "event types", or asks about interview scheduling.

50 8
Explore
vm0-ai/vm0-skills

stripe

Stripe API for payments. Use when user mentions "Stripe", "payment", "subscription", "billing", "invoice", or asks about payment processing.

50 8
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results