Support API

Macros

A macro consists of one or more actions that modify the values of a ticket's fields. Macros are applied to tickets manually by agents. For example, you can create macros for support requests that agents can answer with a single, standard response. For more information, see Using macros to update and add comments to tickets.

JSON Format

Macros are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
actions array false true Each action describes what the macro will do. See Actions reference
active boolean false false Useful for determining if the macro should be displayed
created_at string false false The time the macro was created
description string false false The description of the macro
id integer false false The ID automatically assigned when a macro is created
position integer false false The position of the macro
restriction object false false Access to this macro. A null value allows unrestricted access for all users in the account
title string false true The title of the macro
updated_at string false false The time of the last update of the macro
url string false false A URL to access the macro's details
Example
 
{
  "actions": [
    {
      "field": "status",
      "value": "solved"
    },
    {
      "field": "priority",
      "value": "normal"
    },
    {
      "field": "type",
      "value": "incident"
    },
    {
      "field": "assignee_id",
      "value": "current_user"
    },
    {
      "field": "group_id",
      "value": "current_groups"
    },
    {
      "field": "comment_value",
      "value": "Thanks for your request. This issue you reported is a known issue. For more information, please visit our forums. "
    }
  ],
  "active": true,
  "created_at": "2019-09-16T02:17:38Z",
  "description": null,
  "id": 360111062754,
  "position": 9999,
  "restriction": null,
  "title": "Close and redirect to topics",
  "updated_at": "2019-09-16T02:17:38Z",
  "url": "https://subdomain.zendesk.com/api/v2/macros/360111062754.json"
}

List Macros
  • GET /api/v2/macros

Lists all shared and personal macros available to the current user.

Allowed For
  • Agents
Sideloads

The following sideloads are supported. The usage sideloads are only supported on Professional and Enterprise plans.

Name Will sideload
app_installation The app installation that requires each macro, if present
categories The macro categories
permissions The permissions for each macro
usage_1h The number of times each macro has been used in the past hour
usage_24h The number of times each macro has been used in the past day
usage_7d The number of times each macro has been used in the past week
usage_30d The number of times each macro has been used in the past thirty days
Parameters
Name Type In Required Description
access boolean Query false Only macros with given access. Possible values are "personal", "shared", or "account"
active boolean Query false Active macros if true. Inactive macros if false
category integer Query false Only macros within given category
group_id integer Query false Only macros belonging to given group
include string Query false Used for specifying sideloads
only_viewable boolean Query false Only macros that can be applied to tickets if true. All macros the current user can manage if false. Default value is false
sort_by string Query false Possible values are alphabetical, "created_at", "updated_at", "usage_1h", "usage_24h", "usage_7d", or "usage_30d". Defaults to alphabetical
sort_order string Query false One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros.json \
  -v -u {email}:{password}
Example Response
 
Status 200 OK

{
  "count": 2,
  "macros": [
    {
      "actions": [],
      "active": true,
      "description": "Sets the ticket status to `solved`",
      "id": 25,
      "position": 42,
      "restriction": {},
      "title": "Close and Save"
    },
    {
      "actions": [],
      "active": false,
      "description": "Adds a `priority` tag to the ticket",
      "id": 26,
      "restriction": {},
      "title": "Assign priority tag"
    }
  ],
  "next_page": null,
  "previous_page": null
}

Create Macro
  • POST /api/v2/macros
Allowed For
  • Agents
Request Parameters

The POST request takes one parameter, a macro object that lists the values to set when the macro is created.

Name Description
actions Required. An object describing what the macro will do. See Actions reference
active Allowed values are true or false. Determines if the macro is displayed or not
attachments An array of macro attachment IDs to be associated with the macro
description The description of the macro
restriction An object that describes who can access the macro. To give all agents access to the macro, omit this property
title Required. The title of the macro

The restriction object has the following properties.

Name Comment
type Allowed values are "Group" or "User"
id The numeric ID of the group or user
ids The numeric IDs of the groups
Example Body
 
{
  "macro": {
    "actions": [
      {
        "field": "status",
        "value": "solved"
      }
    ],
    "title": "Roger Wilco"
  }
}
Using curl
 
curl -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/macros.json \
  -H "Content-Type: application/json" -X POST \
  -d '{"macro": {"title": "Roger Wilco", "actions": [{"field": "status", "value": "solved"}]}}'
Example Response
 
Status 200 OK

{
  "macro": {
    "actions": [
      {
        "field": "status",
        "value": "solved"
      }
    ],
    "id": 25,
    "restriction": {},
    "title": "Roger Wilco"
  }
}

List Supported Actions for Macros
  • GET /api/v2/macros/actions
Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/actions.json \
  -v -u {email}:{password}
Example Response
 
Status 200 OK

{
  "actions": [
    {
      "group": "ticket",
      "operators": [
        {
          "title": "Is",
          "value": "is"
        }
      ],
      "output_key": null,
      "target": null,
      "title": "Set subject",
      "title_for_field": "Set subject",
      "value": "subject",
      "values": {
        "list": [],
        "type": "text"
      }
    },
    {
      "group": "ticket",
      "operators": [
        {
          "title": "Is",
          "value": "is"
        }
      ],
      "output_key": null,
      "target": null,
      "title": "Status",
      "title_for_field": "Set subject",
      "value": "subject",
      "values": {
        "list": [
          {
            "enabled": true,
            "title": "Open",
            "value": "open"
          },
          {
            "enabled": true,
            "title": "Pending",
            "value": "pending"
          },
          {
            "enabled": true,
            "title": "Solved",
            "value": "solved"
          }
        ],
        "type": "list"
      }
    },
    {
      "field": "priority",
      "group": "ticket",
      "operators": [
        {
          "title": "Is",
          "value": "is"
        }
      ],
      "output_key": null,
      "title": "Priority",
      "title_for_field": "Priority",
      "value": "priority",
      "values": {
        "list": [
          {
            "enabled": false,
            "title": "Low",
            "value": "low"
          },
          {
            "enabled": true,
            "title": "Normal",
            "value": "normal"
          },
          {
            "enabled": true,
            "title": "High",
            "value": "high"
          },
          {
            "enabled": false,
            "title": "Urgent",
            "value": "urgent"
          }
        ],
        "type": "list"
      }
    }
  ]
}

List Active Macros
  • GET /api/v2/macros/active

Lists all active shared and personal macros available to the current user.

Allowed For
  • Agents
Sideloads

The following sideloads are supported. The usage sideloads are only supported on Professional and Enterprise plans.

Name Will sideload
app_installation The app installation that requires each macro, if present
categories The macro categories
permissions The permissions for each macro
usage_1h The number of times each macro has been used in the past hour
usage_24h The number of times each macro has been used in the past day
usage_7d The number of times each macro has been used in the past week
usage_30d The number of times each macro has been used in the past thirty days
Parameters
Name Type In Required Description
access boolean Query false Only macros with given access. Possible values are "personal", "shared", or "account"
category integer Query false Only macros within given category
group_id integer Query false Only macros belonging to given group
include string Query false Used for specifying sideloads
sort_by string Query false Possible values are alphabetical, "created_at", "updated_at", "usage_1h", "usage_24h", "usage_7d", or "usage_30d". Defaults to alphabetical
sort_order string Query false One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/active.json \
  -v -u {email}:{password}
Example Response
 
Status 200 OK

{
  "count": 2,
  "macros": [
    {
      "actions": [],
      "active": true,
      "description": "Sets the ticket status to `solved`",
      "id": 25,
      "position": 42,
      "restriction": {},
      "title": "Close and Save"
    },
    {
      "actions": [],
      "active": false,
      "description": "Adds a `priority` tag to the ticket",
      "id": 26,
      "restriction": {},
      "title": "Assign priority tag"
    }
  ],
  "next_page": null,
  "previous_page": null
}

Create Unassociated Macro Attachment
  • POST /api/v2/macros/attachments

Allows an attachment to be uploaded that can be associated with a macro at a later time.

