🎫

Zendesk Integration

33 pre-built action templates across 8 categories

One-Click Connect available! Go to Settings → Integrations → Connect Platform → Zendesk to connect with a single click via OAuth. Enter your Zendesk subdomain when prompted.

Overview

The Zendesk integration gives your AI agents full access to your helpdesk data during live phone calls and widget conversations. With 33 pre-built action templates across 8 categories, your AI can search tickets, create and update support requests, manage users and organizations, add public replies or internal notes, manage tags for routing, look up agent groups, retrieve admin configuration data, and get detailed ticket metrics, all while talking to the customer.

Connect via One-Click OAuth. No API tokens needed. Zendesk OAuth tokens do not expire, so no refresh is required.

Zendesk Quick Reference

Ticket Statuses

newopenpendingholdsolvedclosed

closed cannot be set via API and auto-transitions from solved

Ticket Priorities

lownormalhighurgent

Ticket Types

questionincidentproblemtask

Comments

"public": true = customer-visible reply

"public": false = agent-only internal note

Search Query Syntax

Zendesk uses its own query syntax for searching. No spaces before/after operators:

type:ticket status:open

type:ticket requester:[email protected]

type:ticket status:open priority:urgent

type:user email:[email protected]

🎫Tickets

Create, search, update, and delete support tickets.

GET

Search Tickets

Setting	Value
Endpoint	/api/v2/search.json
Query Param	query (must include type:ticket)
AI Instructions	Search for tickets matching a query. Always include type:ticket in the query parameter.

Example query: type:ticket status:open priority:urgent

Example Response:

