Zendesk automation API reference: A practical developer guide

The Zendesk automation API gives you programmatic control over time-based business rules that keep your support operation running smoothly. While triggers fire immediately when events occur, automations run on a schedule, checking conditions every hour and performing actions when those conditions are met.

If you are building custom integrations, migrating workflows between environments, or managing Zendesk at scale, understanding this API is essential. This guide covers everything you need to implement automations effectively, from authentication to real-world code examples.

For teams without development resources, there is another path. eesel AI connects directly to Zendesk and handles many of the same automation scenarios through a no-code interface. We will explore both approaches so you can choose what fits your team.

Understanding Zendesk automations

An automation is a time-based business rule that performs one or more actions when specific conditions are met. Unlike triggers, which respond instantly to events like ticket creation or status changes, automations evaluate conditions hourly.

Here is the key distinction:

• Triggers react to events immediately. A trigger fires when a ticket is created, updated, or when a specific field changes.
• Automations run on a schedule. They check conditions every hour and execute actions only when those conditions are true.

This timing makes automations perfect for scenarios where you need to wait before acting. Common use cases include:

• SLA alerts: Notify managers when tickets remain unresolved after 24 hours
• Ticket escalation: Bump priority or reassign tickets that have been open too long
• Follow-up sequences: Send reminder emails to customers who haven't responded
• Stale ticket cleanup: Close solved tickets after a period of inactivity
• Agent workload balancing: Reassign tickets from overloaded agents

The automation lifecycle works like this: every hour, Zendesk evaluates all active automations against all tickets that meet the time-based criteria. If the conditions match, the actions execute. Importantly, automations will continue to fire as long as conditions remain true, so you need to design them carefully to avoid repeated actions.

Authentication and setup

Before you can create or manage automations via the API, you need to set up authentication. The Zendesk automation API uses token-based authentication with HTTP Basic Auth.

Generating an API token

1. Sign in to your Zendesk as an administrator
2. Go to Admin Center > Apps and integrations > APIs > Zendesk API
3. Click the Settings tab
4. Enable Token Access if it isn't already enabled
5. Click the + button to add a new token
6. Give your token a descriptive name like "Automation Management"
7. Copy the token immediately (it won't be shown again)

For detailed guidance, see the Zendesk documentation on generating API tokens.

Authentication format

The Zendesk automation API uses Basic authentication. You need to Base64 encode your credentials in this format:

{email_address}/token:{api_token}

For example, if your email is admin@company.com and your token is abc123xyz, you encode:

admin@company.com/token:abc123xyz

Here is a curl command to test your authentication:

curl https://{subdomain}.zendesk.com/api/v2/automations \
  -v -u {email_address}/token:{api_token}

Replace {subdomain} with your Zendesk subdomain, {email_address} with your admin email, and {api_token} with the token you generated.

Base URL structure

All automation API endpoints use this base URL:

https://{subdomain}.zendesk.com/api/v2/automations

Rate limits

Zendesk applies rate limits to maintain system stability. Most endpoints allow 700 requests per minute, but this can vary based on your plan and endpoint. If you exceed the limit, you will receive a 429 Too Many Requests response. Implement exponential backoff in your code to handle this gracefully.

Core API endpoints

The automation API provides standard CRUD operations. Here are the endpoints you will use most often.

List automations

GET /api/v2/automations

This endpoint returns all automations for your account. You can filter by active status and control sorting.

Available parameters:

Parameter	Type	Description
active	boolean	Filter to active (true) or inactive (false) automations
sort_by	string	Sort by "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d"
sort_order	string	"asc" or "desc"

Example curl:

curl https://{subdomain}.zendesk.com/api/v2/automations?active=true \
  -u {email_address}/token:{api_token}

Show automation

GET /api/v2/automations/{id}

Retrieve a single automation by its ID.

Example curl:

curl https://{subdomain}.zendesk.com/api/v2/automations/25 \
  -u {email_address}/token:{api_token}

Create automation

POST /api/v2/automations

Create a new automation. The request body must include a JSON object with the automation definition.

Important requirements for new automations:

• Must have at least one time-based condition
• Must include at least one condition checking status, type, group_id, assignee_id, or requester_id
• Must have an action that nullifies at least one condition (prevents infinite loops)

Example curl:

curl -u {email_address}/token:{api_token} \
  https://{subdomain}.zendesk.com/api/v2/automations \
  -H "Content-Type: application/json" -X POST -d \
  '{
    "automation": {
      "title": "Escalate old tickets",
      "all": [
        { "field": "status", "operator": "is", "value": "open" },
        { "field": "hours_since_created", "operator": "greater_than", "value": "24" }
      ],
      "actions": [
        { "field": "priority", "value": "high" }
      ]
    }
  }'

