Admins in Zendesk Support can set up contextual workspaces to present ticket tools and features based on specific workflows. For more information, see Setting up contextual workspaces (Enterprise).

JSON format

Workspaces are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
activatedbooleanfalsefalseIf true, this workspace is available for use
appsarrayfalsefalseThe apps associated to this workspace
conditionsobjectfalsefalseAn object that describes the conditions under which the automation will execute. See Conditions reference
created_atstringfalsefalseThe time the workspace was created
descriptionstringfalsefalseUser-defined description of this workspace's purpose
idintegerfalsefalseAutomatically assigned upon creation
macro_idsarrayfalsefalseThe ids of the macros associated to this workspace
macrosarrayfalsefalseThe ids of the macros associated to this workspace
positionintegerfalsefalseOrdering of the workspace relative to other workspaces
prefer_workspace_app_orderbooleanfalsefalseIf true, the order of apps within the workspace will be preserved
selected_macrosarrayfalsefalseAn array of the macro objects that will be used in this workspace. See Macros
ticket_form_idintegerfalsefalseThe id of the ticket web form associated to this workspace
titlestringfalsefalseThe title of the workspace
updated_atstringfalsefalseThe time of the last update of the workspace
urlstringfalsefalseThe URL for this resource

List Workspaces

  • GET /api/v2/workspaces

Allowed For

  • Admins, Agents

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/v2/workspaces.jsoncurl https://{subdomain}.zendesk.com/api/v2/workspaces.json?per_page=2
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/workspaces"	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 "username:password"
	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/workspaces")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/workspaces',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/workspaces"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/workspaces")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"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": 1,  "next_page": null,  "previous_page": null,  "workspaces": [    {      "activated": true,      "apps": [        {          "expand": false,          "id": 360000080413,          "position": 1        }      ],      "conditions": {        "all": [          {            "field": "ticket_form_id",            "operator": "is",            "value": "360000014173"          }        ],        "any": []      },      "created_at": "2018-11-13T19:08:13Z",      "description": "Test rules",      "id": 3133,      "macro_ids": [        360005374974      ],      "position": 1,      "prefer_workspace_app_order": true,      "selected_macros": [        {          "actions": [            {              "field": "status",              "value": "solved"            }          ],          "active": true,          "created_at": "2018-02-08T23:45:30Z",          "description": null,          "id": 360005374974,          "position": 9999,          "restriction": {            "id": 360002226093,            "ids": [              360002226093            ],            "type": "Group"          },          "title": "Close and redirect to topics",          "updated_at": "2018-11-08T22:27:00Z",          "url": "https://{subdomain}.zendesk.com/api/v2/macros/360005374974.json",          "usage_7d": 0        }      ],      "ticket_form_id": 360000014173,      "title": "Test Workspace 1",      "updated_at": "2018-12-17T22:37:40Z",      "url": "https://{subdomain}.zendesk.com/api/v2/workspaces.json"    }  ]}

Show Workspace

  • GET /api/v2/workspaces/{workspace_id}

Allowed For

  • Admins

Parameters

NameTypeInRequiredDescription
workspace_idintegerPathtrueThe id of the workspace

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/v2/workspaces/{id}.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/workspaces/3133"	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 "username:password"
	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/workspaces/3133")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/workspaces/3133',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/workspaces/3133"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/workspaces/3133")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"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
{  "workspace": {    "activated": true,    "apps": [],    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "created_at": "2018-11-13T19:08:13Z",    "description": "Test rules",    "id": 3133,    "macro_ids": [      360005374974    ],    "position": 1,    "prefer_workspace_app_order": true,    "selected_macros": [      {        "actions": [          {            "field": "status",            "value": "solved"          }        ],        "active": true,        "created_at": "2018-02-08T23:45:30Z",        "description": null,        "id": 360005374974,        "position": 9999,        "restriction": {          "id": 360002226093,          "ids": [            360002226093          ],          "type": "Group"        },        "title": "Close and redirect to topics",        "updated_at": "2018-11-08T22:27:00Z",        "url": "https://{subdomain}.zendesk.com/api/v2/macros/360005374974.json",        "usage_7d": 0      }    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1",    "updated_at": "2018-12-17T22:37:40Z",    "url": "https://{subdomain}.zendesk.com/api/v2/workspaces.json"  }}

Create Workspace

  • POST /api/v2/workspaces

Allowed For

  • Admins

Example body

{  "workspace": {    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "description": "Test rules",    "macros": [      360005374974    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1"  }}

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/v2/workspaces.json \  -H "Content-Type: application/json" -X POST \  -d '  {    "workspace": {      "title": "Test Workspace 1",      "description": "Test rules",      "ticket_form_id": 360000014173,      "macros": [360005374974],      "conditions": {        "all": [          {            "field": "ticket_form_id",            "operator": "is",            "value": "360000014173"          },        ],        "any": []      }    }  }' \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://example.zendesk.com/api/v2/workspaces"	method := "POST"	payload := strings.NewReader(`{  "workspace": {    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "description": "Test rules",    "macros": [      360005374974    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1"  }}`)	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 "username:password"
	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/workspaces")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"workspace\": {    \"conditions\": {      \"all\": [        {          \"field\": \"ticket_form_id\",          \"operator\": \"is\",          \"value\": \"360000014173\"        }      ],      \"any\": []    },    \"description\": \"Test rules\",    \"macros\": [      360005374974    ],    \"ticket_form_id\": 360000014173,    \"title\": \"Test Workspace 1\"  }}""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "workspace": {    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "description": "Test rules",    "macros": [      360005374974    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1"  }});
var config = {  method: 'POST',  url: 'https://example.zendesk.com/api/v2/workspaces',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport json
url = "https://example.zendesk.com/api/v2/workspaces"
payload = json.loads("""{  "workspace": {    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "description": "Test rules",    "macros": [      360005374974    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1"  }}""")headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	auth=('<username>', '<password>'),	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/workspaces")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.body = %q({  "workspace": {    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "description": "Test rules",    "macros": [      360005374974    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1"  }})request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

201 Created
// Status 201 Created
{  "workspace": {    "activated": true,    "apps": [],    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "created_at": "2018-11-13T19:08:13Z",    "description": "Test rules",    "id": 3133,    "macro_ids": [      360005374974    ],    "position": 1,    "prefer_workspace_app_order": true,    "selected_macros": [      {        "actions": [          {            "field": "status",            "value": "solved"          }        ],        "active": true,        "created_at": "2018-02-08T23:45:30Z",        "description": null,        "id": 360005374974,        "position": 9999,        "restriction": {          "id": 360002226093,          "ids": [            360002226093          ],          "type": "Group"        },        "title": "Close and redirect to topics",        "updated_at": "2018-11-08T22:27:00Z",        "url": "https://{subdomain}.zendesk.com/api/v2/macros/360005374974.json",        "usage_7d": 0      }    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1",    "updated_at": "2018-12-17T22:37:40Z",    "url": "https://{subdomain}.zendesk.com/api/v2/workspaces.json"  }}

Update Workspace

  • PUT /api/v2/workspaces/{workspace_id}

Allowed For

  • Admins

Parameters

NameTypeInRequiredDescription
workspace_idintegerPathtrueThe id of the workspace

Example body

{  "workspace": {    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "description": "Test rules",    "macros": [      360005374974    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1"  }}

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/v2/workspaces/{id}.json \  -H "Content-Type: application/json" -X PUT \  -d '{"workspace": {          "title": "Test Workspace 1",          "description": "Test rules",          "ticket_form_id": 360000014173,          "macro_ids": [360005374974],          "conditions": {            "all": [              {                "field": "status",                "operator": "is",                "value": "pending"              },            ],            "any": []          }      }}' \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://example.zendesk.com/api/v2/workspaces/3133"	method := "PUT"	payload := strings.NewReader(`{  "workspace": {    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "description": "Test rules",    "macros": [      360005374974    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1"  }}`)	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 "username:password"
	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/workspaces/3133")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"workspace\": {    \"conditions\": {      \"all\": [        {          \"field\": \"ticket_form_id\",          \"operator\": \"is\",          \"value\": \"360000014173\"        }      ],      \"any\": []    },    \"description\": \"Test rules\",    \"macros\": [      360005374974    ],    \"ticket_form_id\": 360000014173,    \"title\": \"Test Workspace 1\"  }}""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "workspace": {    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "description": "Test rules",    "macros": [      360005374974    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1"  }});
var config = {  method: 'PUT',  url: 'https://example.zendesk.com/api/v2/workspaces/3133',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport json
url = "https://example.zendesk.com/api/v2/workspaces/3133"
payload = json.loads("""{  "workspace": {    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "description": "Test rules",    "macros": [      360005374974    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1"  }}""")headers = {	"Content-Type": "application/json",}
response = requests.request(	"PUT",	url,	auth=('<username>', '<password>'),	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/workspaces/3133")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")request.body = %q({  "workspace": {    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "description": "Test rules",    "macros": [      360005374974    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1"  }})request.basic_auth "username", "password"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
{  "workspace": {    "activated": true,    "apps": [],    "conditions": {      "all": [        {          "field": "ticket_form_id",          "operator": "is",          "value": "360000014173"        }      ],      "any": []    },    "created_at": "2018-11-13T19:08:13Z",    "description": "Test rules",    "id": 3133,    "macro_ids": [      360005374974    ],    "position": 1,    "prefer_workspace_app_order": true,    "selected_macros": [      {        "actions": [          {            "field": "status",            "value": "solved"          }        ],        "active": true,        "created_at": "2018-02-08T23:45:30Z",        "description": null,        "id": 360005374974,        "position": 9999,        "restriction": {          "id": 360002226093,          "ids": [            360002226093          ],          "type": "Group"        },        "title": "Close and redirect to topics",        "updated_at": "2018-11-08T22:27:00Z",        "url": "https://{subdomain}.zendesk.com/api/v2/macros/360005374974.json",        "usage_7d": 0      }    ],    "ticket_form_id": 360000014173,    "title": "Test Workspace 1",    "updated_at": "2018-12-17T22:37:40Z",    "url": "https://{subdomain}.zendesk.com/api/v2/workspaces.json"  }}

Reorder Workspaces

  • PUT /api/v2/workspaces/reorder

Allowed For

  • Admins

Example body

{  "ids": [    12,    32,    48,    60