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:

NameTypeRead-onlyMandatoryDescription
actionsarrayfalsetrueEach action describes what the macro will do. See Actions reference
activebooleanfalsefalseUseful for determining if the macro should be displayed
created_atstringfalsefalseThe time the macro was created
defaultbooleantruefalseIf true, the macro is a default macro
descriptionstringfalsefalseThe description of the macro
idintegerfalsefalseThe ID automatically assigned when a macro is created
positionintegerfalsefalseThe position of the macro
restrictionobjectfalsefalseAccess to this macro. A null value allows unrestricted access for all users in the account
titlestringfalsetrueThe title of the macro
updated_atstringfalsefalseThe time of the last update of the macro
urlstringfalsefalseA 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",  "default": false,  "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. For admins, the API returns all macros for the account, including the personal macros of agents and other admins.

Pagination

  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

  • Agents

Sideloads

The following sideloads are supported. The usage sideloads are only supported on the Support Professional or Suite Growth plan or above.

NameWill sideload
app_installationThe app installation that requires each macro, if present
categoriesThe macro categories
permissionsThe permissions for each macro
usage_1hThe number of times each macro has been used in the past hour
usage_24hThe number of times each macro has been used in the past day
usage_7dThe number of times each macro has been used in the past week
usage_30dThe number of times each macro has been used in the past thirty days

Parameters

NameTypeInRequiredDescription
accessstringQueryfalseFilter macros by access. Possible values are "personal", "agents", "shared", or "account". The "agents" value returns all personal macros for the account's agents and is only available to admins.
activebooleanQueryfalseFilter by active macros if true or inactive macros if false
categoryintegerQueryfalseFilter macros by category
group_idintegerQueryfalseFilter macros by group
includestringQueryfalseA sideload to include in the response. See Sideloads
only_viewablebooleanQueryfalseIf true, returns only macros that can be applied to tickets. If false, returns all macros the current user can manage. Default is false
sort_bystringQueryfalsePossible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", "usage_7d", or "usage_30d". Defaults to alphabetical
sort_orderstringQueryfalseOne of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/macros.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/macros?access=personal&active=true&category=25&group_id=25&include=usage_7d&only_viewable=false&sort_by=alphabetical&sort_order=asc"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/macros")		.newBuilder()		.addQueryParameter("access", "personal")		.addQueryParameter("active", "true")		.addQueryParameter("category", "25")		.addQueryParameter("group_id", "25")		.addQueryParameter("include", "usage_7d")		.addQueryParameter("only_viewable", "false")		.addQueryParameter("sort_by", "alphabetical")		.addQueryParameter("sort_order", "asc");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/macros',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  params: {    'access': 'personal',    'active': 'true',    'category': '25',    'group_id': '25',    'include': 'usage_7d',    'only_viewable': 'false',    'sort_by': 'alphabetical',    'sort_order': 'asc',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/macros?access=personal&active=true&category=25&group_id=25&include=usage_7d&only_viewable=false&sort_by=alphabetical&sort_order=asc"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/macros")uri.query = URI.encode_www_form("access": "personal", "active": "true", "category": "25", "group_id": "25", "include": "usage_7d", "only_viewable": "false", "sort_by": "alphabetical", "sort_order": "asc")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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}

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 the Support Professional or Suite Growth plan or above.

NameWill sideload
app_installationThe app installation that requires each macro, if present
categoriesThe macro categories
permissionsThe permissions for each macro
usage_1hThe number of times each macro has been used in the past hour
usage_24hThe number of times each macro has been used in the past day
usage_7dThe number of times each macro has been used in the past week
usage_30dThe number of times each macro has been used in the past thirty days

Parameters