Update automation

PUT /api/v2/automations/{id}

Modify an existing automation. Send the complete automation object with your changes.

Delete automation

DELETE /api/v2/automations/{id}

Remove an automation permanently.

Pagination

The API supports two pagination methods:

• Cursor pagination (recommended): Use ?page[size]=50&page[after]=cursor for better performance with large datasets
• Offset pagination: Use ?page=2&per_page=50 for simpler implementations

Automation object structure

An automation is represented as a JSON object with specific properties. Understanding this structure is key to building effective automations.

Core properties

Property	Type	Required	Description
title	string	Yes	Human-readable name for the automation
actions	array	Yes	Actions to perform when conditions are met
conditions	object	Yes	Conditions that must be true for actions to execute
active	boolean	No	Whether the automation is enabled (default: true)
position	integer	No	Execution order (lower numbers run first)

Read-only properties

Property	Type	Description
id	integer	Unique identifier assigned by Zendesk
created_at	string	ISO 8601 timestamp of creation
updated_at	string	ISO 8601 timestamp of last modification
default	boolean	Whether this is a system default automation

The conditions object

The conditions object contains two arrays that define when the automation runs:

{
  "conditions": {
    "all": [
      { "field": "status", "operator": "is", "value": "open" },
      { "field": "hours_since_created", "operator": "greater_than", "value": "24" }
    ],
    "any": [
      { "field": "priority", "operator": "is", "value": "high" }
    ]
  }
}

• all: All conditions in this array must be true (AND logic)
• any: At least one condition in this array must be true (OR logic)

The actions array

Actions define what happens when conditions are met. Each action has a field and value:

{
  "actions": [
    { "field": "priority", "value": "high" },
    { "field": "group_id", "value": "360000000000" }
  ]
}

Complete example

Here is a full automation object that escalates tickets open for more than 24 hours:

{
  "automation": {
    "title": "Escalate tickets open > 24 hours",
    "active": true,
    "conditions": {
      "all": [
        { "field": "status", "operator": "is", "value": "open" },
        { "field": "hours_since_created", "operator": "greater_than", "value": "24" },
        { "field": "priority", "operator": "less_than", "value": "high" }
      ],
      "any": []
    },
    "actions": [
      { "field": "priority", "value": "high" },
      { "field": "current_tags", "value": "escalated" }
    ],
    "position": 1
  }
}

Available conditions and actions

Automations share many conditions and actions with triggers and macros, but they also have unique time-based capabilities. For a complete reference, see the Zendesk actions documentation.

Common condition fields

These fields work across automations, triggers, and macros:

Field	Description	Example operators
status	Ticket status	is, is_not, less_than
priority	Ticket priority	is, less_than, greater_than
type	Ticket type	is, is_not
assignee_id	Assigned agent	is, is_not
group_id	Assigned group	is, is_not
requester_id	Ticket requester	is, is_not
current_tags	Tags on ticket	includes, not_includes
via	Channel ticket came from	is, is_not

Time-based conditions (automation-specific)

These conditions are unique to automations and enable time-based workflows:

Field	Description
hours_since_created	Hours since ticket was created
hours_since_updated	Hours since last update
hours_since_assigned	Hours since ticket was assigned
hours_since_requester_updated	Hours since requester last updated
hours_since_agent_updated	Hours since agent last updated
hours_since_due_date	Hours until or since due date

Condition operators

Operator	Description
is	Exact match
is_not	Does not match
less_than	Numerically or alphabetically less
greater_than	Numerically or alphabetically greater
includes	Contains value (for tags, lists)
not_includes	Does not contain value

Shared actions

These actions work in automations, triggers, and macros:

Field	Description	Example values
status	Change ticket status	"open", "pending", "solved", "closed"
priority	Set priority	"low", "normal", "high", "urgent"
type	Set ticket type	"question", "incident", "problem", "task"
assignee_id	Assign to agent	Agent ID or "current_user"
group_id	Assign to group	Group ID
set_tags	Replace all tags	"tag1 tag2 tag3"
current_tags	Add tags	"new_tag"
remove_tags	Remove tags	"old_tag"

Automation-specific actions

Field	Description
notification_user	Send email to user
notification_group	Send email to group
notification_target	Send to external target
notification_webhook	Trigger webhook
satisfaction_score	Send satisfaction survey

Practical implementation examples

Let us walk through some real-world automation scenarios with complete code examples.

Example 1: Auto-escalate tickets open longer than 24 hours

This automation increases priority and adds an escalated tag for tickets that have been open too long.

Request:

curl -u {email_address}/token:{api_token} \
  https://{subdomain}.zendesk.com/api/v2/automations \
  -H "Content-Type: application/json" -X POST -d \
  '{
    "automation": {
      "title": "Escalate tickets open > 24 hours",
      "active": true,
      "conditions": {
        "all": [
          { "field": "status", "operator": "is", "value": "open" },
          { "field": "hours_since_created", "operator": "greater_than", "value": "24" },
          { "field": "priority", "operator": "less_than", "value": "high" }
        ]
      },
      "actions": [
        { "field": "priority", "value": "high" },
        { "field": "current_tags", "value": "escalated" }
      ]
    }
  }'

Response:

{
  "automation": {
    "id": 3600123456789,
    "title": "Escalate tickets open > 24 hours",
    "active": true,
    "conditions": {
      "all": [
        { "field": "status", "operator": "is", "value": "open" },
        { "field": "hours_since_created", "operator": "greater_than", "value": "24" },
        { "field": "priority", "operator": "less_than", "value": "high" }
      ]
    },
    "actions": [
      { "field": "priority", "value": "high" },
      { "field": "current_tags", "value": "escalated" }
    ],
    "position": 1,
    "created_at": "2026-02-24T10:00:00Z",
    "updated_at": "2026-02-24T10:00:00Z"
  }
}

Example 2: Send reminder email for pending tickets after 48 hours

This automation sends an email to the requester when their ticket has been pending for two days.

curl -u {email_address}/token:{api_token} \
  https://{subdomain}.zendesk.com/api/v2/automations \
  -H "Content-Type: application/json" -X POST -d \
  '{
    "automation": {
      "title": "Reminder: Pending ticket 48 hours",
      "active": true,
      "conditions": {
        "all": [
          { "field": "status", "operator": "is", "value": "pending" },
          { "field": "hours_since_updated", "operator": "greater_than", "value": "48" }
        ]
      },
      "actions": [
        {
          "field": "notification_user",
          "value": ["requester_id", "We are still working on your request", "Your ticket has been pending for 48 hours. Please reply with any additional information."]
        }
      ]
    }
  }'

Example 3: Close solved tickets after 72 hours of inactivity

This automation helps keep your ticket queue clean by closing solved tickets automatically.

curl -u {email_address}/token:{api_token} \
  https://{subdomain}.zendesk.com/api/v2/automations \
  -H "Content-Type: application/json" -X POST -d \
  '{
    "automation": {
      "title": "Auto-close solved tickets after 72 hours",
      "active": true,
      "conditions": {
        "all": [
          { "field": "status", "operator": "is", "value": "solved" },
          { "field": "hours_since_updated", "operator": "greater_than", "value": "72" }
        ]
      },
      "actions": [
        { "field": "status", "value": "closed" }
      ]
    }
  }'

Example 4: Tag VIP tickets for priority routing

This automation tags tickets from VIP customers for special handling.

curl -u {email_address}/token:{api_token} \
  https://{subdomain}.zendesk.com/api/v2/automations \
  -H "Content-Type: application/json" -X POST -d \
  '{
    "automation": {
      "title": "Tag VIP customer tickets",
      "active": true,
      "conditions": {
        "all": [
          { "field": "current_tags", "operator": "includes", "value": "vip_customer" }
        ],
        "any": [
          { "field": "status", "operator": "is", "value": "new" },
          { "field": "status", "operator": "is", "value": "open" }
        ]
      },
      "actions": [
        { "field": "priority", "value": "high" },
        { "field": "current_tags", "value": "vip_priority" }
      ]
    }
  }'

Testing and debugging

Before deploying automations to production, you should test them thoroughly.

Using the Zendesk API console

Zendesk provides an API console in the developer documentation where you can test requests without writing code. This is useful for verifying your JSON structure and authentication.

Testing with Postman

Zendesk maintains an official Postman collection that includes automation endpoints. Import this collection to test endpoints with a user-friendly interface. You can also explore the complete Zendesk API reference documentation for detailed information about all available endpoints.

Common error responses

HTTP Status	Meaning	Common Causes
200 OK	Success	Request completed successfully
201 Created	Created	Automation was created successfully
400 Bad Request	Invalid request	Malformed JSON, missing required fields
401 Unauthorized	Authentication failed	Invalid credentials or token
403 Forbidden	Permission denied	User lacks admin/agent rights
404 Not Found	Resource not found	Automation ID doesn't exist
422 Unprocessable	Validation failed	Invalid conditions or actions
429 Too Many Requests	Rate limited	Too many requests, retry with backoff

Verifying automation execution

To check if your automation is running correctly:

1. View ticket events to see automation actions in the activity log
2. Use the usage_24h sideload when listing automations to see execution counts
3. Check the automation's updated_at timestamp to confirm it is active

Testing conditions before going live

Create a test automation with a unique tag that you can easily identify. Apply it to a test ticket and monitor the results before rolling out to production.

Rate limits and best practices

Following best practices will help you build reliable, maintainable automations.

Rate limit management

Zendesk's default rate limit is 700 requests per minute for most endpoints. If you hit this limit:

1. Implement exponential backoff in your code
2. Use cursor pagination for listing large numbers of automations
3. Cache results when appropriate
4. Batch operations when possible

Automation position and execution order

Automations run in position order, from lowest to highest. Place time-sensitive automations earlier in the sequence to ensure they execute promptly.

Avoiding automation loops

The most common automation mistake is creating infinite loops. Always include an action that changes a condition:

• If checking for status: open, change the status in your actions
• If checking for priority: low, change the priority
• Add a unique tag and check for its absence

When to use the API vs native builder

Use the API when you need to:

• Manage automations across multiple Zendesk instances
• Version control your automation configurations
• Create automations programmatically based on external data
• Integrate with infrastructure-as-code tools like Terraform

Use Zendesk's native automation builder when:

• You only manage one Zendesk instance
• Your automations rarely change
• You prefer a visual interface

Alternative: No-code automation with eesel AI

Building and maintaining API-based automations requires development resources, testing infrastructure, and ongoing maintenance. For many teams, this overhead isn't practical.

eesel AI offers an alternative approach. Instead of writing code, you connect eesel AI to your Zendesk instance and configure automations through natural language instructions.

Here is how the approaches compare:

Aspect	Zendesk API	eesel AI
Setup time	Hours to days	Minutes
Technical skill required	Developer	None
Maintenance	Code updates, testing	Automatic updates
Flexibility	Full API control	Pre-built actions
Testing	Manual, requires staging	Built-in simulation

With eesel AI, you can achieve similar outcomes to API-based automations:

• Auto-escalation: Route urgent tickets based on content and sentiment
• Follow-ups: Send contextual reminders without manual configuration
• Ticket hygiene: Auto-tag, merge duplicates, and close stale tickets
• Smart routing: Assign tickets based on expertise and workload

The key difference is that eesel AI learns from your existing tickets and knowledge base, so it understands your business context without explicit programming. You define behaviors in plain English rather than JSON.

If your team needs automation but lacks development resources, explore how eesel AI integrates with Zendesk. The setup takes minutes rather than days, and you can test everything before going live. Learn more about AI-powered support in our guide to AI and the ITIL framework.

Getting started with the Zendesk automation API

You now have the foundation to build automations through the Zendesk API. Let us recap the key concepts:

• Automations are time-based rules that run hourly
• They require at least one time-based condition and one nullifying action
• Authentication uses API tokens with Basic auth
• The API provides standard CRUD operations for managing automations
• Always test thoroughly before deploying to production

Your next steps:

1. Generate an API token in your Zendesk Admin Center
2. Test authentication with a simple list request
3. Create a test automation in a sandbox environment
4. Iterate on your conditions and actions
5. Deploy to production with monitoring in place

For teams looking to automate without the development overhead, eesel AI provides a no-code alternative that connects directly to Zendesk and handles many of the same scenarios. You can see how it works or check pricing to compare options. For more on Zendesk integrations, read our guide on how to connect Zendesk to Slack using third-party AI apps.