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) .
Workspaces are represented as JSON objects with the following properties:
Name
Type
Read-only
Mandatory
Description
activated
boolean
false
false
If true, this workspace is available for use
apps
array
false
false
The apps associated to this workspace
conditions
object
false
false
An object that describes the conditions under which the automation will execute. See Conditions reference
created_at
string
false
false
The time the workspace was created
description
string
false
false
User-defined description of this workspace's purpose
id
integer
false
false
Automatically assigned upon creation
macro_ids
array
false
false
The ids of the macros associated to this workspace
macros
array
false
false
The ids of the macros associated to this workspace
position
integer
false
false
Ordering of the workspace relative to other workspaces
prefer_workspace_app_order
boolean
false
false
If true, the order of apps within the workspace will be preserved
selected_macros
array
false
false
An array of the macro objects that will be used in this workspace. See Macros
ticket_form_id
integer
false
false
The id of the ticket web form associated to this workspace
title
string
false
false
The title of the workspace
updated_at
string
false
false
The time of the last update of the workspace
url
string
false
false
The URL for this resource
List Workspaces
Allowed For
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/workspaces.json
curl https://{subdomain}.zendesk.com/api/v2/workspaces.json?per_page=2
Example Response
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
Parameters
Name
Type
In
Required
Description
workspace_id
integer
Path
true
The id of the workspace
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/workspaces/{id}.json \
-v -u {email_address}:{password}
Example Response
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
Allowed For
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"
}
}
Using 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}
Example Response
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
Parameters
Name
Type
In
Required
Description
workspace_id
integer
Path
true
The 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"
}
}
Using 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}
Example Response
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
Example Body
{
"ids" : [
12 ,
32 ,
48 ,
60
]
}
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/workspaces/reorder.json \
-H "Content-Type: application/json" -X PUT \
-d '{"ids": [12, 32, 48, 60]}' \
-v -u {email_address}:{password}
Example Response
Delete Workspace
DELETE /api/v2/workspaces/{workspace_id}
Allowed For
Parameters
Name
Type
In
Required
Description
workspace_id
integer
Path
true
The id of the workspace
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/workspaces/{workspace_id}.json \
-v -u {email_address}:{password} -X DELETE
Example Response
Bulk Delete Workspaces
DELETE /api/v2/workspaces/destroy_many?ids={ids}
Allowed For
Parameters
Name
Type
In
Required
Description
ids
array
Query
true
The ids of the workspaces to delete
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/workspaces/destroy_many.json?ids=1,2,3 \
-v -u {email}:{password} -X DELETE
Example Response