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 simple flat JSON objects which have the following keys.

Name Type Comment
id integer Automatically assigned when created
actions Actions An object describing what the macro will do
active boolean Useful for determining if the macro should be displayed
description string The description of the macro
position integer The position of the macro
restriction object Who may access this macro. Will be null when everyone in the account can access it
title string The title of the macro
created_at date The time the macro was created
updated_at date The time of the last update of the macro
Example
 
{
  "macro": {
    "id": 25,
    "title": "Close and Save",
    "active": true,
    "actions": { ... },
    "position": 42,
    "restriction": {
      "type": "User",
      "id": 4
    },
   "description": "Sets the ticket status to `solved`"
  }
}

Actions

Actions consist of an array of one or more actions.

Example

{
  "actions": [
    {"field": "status", "value": "open"},
    {"field": "assignee_id", "value": "296220096"}
  ]
}

Each action in the array has the following properties:

Name Type Description
field string The name of a ticket field to modify
value string The new value of the field

Example action

{ "field": "status", "value": "solved" }
Actions reference

Triggers, automations, and macros share the following actions.

field value
status Sets the ticket status. Takes new, open, pending, hold, solved, or closed, except for macros, which don't take new or closed.
type Sets the ticket type. Takes question, incident, problem, or task.
priority Sets the ticket priority. Takes low, normal, high, or urgent.
group_id Assigns the ticket to a group. Takes a string with a group id, or an empty string ("") to unassign the group assigned to the ticket.
assignee_id Assigns the ticket to a person. Takes a string with the user id of an assignee or requester, or "current_user", or an empty string ("") to unassign the person assigned to the ticket.
set_tags A space-delimited list of tags to insert in the ticket. The action replaces the current tags.
current_tags A space-delimited list of tags to add to existing tags.
remove_tags A space-delimited list of tags to remove from existing tags.
custom_fields_<id> Sets the value of a custom ticket field.
Additional actions for triggers and automations

In addition to the shared actions, triggers and automations share the following actions.

field value
satisfaction_score Sends a survey request to the ticket requester. Takes offered as a value.
notification_user Sends an email to a user. Takes an array of three strings specifying the email recipient, subject, and body. See "Notification emails" below. Possible recipient value: current_user, all_agents (all non-restricted agents), requester_id (the current requester), assignee_id (the current assignee), or the numeric ID of an agent.
notification_group Sends an email to a group. Takes an array of three strings specifying the email recipient, subject, and body. See "Notification emails" below. Possible recipient value: group_id (the currently assigned group), or the numeric ID of a group.
notification_target Sends a message to an external target. Takes an array of two strings specifying the numeric ID of the target and the message body.
tweet_requester Responds to the twitter requester with a tweet. Takes the text of the tweet.
cc CC's somebody on the ticket. Takes current_user or the numeric ID of an agent.
locale_id Sets the requester's language to one of your supported languages. Takes the numeric ID of a supported locale. See List locales to list the available locale IDs for the account.
requester.custom_fields.<field_key> Sets the value of a custom user field. The corresponding "value" property can be any string for a text field, or the id of an option for a dropdown field. An option id must be specified as a string. For a field's key or option id values, see Show User Field in User Fields
Additional actions for macros

In addition to the shared actions, macros have the following actions.

field value
subject Replaces the subject of a ticket. Takes the subject text.
comment_value Adds a comment to a ticket. Takes the comment text or an array of two strings specifying the comment channel and comment text. Possible comment channels : 'channel:all', 'channel:web' and 'channel:chat'
comment_value_html Adds a rich-text comment to a ticket.
comment_mode_is_public Makes a ticket comment public or private. Takes true (public) or false (private).
Notification emails

Notification emails are represented by an array of three strings specifying the email recipient, subject, and body.

Example

["293741756", "Leaking radiator", "Open the steam valve."]

The array is used for the value property of email notification actions. See "Additional actions for triggers and automations" above.

Example action

{
  "actions": [
    {"field": "notification_user", "value": ["293741756", "Leaking radiator", "Open the steam valve."]}
  ]
}

You can use dynamic content placeholders in the email subject and body. See Zendesk Support data object (placeholders) reference.

You can also use return (\r) and newline (\n) characters in the message body.

Example

["current_user","{{ticket.id}}: Leaking radiator","Open the steam valve.\r \nHope this helps."]

List Macros

GET /api/v2/macros.json

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

Allowed For
  • Agents
Available Parameters

You can pass in any combination of the following optional filters:

Name Type Comment
access string Only macros with given access. Possible values are personal, shared, or account
active boolean Only active macros if true, inactive macros if false
category string Only macros within given category
group_id integer Only macros belonging to given group
only_viewable boolean Only macros that can be applied to tickets if true, All macros the current user can manage if false. Defaults to false
sort_by string Possible values are alphabetical, created_at, updated_at, usage_1h, usage_24h, usage_7d, or usage_30d. Defaults to alphabetical
sort_order string One of asc or desc. Defaults to asc for alphabetical and position sort, desc for all others
Sideloads

The following sideloads are supported. The usage sideloads are only supported on the Enterprise plan.

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros.json \
  -v -u {email}:{password}
Example Response
 
Status: 200 OK

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

Show Macro

GET /api/v2/macros/{id}.json

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

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

List Active Macros

GET /api/v2/macros/active.json

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

Allowed For
  • Agents
Available Parameters

You can pass in any combination of the following optional filters:

Name Type Comment
access string Only macros with given access. Possible values are personal, shared, or account
category string Only macros within given category
group_id integer Only macros belonging to given group
sort_by string Possible values are alphabetical, created_at, updated_at, usage_1h, usage_24h, or usage_7d. Defaults to alphabetical
sort_order string One of asc or desc. Defaults to asc for alphabetical and position sort, desc for all others
Sideloads

The following sideloads are supported. The usage sideloads are only supported on the Enterprise plan.

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/active.json \
  -v -u {email}:{password}
Example Response
 
Status: 200 OK

{
  "macros": [
    {
      "id": 25,
      "title": "Close and Save",
      "raw_title": "Close and Save",
      "active": true,
      "position": 42,
      "actions": [ {...}, ... ],
      "restriction": { ... },
      "description": "Sets the ticket status to `solved`"
    },
    {
      "id": 28,
      "title": "Close and redirect to topics",
      "raw_title": "{{dc.close_and_redirect}}",
      "active": true,
      "position": 42,
      "actions": [ {...}, ... ],
      "restriction": { ... },
      "description": "Solves and marks the ticket as a known issue"
    }
  ],
  "count": 2,
  "previous_page": null,
  "next_page": null
}

Create Macro

POST /api/v2/macros.json

Allowed For
  • Agents
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 II", "actions": [{"field": "status", "value": "solved"}]}}'
Example Response
 
Status: 201 Created
Location: /api/v2/macros/{new-macro-id}.json

{
  "macro": {
    "id":   9873843,
    "title": "Roger Wilco",
    ...
  }
}
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
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

Update Macro

PUT /api/v2/macros/{id}.json

Allowed For
  • Agents
Using curl
 
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/macros/{id}.json \
  -H "Content-Type: application/json" -X PUT -d '{"macro": {"title": "Roger Wilco II"}}'
Example Response
 
Status: 200 OK

{
  "macro": {
    "id":   9873843,
    "title": "Roger Wilco II",
    ...
  }
}
Note

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

Update Many Macros

PUT /api/v2/macros/update_many.json

Updates the provided macros with the specified changes.

Allowed For
  • Agents
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

{
  "macros": [
    {
      "id": 26,
      "title": "Assign priority tag",
      "raw_title": "{{dc.assign_priority_tag}}",
      "active": false,
      "position": 419,
      "actions": [ {...}, ... ],
      "restriction": { ... },
      "description": "Adds a `priority` tag to the ticket"
    },
    {
      "id": 25,
      "title": "Close and Save",
      "raw_title": "Close and Save",
      "active": true,
      "position": 42,
      "actions": [ {...}, ... ],
      "restriction": { ... },
      "description": "Sets the ticket status to `solved`"
    },
    ...
  ]
}
Request Parameters

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

Each macro may have the following properties:

Name Mandatory Description
id yes The ID of the macro to update
position no The new position of the macro
active no The active status of the macro (true or false)
Example request
 
 {
  "macros": [
    {"id": 25, "active": false},
    {"id": 23, "active": false},
    {"id": 27, "active": false},
    {"id": 22, "active": false}
  ]
}

{
  "macros": [
    {"id": 25, "position": 3},
    {"id": 23, "position": 5},
    {"id": 27, "position": 9},
    {"id": 22, "position": 7}
  ]
}

Delete Macro

DELETE /api/v2/macros/{id}.json

Allowed For
  • Agents, with restrictions applying on certain actions
Using curl
 
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/macros/{id}.json \
  -X DELETE
Example Response
 
Status: 200 OK

Bulk Delete Macros

DELETE /api/v2/macros/destroy_many.json

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

Allowed For
  • Agents
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
Request Parameters

The DELETE request takes one parameter, an ids object that lists the macros to delete.

Name Description
ids The IDs of the macros to delete
Example request
 
{
  "ids": "25,23,27,22"
}

Show Changes to Ticket

GET /api/v2/macros/{id}/apply.json

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/{id}/apply.json \
  -u {email}:{password}
Example Response
 
Status: 200 OK

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

Show Ticket After Changes

GET /api/v2/tickets/{ticket_id}/macros/{id}/apply.json

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
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": {
      "id": 35436,
      "url": "https://company.zendesk.com/api/v2/tickets/35436.json",
      "assignee_id": 235323,
      "group_id": 98738,
      "fields": [
        {
          "id": 27642,
          "value": "745"
        }
      ],
      ...
    },
    "comment": {
      "body": "Assigned to Agent Uno.",
      "scoped_body": [["channel:all", "Assigned to Agent Uno."]],
      "public": false
    }
  }
}

List Macro Categories

GET /api/v2/macros/categories.json

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",
    ...
  ]
}

Search Macros

GET /api/v2/macros/search.json

Allowed For
  • Agents
Search Parameters

Required

Name Type Comment
query string Query string used to find macros with matching titles

Optional

You can use any combination of the following optional parameters.

Name Type Comment
access string List macros with the given access. Possible values are personal, shared, or account
active boolean List active macros if true; inactive macros if false
category string List macros in the given category
group_id integer List macros belonging to given group
only_viewable boolean List macros that can be applied to tickets if true; list all macros the current user can manage if false. Default is false
sort_by string Possible values are alphabetical, created_at, updated_at, and position. If unspecified, the macros are sorted by relevance
sort_order string One of asc or desc. Defaults to asc for alphabetical and position sort, desc for all others
Sideloads

The following sideloads are supported. The usage sideloads are only supported on the Enterprise plan.

Name Will sideload
app_installation The app installation that requires each macro, if present
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
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

{
  "macros": [
    {
      "id": 25,
      "title": "Save and Close",
      "raw_title": "Save and Close",
      "active": true,
      "position": 42,
      "actions": [ {...}, ... ],
      "restriction": { ... },
      "description": "Sets the ticket status to solved"
    },
    {
      "id": 28,
      "title": "Close and redirect to topics",
      "raw_title": "{{dc.close_and_redirect}}",
      "active": true,
      "position": 42,
      "actions": [ {...}, ... ],
      "restriction": { ... },
      "description": "Solves and marks the ticket as a known issue"
    }
  ],
  "count": 2,
  "previous_page": null,
  "next_page": null
}

List supported actions for macros

GET /api/v2/macros/actions.json

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

Show macro replica

GET /api/v2/macros/new.json

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

Allowed For
  • Agents
Available Parameters

You must pass in one of the following parameters:

Name Type Comment
macro_id integer ID of the macro to replicate
ticket_id integer ID of the ticket from which to build a macro replica

If both macro_id and ticket_id are passed, macro_id will be used.

Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/new.json?macro_id=123 \
  -u {email}:{password}
Example Response
 
Status: 200 OK

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

List Macro Action Definitions

GET /api/v2/macros/definitions.json

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 Action 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": [
      {
        "title": "Status",
        "type": "list",
        "subject": "status",
        "group": "ticket",
        "repeatable": false,
        "nullable": false,
        "values": [
          { "value": "1", "title": "Open", "enabled": true },
          { "value": "2", "title": "Pending", "enabled": true },
          { "value": "3", "title": "Solved", "enabled": true },
          { "value": "4", "title": "Closed", "enabled": true }
        ]
      },
      ...
    ]
  }
}

Create Unassociated Macro Attachment

POST /api/v2/macros/attachments.json

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 "attachment=@screenshot.jpg" -F "filename=foobar.jpg"
Example Response
 
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/macros/attachments/100.json

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

Create Macro Attachment

POST /api/v2/macros/{macro_id}/attachments.json

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/macros/123/attachments.json \
  -v -u {email}:{password} -F "attachment=@screenshot.jpg" -F "filename=foobar.jpg"
Example Response
 
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/macros/attachments/100.json

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

List Macro Attachments

GET /api/v2/macros/{macro_id}/attachments.json

Lists the attachments associated with a macro.

Allowed For
  • Agents
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": [
    {
      "id": 100,
      "filename": "foobar.jpg",
      "content_type": "image/jpeg",
      "content_url": "https://company.zendesk.com/api/v2/macros/attachments/100/content",
      "size": 2532,
      "created_at": "2016-08-15T16:04:06Z"
    },
    {
      "id": 342,
      "filename": "bazbat.jpg",
      "content_type": "image/jpeg",
      "content_url": "https://company.zendesk.com/api/v2/macros/attachments/342/content",
      "size": 5028,
      "created_at": "2016-08-16T12:42:25Z"
    },
    ...
  ]
}

Show Macro Attachment

GET /api/v2/macros/attachments/{id}.json

Shows the properties of the specified macro attachment.

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

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