{
  "results": [
    {
      "id": 1234,
      "subject": "Cannot access my account",
      "status": "open",
      "priority": "high",
      "requester_id": 5678,
      "assignee_id": 9012,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

POST

Create Ticket

Setting	Value
Endpoint	/api/v2/tickets.json
Required	comment.body (the ticket description)
Optional	subject, requester_id, priority, status, type, assignee_id
Confirmation	Required before execution

Request Body:

{
  "ticket": {
    "subject": "{{subject}}",
    "comment": { "body": "{{description}}" },
    "requester_id": "{{requester_id}}",
    "priority": "{{priority}}",
    "status": "{{status}}",
    "type": "{{type}}",
    "assignee_id": "{{assignee_id}}"
  }
}

PATCH

Update Ticket

Setting	Value
Endpoint	/api/v2/tickets/{{ticket_id}}.json
Required	ticket_id (in URL path)
Optional	status, priority, assignee_id, type, comment
Confirmation	Required before execution

Request Body:

{
  "ticket": {
    "status": "{{status}}",
    "priority": "{{priority}}",
    "assignee_id": "{{assignee_id}}",
    "type": "{{type}}",
    "comment": { "body": "{{comment}}", "public": true }
  }
}

Note: Zendesk uses PATCH for ticket updates. Only include the fields you want to change since omitted fields remain unchanged.

DELETE

Delete Ticket

Setting	Value
Endpoint	/api/v2/tickets/{{ticket_id}}.json
Required	ticket_id (in URL path)
Confirmation	Required (destructive action)

Warning: This permanently deletes the ticket. The AI will ask for explicit confirmation before executing.

👤Users

Search, create, update, and delete end-users and agents.

GET

Search Users

Setting	Value
Endpoint	/api/v2/users/search.json
Query Param	query (name, email, or phone)
AI Instructions	Search for users by name, email, or phone number.

Example Response:

{
  "users": [
    {
      "id": 5678,
      "name": "Emma Wilson",
      "email": "[email protected]",
      "phone": "+15551234567",
      "role": "end-user",
      "organization_id": 9012
    }
  ]
}

POST

Create User

Setting	Value
Endpoint	/api/v2/users.json
Required	name
Optional	email, phone, role, organization_id
Confirmation	Required before execution

Request Body:

{
  "user": {
    "name": "{{name}}",
    "email": "{{email}}",
    "phone": "{{phone}}",
    "role": "end-user",
    "organization_id": "{{organization_id}}"
  }
}

PUT

Update User

Setting	Value
Endpoint	/api/v2/users/{{user_id}}.json
Required	user_id (in URL path)
Optional	name, email, phone, organization_id
Confirmation	Required before execution

Request Body:

{
  "user": {
    "name": "{{name}}",
    "email": "{{email}}",
    "phone": "{{phone}}",
    "organization_id": "{{organization_id}}"
  }
}

Note: Zendesk uses PUT (not PATCH) for user updates. Include all fields you want to keep since omitted fields may be cleared.

DELETE

Delete User

Setting	Value
Endpoint	/api/v2/users/{{user_id}}.json
Required	user_id (in URL path)
Confirmation	Required (destructive action)

Warning: This permanently deletes the user and all associated data. The AI will ask for explicit confirmation before executing.

🏢Organizations

Search, create, update, and delete organizations.

GET

Search Organizations

Setting	Value
Endpoint	/api/v2/organizations/autocomplete.json
Query Param	name (organization name to search)
AI Instructions	Search for organizations by name using autocomplete.

Example Response:

{
  "organizations": [
    {
      "id": 9012,
      "name": "Acme Corp",
      "details": "Enterprise customer",
      "notes": "Renewed contract in Q1",
      "created_at": "2024-01-10T08:00:00Z"
    }
  ]
}

POST

Create Organization

Setting	Value
Endpoint	/api/v2/organizations.json
Required	name
Optional	details, notes
Confirmation	Required before execution

Request Body:

{
  "organization": {
    "name": "{{name}}",
    "details": "{{details}}",
    "notes": "{{notes}}"
  }
}

PUT

Update Organization

Setting	Value
Endpoint	/api/v2/organizations/{{organization_id}}.json
Required	organization_id (in URL path)
Optional	name, details, notes
Confirmation	Required before execution

Request Body:

{
  "organization": {
    "name": "{{name}}",
    "details": "{{details}}",
    "notes": "{{notes}}"
  }
}

Note: Zendesk uses PUT (not PATCH) for organization updates. Include all fields you want to keep since omitted fields may be cleared.

DELETE

Delete Organization

Setting	Value
Endpoint	/api/v2/organizations/{{organization_id}}.json
Required	organization_id (in URL path)
Confirmation	Required (destructive action)

Warning: This permanently deletes the organization. Users assigned to this organization will be unassigned. The AI will ask for explicit confirmation before executing.

💬Ticket Comments

List comments, add public replies or internal notes, and list a user's tickets.

GET

List Comments

Setting	Value
Endpoint	/api/v2/tickets/{{ticket_id}}/comments.json
Required	ticket_id (in URL path)
AI Instructions	List all comments on a ticket to see the conversation history.

Example Response:

{
  "comments": [
    {
      "id": 11111,
      "body": "I need help resetting my password",
      "author_id": 5678,
      "public": true,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 22222,
      "body": "Customer verified via phone",
      "author_id": 9012,
      "public": false,
      "created_at": "2024-01-15T10:35:00Z"
    }
  ]
}

PATCH

Add Public Reply

Setting	Value
Endpoint	/api/v2/tickets/{{ticket_id}}.json
Required	ticket_id (in URL path), comment body
Confirmation	Required before execution

Request Body:

{
  "ticket": {
    "comment": { "body": "{{comment}}", "public": true }
  }
}

Public Reply: This comment will be visible to the customer via email notification and in the customer portal.

PATCH

Add Internal Note

Setting	Value
Endpoint	/api/v2/tickets/{{ticket_id}}.json
Required	ticket_id (in URL path), comment body
Confirmation	Required before execution

Request Body:

{
  "ticket": {
    "comment": { "body": "{{comment}}", "public": false }
  }
}

Internal Note: This comment is only visible to agents. The customer will not be notified or see this note.

GET

List User's Tickets

Setting	Value
Endpoint	/api/v2/users/{{user_id}}/tickets/requested.json
Required	user_id (in URL path)
AI Instructions	List all tickets requested by a specific user to see their support history.

Example Response:

{
  "tickets": [
    {
      "id": 1234,
      "subject": "Cannot access my account",
      "status": "open",
      "priority": "high",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 1230,
      "subject": "Billing question",
      "status": "solved",
      "priority": "normal",
      "created_at": "2024-01-10T14:00:00Z"
    }
  ]
}

🏷️Tags

Manage ticket tags for categorization, routing, and triggering automations.

GET

List Ticket Tags

Setting	Value
Endpoint	/api/v2/tickets/{{ticket_id}}/tags.json
Required	ticket_id (in URL path)
AI Instructions	List all tags on a ticket to see its categorization.

Example Response:

{
  "tags": ["vip", "enterprise", "billing"]
}

PUT

Add Ticket Tags

Setting	Value
Endpoint	/api/v2/tickets/{{ticket_id}}/tags.json
Required	ticket_id (in URL path), tags array
Confirmation	Required before execution

Request Body:

{
  "tags": ["{{tag1}}", "{{tag2}}"]
}

Additive: Existing tags are preserved. New tags are added without removing any current tags.

DELETE

Remove Ticket Tags

Setting	Value
Endpoint	/api/v2/tickets/{{ticket_id}}/tags.json
Required	ticket_id (in URL path), tags array

Request Body:

{
  "tags": ["{{tag1}}", "{{tag2}}"]
}

GET

Search Tags

Setting	Value
Endpoint	/api/v2/autocomplete/tags.json
Query Param	name (tag name or partial name)
AI Instructions	Search for valid tags using autocomplete before adding them.

Example Response:

{
  "tags": [
    { "name": "escalation_needed", "count": 42 },
    { "name": "escalated", "count": 18 }
  ]
}

👥Groups

List agent groups/teams for ticket routing and lookup organization members.

GET

List Groups

Setting	Value
Endpoint	/api/v2/groups.json
AI Instructions	List all agent groups/teams to know what departments are available.

Example Response:

{
  "groups": [
    { "id": 101, "name": "Billing", "description": "Billing and payments team" },
    { "id": 102, "name": "Technical Support", "description": "Technical issues" },
    { "id": 103, "name": "Sales", "description": "Sales inquiries" }
  ]
}

GET

List Assignable Groups

Setting	Value
Endpoint	/api/v2/groups/assignable.json
AI Instructions	List only groups that can be assigned tickets. Use this for routing tickets to the right team.

GET

Get Group

Setting	Value
Endpoint	/api/v2/groups/{{group_id}}.json
Required	group_id (in URL path)
AI Instructions	Get group details to resolve a group_id to a team name (e.g., "Your ticket is with the Billing team").

Example Response:

{
  "group": {
    "id": 101,
    "name": "Billing",
    "description": "Billing and payments team",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

GET

List Organization Users

Setting	Value
Endpoint	/api/v2/organizations/{{organization_id}}/users.json
Required	organization_id (in URL path)
AI Instructions	List all users belonging to an organization. Use when the customer asks about other people from their company.

Example Response:

{
  "users": [
    { "id": 5678, "name": "Emma Wilson", "email": "[email protected]", "role": "end-user" },
    { "id": 5679, "name": "James Chen", "email": "[email protected]", "role": "end-user" }
  ]
}

🔍Direct Lookups

Get specific records by ID, which is faster and more precise than searching.

GET

Get Ticket

Setting	Value
Endpoint	/api/v2/tickets/{{ticket_id}}.json
Required	ticket_id (in URL path)
AI Instructions	Get a specific ticket by ID. Use when the customer provides a ticket number directly.

Example Response:

{
  "ticket": {
    "id": 1234,
    "subject": "Cannot access my account",
    "description": "I've been locked out since yesterday...",
    "status": "open",
    "priority": "high",
    "type": "incident",
    "requester_id": 5678,
    "assignee_id": 9012,
    "group_id": 101,
    "tags": ["account_access", "urgent"],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-16T14:20:00Z"
  }
}

GET

Get User

Setting	Value
Endpoint	/api/v2/users/{{user_id}}.json
Required	user_id (in URL path)
AI Instructions	Get a specific user by ID. Use to resolve a requester_id or assignee_id from a ticket to a name and email.

Example Response:

{
  "user": {
    "id": 5678,
    "name": "Emma Wilson",
    "email": "[email protected]",
    "phone": "+15551234567",
    "role": "end-user",
    "organization_id": 9012,
    "created_at": "2024-01-10T08:00:00Z"
  }
}

GET

Get Organization

Setting	Value
Endpoint	/api/v2/organizations/{{organization_id}}.json
Required	organization_id (in URL path)
AI Instructions	Get a specific organization by ID. Use to resolve an organization_id from a user to a company name.

Example Response:

{
  "organization": {
    "id": 9012,
    "name": "Acme Corp",
    "details": "Enterprise customer",
    "notes": "Renewed contract in Q1",
    "created_at": "2024-01-10T08:00:00Z"
  }
}

GET

Get Ticket Metrics

Setting	Value
Endpoint	/api/v2/tickets/{{ticket_id}}/metrics.json
Required	ticket_id (in URL path)
AI Instructions	Get SLA and timing metrics for a ticket. Use when customers ask "How long has my ticket been open?" or "When was the last response?"

Example Response:

{
  "ticket_metric": {
    "id": 99999,
    "ticket_id": 1234,
    "reopens": 0,
    "replies": 2,
    "first_resolution_time_in_minutes": { "calendar": 480, "business": 360 },
    "reply_time_in_minutes": { "calendar": 15, "business": 15 },
    "requester_wait_time_in_minutes": { "calendar": 1440, "business": 480 },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-16T14:20:00Z"
  }
}

Tip: Present wait times in human-readable format. For example, 1440 minutes = "1 day", 480 minutes = "8 hours".

⚙️Admin

Retrieve ticket fields, forms, group memberships, user identities, and satisfaction ratings.

GET

List Ticket Fields

Setting	Value
Endpoint	/api/v2/ticket_fields.json
AI Instructions	List all ticket fields to discover custom fields and their allowed values.

Example Response:

{
  "ticket_fields": [
    {
      "id": 30001,
      "type": "text",
      "title": "Product Area",
      "active": true,
      "required": false
    }
  ]
}

GET

List Ticket Forms

Setting	Value
Endpoint	/api/v2/ticket_forms.json
AI Instructions	List all ticket forms to see which forms are available when creating tickets.

Example Response:

{
  "ticket_forms": [
    {
      "id": 40001,
      "name": "Default Ticket Form",
      "active": true,
      "default": true
    }
  ]
}

GET

List Group Members

Setting	Value
Endpoint	/api/v2/groups/{{group_id}}/memberships.json
Required	group_id (in URL path)
AI Instructions	List all agent memberships in a group. Use to find which agents belong to a specific team.

Example Response:

{
  "group_memberships": [
    {
      "id": 50001,
      "user_id": 9012,
      "group_id": 101,
      "default": true
    }
  ]
}

GET

List User Identities

Setting	Value
Endpoint	/api/v2/users/{{user_id}}/identities.json
Required	user_id (in URL path)
AI Instructions	List all identities (emails, phone numbers, X handles) for a user.

Example Response:

{
  "identities": [
    {
      "id": 60001,
      "type": "email",
      "value": "[email protected]",
      "primary": true,
      "verified": true
    }
  ]
}

GET

Get Satisfaction Rating

Setting	Value
Endpoint	/api/v2/satisfaction_ratings/{{rating_id}}.json
Required	rating_id (in URL path)
AI Instructions	Get a specific satisfaction rating by ID. Use to check customer feedback on a resolved ticket.

Example Response:

{
  "satisfaction_rating": {
    "id": 70001,
    "assignee_id": 9012,
    "group_id": 101,
    "requester_id": 5678,
    "ticket_id": 1234,
    "score": "good",
    "comment": "Very helpful, resolved quickly!",
    "created_at": "2024-01-17T09:00:00Z"
  }
}

Example Conversation

Caller:"Hi, I submitted a ticket about my invoice last week. Any updates?"

AI calls Search Users with customer's phone number

AI calls List User's Tickets with the user_id

AI:"I can see your ticket #1234 about the invoice discrepancy. It's currently open and assigned to our billing team with high priority. The last update was yesterday. Would you like me to add a note to the ticket with any additional information?"

Caller:"Yes, please add that the correct amount should be $450, not $540."

AI calls Add Internal Note on ticket #1234

AI:"Done! I've added an internal note to ticket #1234 with the correct amount of $450. The billing team will see this when they review your ticket. Is there anything else I can help with?"

Last updated: February 2026

Back to Integrations Guide HubSpot Guide →