Note: To ensure an uploaded attachment is not lost, associate it with a macro as soon as possible. From time to time, old attachments that are not not associated with any macro are purged.

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/attachments.json \
  -v -u {email}:{password} -F "[email protected]" -F "filename=foobar.jpg"
Example Response
 
Status 201 Created

{
  "macro_attachment": {
    "content_type": "image/jpeg",
    "content_url": "https://company.zendesk.com/api/v2/macros/attachments/100/content",
    "created_at": "2016-08-15T16:04:06Z",
    "filename": "foobar.jpg",
    "id": 100,
    "size": 2532
  }
}

Show Macro Attachment
  • GET /api/v2/macros/attachments/{attachment_id}

Shows the properties of the specified macro attachment.

Allowed For
  • Agents
Parameters
Name Type In Required Description
attachment_id integer Path true The ID of the attachment
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/attachments/{id}.json \
  -v -u {email}:{password}
Example Response
 
Status 200 OK

{
  "macro_attachment": {
    "content_type": "image/jpeg",
    "content_url": "https://company.zendesk.com/api/v2/macros/attachments/100/content",
    "created_at": "2016-08-15T16:04:06Z",
    "filename": "foobar.jpg",
    "id": 100,
    "size": 2532
  }
}

List Macro Categories
  • GET /api/v2/macros/categories

Lists all macro categories available to the current user.

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/categories.json \
  -v -u {email}:{password}
Example Response
 
Status 200 OK

{
  "categories": [
    "FAQ",
    "Triage"
  ]
}

List Macro Action Definitions
  • GET /api/v2/macros/definitions

Returns the definitions of the actions a macro can perform. For example, one action can set the status of a ticket. The definition of the action includes a title ("Status"), a type ("list"), and possible values. For a list of support actions, see Actions reference.

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/definitions.json \
  -v -u {email}:{password}
Example Response
 
Status 200 OK

{
  "definitions": {
    "actions": [
      {
        "group": "ticket",
        "nullable": false,
        "repeatable": false,
        "subject": "status",
        "title": "Status",
        "type": "list",
        "values": [
          {
            "enabled": true,
            "title": "Open",
            "value": "1"
          },
          {
            "enabled": true,
            "title": "Pending",
            "value": "2"
          },
          {
            "enabled": true,
            "title": "Solved",
            "value": "3"
          },
          {
            "enabled": true,
            "title": "Closed",
            "value": "4"
          }
        ]
      }
    ]
  }
}

Bulk Delete Macros
  • PUT /api/v2/macros/destroy_many?ids={ids}

Deletes the macros corresponding to the provided comma-separated list of IDs.

Allowed For
  • Agents
Parameters
Name Type In Required Description
ids array Query true The IDs of the macros to delete
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/destroy_many.json?ids=1,2,3 \
  -v -u {email}:{password} -X DELETE
Example Response
 
Status 204 No Content

Show Macro Replica
  • GET /api/v2/macros/new?macro_id={macro_id}?ticket_id={ticket_id}

Returns an unpersisted macro representation derived from a ticket or macro.

The endpoint takes one of the following query parameters: macro_id or ticket_id. If you include both, macro_id is used.

Allowed For
  • Agents
Parameters
Name Type In Required Description
macro_id integer Query true The ID of the macro to replicate
ticket_id integer Query true The ID of the ticket from which to build a macro replica
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/new.json?macro_id=123 \
  -u {email}:{password}
Example Response
 
Status 200 OK

{
  "macro": {
    "actions": [],
    "active": true,
    "description": "Sets the ticket status to `solved`",
    "id": 25,
    "position": 42,
    "restriction": {},
    "title": "Close and Save"
  }
}

Search Macros
  • GET /api/v2/macros/search?query={query}
Allowed For
  • Agents
Sideloads

The following sideloads are supported. The usage sideloads are only supported on Professional and Enterprise plans.

Name Will sideload
app_installation The app installation that requires each macro, if present
categories The macro categories
permissions The permissions for each macro
usage_1h The number of times each macro has been used in the past hour
usage_24h The number of times each macro has been used in the past day
usage_7d The number of times each macro has been used in the past week
usage_30d The number of times each macro has been used in the past thirty days
Parameters
Name Type In Required Description
access boolean Query false Only macros with given access. Possible values are "personal", "shared", or "account"
active boolean Query false Active macros if true. Inactive macros if false
category integer Query false Only macros within given category
group_id integer Query false Only macros belonging to given group
include string Query false Used for specifying sideloads
only_viewable boolean Query false Only macros that can be applied to tickets if true. All macros the current user can manage if false. Default value is false
query string Query true Query string used to find macros with matching titles
sort_by string Query false Possible values are alphabetical, "created_at", "updated_at", "usage_1h", "usage_24h", "usage_7d", or "usage_30d". Defaults to alphabetical
sort_order string Query false One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/search.json?query=close&active=true
  -v -u {email}:{password}
Example Response
 
Status 200 OK

{
  "count": 2,
  "macros": [
    {
      "actions": [],
      "active": true,
      "description": "Sets the ticket status to `solved`",
      "id": 25,
      "position": 42,
      "restriction": {},
      "title": "Close and Save"
    },
    {
      "actions": [],
      "active": false,
      "description": "Adds a `priority` tag to the ticket",
      "id": 26,
      "restriction": {},
      "title": "Assign priority tag"
    }
  ],
  "next_page": null,
  "previous_page": null
}

Update Many Macros
  • PUT /api/v2/macros/update_many

Updates the provided macros with the specified changes.

Allowed For
  • Agents
Request Parameters

The PUT request expects a macros object that lists the triggers to update.

Each macro may have the following properties

Name Type Mandatory Description
id integer yes The ID of the macro to update
position integer no The new position of the macro
active boolean no The active status of the macro (true or false)
Example Body
 
{
  "macros": [
    {
      "active": false,
      "id": 25
    },
    {
      "id": 23,
      "position": 5
    }
  ]
}
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/update_many.json \
  -v -u {email}:{password} -H "Content-Type: application/json" \
  -X PUT -d '{"macros": [{"id": 123, "position": 8}]}'
Example Response
 
Status 200 OK

{
  "count": 2,
  "macros": [
    {
      "actions": [],
      "active": true,
      "description": "Sets the ticket status to `solved`",
      "id": 25,
      "position": 42,
      "restriction": {},
      "title": "Close and Save"
    },
    {
      "actions": [],
      "active": false,
      "description": "Adds a `priority` tag to the ticket",
      "id": 26,
      "restriction": {},
      "title": "Assign priority tag"
    }
  ],
  "next_page": null,
  "previous_page": null
}

Show Macro
  • GET /api/v2/macros/{macro_id}
Allowed For
  • Agents
Parameters
Name Type In Required Description
macro_id integer Path true The ID of the macro
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/{macro_id}.json \
  -v -u {email}:{password}
Example Response
 
Status 200 OK

{
  "macro": {
    "actions": [],
    "active": true,
    "description": "Sets the ticket status to `solved`",
    "id": 25,
    "position": 42,
    "restriction": {},
    "title": "Close and Save"
  }
}

Update Macro
  • PUT /api/v2/macros/{macro_id}
Allowed For
  • Agents
Note

Updating an action updates the containing array, clearing the other actions. Include all your actions when updating any action.

Parameters
Name Type In Required Description
macro_id integer Path true The ID of the macro
Example Body
 
{
  "macro": {
    "actions": [
      {
        "field": "status",
        "value": "solved"
      }
    ],
    "title": "Sets the ticket status to `solved`"
  }
}
Using curl
 
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/macros/{macro_id}.json \
  -H "Content-Type: application/json" -X PUT -d '{"macro": {"title": "Sets the ticket status to `solved`"}}'
Example Response
 
Status 200 OK

{
  "macro": {
    "actions": [
      {
        "field": "status",
        "value": "solved"
      }
    ],
    "active": true,
    "description": "Sets the ticket status to `solved`",
    "id": 25,
    "position": 42,
    "restriction": {},
    "title": "Close and Save"
  }
}

Delete Macro
  • DELETE /api/v2/macros/{macro_id}
Allowed For
  • Agents, with restrictions applying on certain actions
Parameters
Name Type In Required Description
macro_id integer Path true The ID of the macro
Using curl
 
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/macros/{macro_id}.json \
  -X DELETE
Example Response
 
Status 204 No Content

Show Changes to Ticket
  • GET /api/v2/macros/{macro_id}/apply

Returns the changes the macro would make to a ticket. It doesn't actually change a ticket. You can use the response data in a subsequent API call to the Tickets endpoint to update the ticket.

The response includes only the ticket fields that would be changed by the macro. To get the full ticket object after the macro is applied, see Show Ticket After Changes below.

Allowed For
  • Agents
Parameters
Name Type In Required Description
macro_id integer Path true The ID of the macro
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/{macro_id}/apply.json \
  -u {email}:{password}
Example Response
 
Status 200 OK

{
  "result": {
    "ticket": {
      "assignee_id": 235323,
      "comment": {
        "body": "Assigned to Agent Uno.",
        "public": false,
        "scoped_body": [
          [
            "channel:all",
            "Assigned to Agent Uno."
          ]
        ]
      },
      "fields": {
        "id": 27642,
        "value": "745"
      },
      "group_id": 98738
    }
  }
}

List Macro Attachments
  • GET /api/v2/macros/{macro_id}/attachments

Lists the attachments associated with a macro.

Allowed For
  • Agents
Parameters
Name Type In Required Description
macro_id integer Path true The ID of the macro
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/{macro_id}/attachments.json \
  -v -u {email}:{password}
Example Response
 
Status 200 OK

{
  "macro_attachments": [
    {
      "content_type": "image/jpeg",
      "content_url": "https://company.zendesk.com/api/v2/macros/attachments/100/content",
      "created_at": "2016-08-15T16:04:06Z",
      "filename": "foobar.jpg",
      "id": 100,
      "size": 2532
    },
    {
      "content_type": "image/jpeg",
      "content_url": "https://company.zendesk.com/api/v2/macros/attachments/342/content",
      "created_at": "2016-08-16T12:42:25Z",
      "filename": "bazbat.jpg",
      "id": 342,
      "size": 5028
    }
  ]
}

Create Macro Attachment
  • POST /api/v2/macros/{macro_id}/attachments

Allows an attachment to be uploaded and associated with a macro at the same time.

Note: A macro can be associated with up to five attachments.

Allowed For
  • Agents
Parameters
Name Type In Required Description
macro_id integer Path true The ID of the macro
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/123/attachments.json \
  -v -u {email}:{password} -F "[email protected]" -F "filename=foobar.jpg"
Example Response
 
Status 201 Created

{
  "macro_attachment": {
    "content_type": "image/jpeg",
    "content_url": "https://company.zendesk.com/api/v2/macros/attachments/100/content",
    "created_at": "2016-08-15T16:04:06Z",
    "filename": "foobar.jpg",
    "id": 100,
    "size": 2532
  }
}

Show Ticket After Changes
  • GET /api/v2/tickets/{ticket_id}/macros/{macro_id}/apply

Returns the full ticket object as it would be after applying the macro to the ticket. It doesn't actually change the ticket. You can use the response data in a subsequent API call to the Tickets endpoint to update the ticket.

To get only the ticket fields that would be changed by the macro, see Show Changes to Ticket.

Allowed For
  • Agents
Parameters
Name Type In Required Description
macro_id integer Path true The ID of the macro
ticket_id integer Path true The ID of the ticket
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/macros/{id}/apply.json \
  -u {email}:{password}
Example Response
 
Status 200 OK

{
  "result": {
    "ticket": {
      "assignee_id": 235323,
      "comment": {
        "body": "Assigned to Agent Uno.",
        "public": false,
        "scoped_body": [
          [
            "channel:all",
            "Assigned to Agent Uno."
          ]
        ]
      },
      "fields": {
        "id": 27642,
        "value": "745"
      },
      "group_id": 98738
    }
  }
}