NameTypeInRequiredDescription
accessstringQueryfalseFilter macros by access. Possible values are "personal", "agents", "shared", or "account". The "agents" value returns all personal macros for the account's agents and is only available to admins.
categoryintegerQueryfalseFilter macros by category
group_idintegerQueryfalseFilter macros by group
includestringQueryfalseA sideload to include in the response. See Sideloads
sort_bystringQueryfalsePossible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", "usage_7d", or "usage_30d". Defaults to alphabetical
sort_orderstringQueryfalseOne of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/macros/active.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/macros/active?access=personal&category=25&group_id=25&include=usage_7d&sort_by=alphabetical&sort_order=asc"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/macros/active")		.newBuilder()		.addQueryParameter("access", "personal")		.addQueryParameter("category", "25")		.addQueryParameter("group_id", "25")		.addQueryParameter("include", "usage_7d")		.addQueryParameter("sort_by", "alphabetical")		.addQueryParameter("sort_order", "asc");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/macros/active',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  params: {    'access': 'personal',    'category': '25',    'group_id': '25',    'include': 'usage_7d',    'sort_by': 'alphabetical',    'sort_order': 'asc',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/macros/active?access=personal&category=25&group_id=25&include=usage_7d&sort_by=alphabetical&sort_order=asc"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/macros/active")uri.query = URI.encode_www_form("access": "personal", "category": "25", "group_id": "25", "include": "usage_7d", "sort_by": "alphabetical", "sort_order": "asc")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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

NameTypeInRequiredDescription
macro_idintegerPathtrueThe ID of the macro

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/macros/{macro_id}.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/macros/25"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/macros/25")		.newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/macros/25',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/macros/25"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/macros/25")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

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

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.

NameDescription
actionsRequired. An object describing what the macro will do. See Actions reference
activeAllowed values are true or false. Determines if the macro is displayed or not
attachmentsAn array of macro attachment IDs to be associated with the macro
descriptionThe description of the macro
restrictionAn object that describes who can access the macro. To give all agents access to the macro, omit this property
titleRequired. The title of the macro

The restriction object has the following properties.

NameComment
typeRequired. Allowed values are "Group" or "User"
idThe numeric ID of the group or user
idsThe numeric IDs of the groups

Example body

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

Code Samples

curl
curl -u {email_address}/token:{api_token} 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"}], "restriction": {"type": "User","id": "12345"}}}'
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://example.zendesk.com/api/v2/macros"	method := "POST"	payload := strings.NewReader(`{  "macro": {    "actions": [      {        "field": "status",        "value": "solved"      }    ],    "title": "Roger Wilco"  }}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/macros")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"macro\": {    \"actions\": [      {        \"field\": \"status\",        \"value\": \"solved\"      }    ],    \"title\": \"Roger Wilco\"  }}""");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "macro": {    "actions": [      {        "field": "status",        "value": "solved"      }    ],    "title": "Roger Wilco"  }});
var config = {  method: 'POST',  url: 'https://example.zendesk.com/api/v2/macros',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport jsonfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/macros"
payload = json.loads("""{  "macro": {    "actions": [      {        "field": "status",        "value": "solved"      }    ],    "title": "Roger Wilco"  }}""")headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"POST",	url,	auth=auth,	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/macros")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.body = %q({  "macro": {    "actions": [      {        "field": "status",        "value": "solved"      }    ],    "title": "Roger Wilco"  }})email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

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

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

NameTypeInRequiredDescription
macro_idintegerPathtrueThe ID of the macro

Example body

{  "macro": {    "actions": [      {        "field": "status",        "value": "solved"      }    ],    "title": "Sets the ticket status to `solved`"  }}

Code Samples

curl
curl -v -u {email_address}/token:{api_token} 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`"}}'
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://example.zendesk.com/api/v2/macros/25"	method := "PUT"	payload := strings.NewReader(`{  "macro": {    "actions": [      {        "field": "status",        "value": "solved"      }    ],    "title": "Sets the ticket status to `solved`"  }}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/macros/25")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"macro\": {    \"actions\": [      {        \"field\": \"status\",        \"value\": \"solved\"      }    ],    \"title\": \"Sets the ticket status to `solved`\"  }}""");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "macro": {    "actions": [      {        "field": "status",        "value": "solved"      }    ],    "title": "Sets the ticket status to `solved`"  }});
var config = {  method: 'PUT',  url: