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:

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

  • GET /api/v2/workspaces

Allowed For

  • Admins, Agents

Using cURL

curl https://{subdomain}.zendesk.com/api/v2/workspaces.jsoncurl 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

  • Admins

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

  • 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"  }}

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

  • Admins

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

  • Admins

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

Status 200 OK

Delete Workspace

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

Allowed For

  • Admins

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

Status 204 No Content

Bulk Delete Workspaces

  • DELETE /api/v2/workspaces/destroy_many?ids={ids}

Allowed For

  • Admins

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

Status 200 OK