Task Lists

Task lists are copies of task list templates that are added to tickets directly in the Agent Workspace. The task list templates are created and maintained by admins with pre-defined lists of tasks that are required in common situations. When a task list is added to a ticket, agents can check off the tasks as they complete them without leaving the ticket interface and without affecting the task list template.

Within the Task Lists API, the task lists that are defined by admins are referred to as task list templates, and the instances of task lists that agents add to tickets are referred to as task lists. The items within a task list and template are referred to as tasks.

Agents can also create custom task lists — ad-hoc task lists created directly on a ticket without a template. Custom task lists support full CRUD on their individual task items via the task items endpoints below.

JSON format

Task Lists are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
created_at	string	true	false	The time the task list was created
description	string	false	false	The description of the task list
id	string	true	false	Automatically assigned when a task list is created
is_required	boolean	true	false	Whether the task list is required. If true, the ticket can't be solved until all tasks are completed.
name	string	false	false	The name of the task list. Required when creating a custom task list (without a template).
task_count	integer	true	false	The number of tasks in the task list
task_list_template_id	string	true	false	The id of the task list template used to create the task list. The value is null for custom task lists. You can specify this property only when creating a task list
ticket_id	string	true	false	The ID of the ticket that the task list is attached to
updated_at	string	true	false	The time the task list was last updated

Example

{
  "created_at": "2025-08-06T17:08:40Z",
  "description": "Complete HR, IT, and payroll setup for new employees.",
  "id": "01KFGZJGMQ3NA9DNX34Y5YGGYM",
  "is_required": false,
  "name": "Onboarding checklist",
  "task_count": 2,
  "task_list_template_id": "01K205PG0J2ET0B8AFHA106C1E",
  "ticket_id": "1",
  "updated_at": "2025-08-06T17:08:40Z"
}

Show Task Lists for Ticket

• GET /api/v2/tickets/{ticket_id}/task_lists

Returns the task lists attached to the specified ticket. If the ticket has no task lists attached, the task_lists array in the response will be empty.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
ticket_id	integer	Path	true	The ID of the ticket

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/task_lists.json \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}"

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/tickets/123456/task_lists"
	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/tickets/123456/task_lists")
		.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/tickets/123456/task_lists',
  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 requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/tickets/123456/task_lists"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = 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/tickets/123456/task_lists")
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": 1,
  "next_page": null,
  "previous_page": null,
  "task_lists": [
    {
      "created_at": "2025-08-06T17:08:40Z",
      "description": "Complete HR, IT, and payroll setup for new employees.",
      "id": "01K3KVF23JWZ5M98BJBQHENYZ9",
      "is_required": false,
      "name": "Onboarding checklist",
      "task_count": 2,
      "task_list_template_id": "01K205PG0J2ET0B8AFHA106C1E",
      "ticket_id": "1",
      "updated_at": "2025-08-06T17:08:40Z"
    }
  ]
}

Create Task List

• POST /api/v2/tickets/{ticket_id}/task_lists

Adds a task list to the specified ticket. There are two ways to create a task list:

Create from a template: Include task_list_template_id in the request body. The new task list will inherit the template's name, description, and task items.

Create a custom task list: Include name (and optionally description) instead of task_list_template_id. Custom task lists have no template and allow you to add, update, and delete task items individually.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
ticket_id	integer	Path	true	The ID of the ticket

Example body

{
  "task_list": {
    "task_list_template_id": "01K205PG0J2ET0B8AFHA106C1E"
  }
}

Code Samples

Curl

curl --request POST https://example.zendesk.com/api/v2/tickets/123456/task_lists \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--data-raw '{
  "task_list": {
    "task_list_template_id": "01K205PG0J2ET0B8AFHA106C1E"
  }
}'

Go

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://example.zendesk.com/api/v2/tickets/123456/task_lists"
	method := "POST"
	payload := strings.NewReader(`{
  "task_list": {
    "task_list_template_id": "01K205PG0J2ET0B8AFHA106C1E"
  }
}`)
	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/tickets/123456/task_lists")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"task_list\": {
    \"task_list_template_id\": \"01K205PG0J2ET0B8AFHA106C1E\"
  }
}""");
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({
  "task_list": {
    "task_list_template_id": "01K205PG0J2ET0B8AFHA106C1E"
  }
});

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/tickets/123456/task_lists',
  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 requests
import json
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/tickets/123456/task_lists"

payload = json.loads("""{
  "task_list": {
    "task_list_template_id": "01K205PG0J2ET0B8AFHA106C1E"
  }
}""")
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = 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/tickets/123456/task_lists")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "task_list": {
    "task_list_template_id": "01K205PG0J2ET0B8AFHA106C1E"
  }
})
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

curl (from template)

curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/task_lists.json \
  -H "Content-Type: application/json" \
  -d '{
    "task_list": {
      "task_list_template_id": "01K205PG0J2ET0B8AFHA106C1E"
    }}' \
  -H "Authorization: Bearer {access_token}" -X POST

curl (custom)

curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/task_lists.json \
  -H "Content-Type: application/json" \
  -d '{
    "task_list": {
      "name": "Custom follow-up checklist",
      "description": "Custom task list for this ticket"
    }}' \
  -H "Authorization: Bearer {access_token}" -X POST

Example response(s)

201 Created

// Status 201 Created

{
  "count": 1,
  "next_page": null,
  "previous_page": null,
  "task_lists": [
    {
      "created_at": "2025-08-06T17:08:40Z",
      "description": "Complete HR, IT, and payroll setup for new employees.",
      "id": "01K3KVF23JWZ5M98BJBQHENYZ9",
      "is_required": false,
      "name": "Onboarding checklist",
      "task_count": 2,
      "task_list_template_id": "01K205PG0J2ET0B8AFHA106C1E",
      "ticket_id": "1",
      "updated_at": "2025-08-06T17:08:40Z"
    }
  ]
}

Show Task List

• GET /api/v2/task_lists/{task_list_id}

Returns the task list with the specified id. The response includes is_completed, which indicates whether all task items in the list have been completed. Works for both template-based and custom task lists.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
task_list_id	string	Path	true	The id of the task list

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/task_lists/{task_list_id}.json \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}"

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM"
	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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM")
		.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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM',
  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 requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = 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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM")
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

{
  "task_list": {
    "created_at": "2025-08-06T17:08:40Z",
    "description": "Custom task list for this ticket",
    "id": "01KFGZJGMQ3NA9DNX34Y5YGGYM",
    "is_completed": false,
    "is_required": false,
    "name": "Custom follow-up checklist",
    "task_count": 2,
    "ticket_id": "1",
    "updated_at": "2025-08-06T17:09:15Z"
  }
}

Update Custom Task List

• PUT /api/v2/task_lists/{task_list_id}

Updates the name or description of a custom task list. Only custom task lists (those without a template) can be updated.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
task_list_id	string	Path	true	The id of the task list

Example body

{
  "task_list": {
    "description": "Updated description",
    "name": "Updated checklist name"
  }
}

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/task_lists/{task_list_id}.json \
  -H "Content-Type: application/json" \
  -d '{
    "task_list": {
      "name": "Updated checklist name"
    }}' \
  -H "Authorization: Bearer {access_token}" -X PUT

Go

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM"
	method := "PUT"
	payload := strings.NewReader(`{
  "task_list": {
    "description": "Updated description",
    "name": "Updated checklist name"
  }
}`)
	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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"task_list\": {
    \"description\": \"Updated description\",
    \"name\": \"Updated checklist name\"
  }
}""");
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({
  "task_list": {
    "description": "Updated description",
    "name": "Updated checklist name"
  }
});

var config = {
  method: 'PUT',
  url: 'https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM',
  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 requests
import json
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM"

payload = json.loads("""{
  "task_list": {
    "description": "Updated description",
    "name": "Updated checklist name"
  }
}""")
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"PUT",
	url,
	auth=auth,
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM")
request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")
request.body = %q({
  "task_list": {
    "description": "Updated description",
    "name": "Updated checklist name"
  }
})
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

{
  "task_list": {
    "created_at": "2025-08-06T17:08:40Z",
    "description": "Updated description",
    "id": "01KFGZJGMQ3NA9DNX34Y5YGGYM",
    "is_completed": false,
    "is_required": false,
    "name": "Updated checklist name",
    "task_count": 2,
    "ticket_id": "1",
    "updated_at": "2025-08-06T17:15:00Z"
  }
}

Delete Task List

• DELETE /api/v2/task_lists/{task_list_id}

Deletes the task list with the specified id.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
task_list_id	string	Path	true	The id of the task list

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/task_lists/{task_list_id}.json \
  -H "Authorization: Bearer {access_token}" -X DELETE

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM"
	method := "DELETE"
	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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM")
		.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("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM',
  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 requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"DELETE",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM")
request = Net::HTTP::Delete.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)

204 No Content

// Status 204 No Content

null

List Task Items

• GET /api/v2/task_lists/{task_list_id}/task_items

Returns all task items for the specified task list. Works for both template-based and custom task lists. Each item includes an is_custom field indicating whether it was added directly to the task list or inherited from a template.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
task_list_id	string	Path	true	The id of the task list

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/task_lists/{task_list_id}/task_items.json \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}"

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items"
	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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items")
		.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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items',
  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 requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = 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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items")
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": 1,
  "next_page": null,
  "previous_page": null,
  "task_items": [
    {
      "created_at": "2025-08-06T17:09:00Z",
      "description": "Check prior contacts with the customer",
      "id": "01KH2TPNQR5WB7MV9XEJD0FZHS",
      "is_completed": false,
      "is_custom": true,
      "name": "Review ticket history",
      "updated_at": "2025-08-06T17:09:00Z",
      "url": "https://{subdomain}.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS.json"
    }
  ]
}

Create Custom Task Item

• POST /api/v2/task_lists/{task_list_id}/task_items

Adds a task item to the specified custom task list. The task list must be a custom task list (not created from a template). Creating a task item increments task_count on the parent task list.

name is required. description is optional.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
task_list_id	string	Path	true	The id of the task list

Example body

{
  "task_item": {
    "description": "Check prior contacts with the customer",
    "name": "Review ticket history"
  }
}

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/task_lists/{task_list_id}/task_items.json \
  -H "Content-Type: application/json" \
  -d '{
    "task_item": {
      "name": "Review ticket history",
      "description": "Check prior contacts with the customer"
    }}' \
  -H "Authorization: Bearer {access_token}" -X POST

Go

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items"
	method := "POST"
	payload := strings.NewReader(`{
  "task_item": {
    "description": "Check prior contacts with the customer",
    "name": "Review ticket history"
  }
}`)
	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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"task_item\": {
    \"description\": \"Check prior contacts with the customer\",
    \"name\": \"Review ticket history\"
  }
}""");
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({
  "task_item": {
    "description": "Check prior contacts with the customer",
    "name": "Review ticket history"
  }
});

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items',
  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 requests
import json
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items"

payload = json.loads("""{
  "task_item": {
    "description": "Check prior contacts with the customer",
    "name": "Review ticket history"
  }
}""")
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = 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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "task_item": {
    "description": "Check prior contacts with the customer",
    "name": "Review ticket history"
  }
})
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)

201 Created

// Status 201 Created

{
  "task_item": {
    "created_at": "2025-08-06T17:09:00Z",
    "description": "Check prior contacts with the customer",
    "id": "01KH2TPNQR5WB7MV9XEJD0FZHS",
    "is_completed": false,
    "is_custom": true,
    "name": "Review ticket history",
    "updated_at": "2025-08-06T17:09:00Z",
    "url": "https://{subdomain}.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS.json"
  }
}

Show Task Item

• GET /api/v2/task_lists/{task_list_id}/task_items/{task_item_id}

Returns the task item with the specified id. Works for both template-based and custom task items.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
task_item_id	string	Path	true	The id of the task item
task_list_id	string	Path	true	The id of the task list

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/task_lists/{task_list_id}/task_items/{task_item_id}.json \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}"

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS"
	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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS")
		.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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS',
  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 requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = 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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS")
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

{
  "task_item": {
    "created_at": "2025-08-06T17:09:00Z",
    "description": "Check prior contacts with the customer",
    "id": "01KH2TPNQR5WB7MV9XEJD0FZHS",
    "is_completed": false,
    "is_custom": true,
    "name": "Review ticket history",
    "updated_at": "2025-08-06T17:09:00Z",
    "url": "https://{subdomain}.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS.json"
  }
}

Update Task Item

• PUT /api/v2/task_lists/{task_list_id}/task_items/{task_item_id}

Updates a task item. Available fields depend on the item type:

Any task item: Use completed to mark the item complete (true) or incomplete (false). This is reflected as is_completed in the response. Completing all task items in a task list automatically marks the task list as completed.

Custom task items only: Also supports updating name and description. Template-based task items cannot be renamed.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
task_item_id	string	Path	true	The id of the task item
task_list_id	string	Path	true	The id of the task list

Example body

{
  "task_item": {
    "completed": true,
    "description": "Updated description",
    "name": "Updated task name"
  }
}

Code Samples

Curl

curl --request PUT https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--data-raw '{
  "task_item": {
    "completed": true,
    "description": "Updated description",
    "name": "Updated task name"
  }
}'

Go

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS"
	method := "PUT"
	payload := strings.NewReader(`{
  "task_item": {
    "completed": true,
    "description": "Updated description",
    "name": "Updated task name"
  }
}`)
	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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"task_item\": {
    \"completed\": true,
    \"description\": \"Updated description\",
    \"name\": \"Updated task name\"
  }
}""");
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({
  "task_item": {
    "completed": true,
    "description": "Updated description",
    "name": "Updated task name"
  }
});

var config = {
  method: 'PUT',
  url: 'https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS',
  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 requests
import json
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS"

payload = json.loads("""{
  "task_item": {
    "completed": true,
    "description": "Updated description",
    "name": "Updated task name"
  }
}""")
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"PUT",
	url,
	auth=auth,
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS")
request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")
request.body = %q({
  "task_item": {
    "completed": true,
    "description": "Updated description",
    "name": "Updated task name"
  }
})
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

curl (mark complete)

curl https://{subdomain}.zendesk.com/api/v2/task_lists/{task_list_id}/task_items/{task_item_id}.json \
  -H "Content-Type: application/json" \
  -d '{
    "task_item": {
      "completed": true
    }}' \
  -H "Authorization: Bearer {access_token}" -X PUT

curl (rename custom item)

curl https://{subdomain}.zendesk.com/api/v2/task_lists/{task_list_id}/task_items/{task_item_id}.json \
  -H "Content-Type: application/json" \
  -d '{
    "task_item": {
      "name": "Updated task name",
      "description": "Updated description"
    }}' \
  -H "Authorization: Bearer {access_token}" -X PUT

Example response(s)

200 OK

// Status 200 OK

{
  "task_item": {
    "created_at": "2025-08-06T17:09:00Z",
    "description": "Check prior contacts with the customer",
    "id": "01KH2TPNQR5WB7MV9XEJD0FZHS",
    "is_completed": true,
    "is_custom": true,
    "name": "Review ticket history",
    "updated_at": "2025-08-06T17:10:00Z",
    "url": "https://{subdomain}.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS.json"
  }
}

Delete Custom Task Item

• DELETE /api/v2/task_lists/{task_list_id}/task_items/{task_item_id}

Deletes the specified custom task item from its task list. Only custom task items (those not inherited from a template) can be deleted. Deleting a task item decrements task_count on the parent task list.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
task_item_id	string	Path	true	The id of the task item
task_list_id	string	Path	true	The id of the task list

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/task_lists/{task_list_id}/task_items/{task_item_id}.json \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" -X DELETE

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS"
	method := "DELETE"
	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/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS")
		.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("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS',
  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 requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"DELETE",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS")
request = Net::HTTP::Delete.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)

204 No Content

// Status 204 No Content

null

Create Subticket

• POST /api/v2/tickets/{ticket_id}/task_items/{task_item_id}/subticket

Creates a ticket and links it to the specified task item as a subticket. The parent ticket must not already be a subticket.

subject and comment.body are required. comment.body can contain up to 1,000 characters.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
task_item_id	string	Path	true	The id of the task item
ticket_id	integer	Path	true	The ID of the ticket

Example body

{
  "subticket": {
    "comment": {
      "body": "Please provision a laptop for the new hire."
    },
    "requester_id": 123,
    "subject": "Need a laptop"
  }
}

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/task_items/{task_item_id}/subticket.json \
  -H "Content-Type: application/json" \
  -d '{
    "subticket": {
      "subject": "Need a laptop",
      "requester_id": 123,
      "comment": {
        "body": "Please provision a laptop for the new hire."
      }
    }}' \
  -H "Authorization: Bearer {access_token}" -X POST

Go

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://example.zendesk.com/api/v2/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/subticket"
	method := "POST"
	payload := strings.NewReader(`{
  "subticket": {
    "comment": {
      "body": "Please provision a laptop for the new hire."
    },
    "requester_id": 123,
    "subject": "Need a laptop"
  }
}`)
	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/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/subticket")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"subticket\": {
    \"comment\": {
      \"body\": \"Please provision a laptop for the new hire.\"
    },
    \"requester_id\": 123,
    \"subject\": \"Need a laptop\"
  }
}""");
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({
  "subticket": {
    "comment": {
      "body": "Please provision a laptop for the new hire."
    },
    "requester_id": 123,
    "subject": "Need a laptop"
  }
});

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/subticket',
  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 requests
import json
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/subticket"

payload = json.loads("""{
  "subticket": {
    "comment": {
      "body": "Please provision a laptop for the new hire."
    },
    "requester_id": 123,
    "subject": "Need a laptop"
  }
}""")
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = 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/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/subticket")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "subticket": {
    "comment": {
      "body": "Please provision a laptop for the new hire."
    },
    "requester_id": 123,
    "subject": "Need a laptop"
  }
})
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)

201 Created

// Status 201 Created

{
  "subticket": {
    "id": 456
  },
  "task_object_link": {
    "created_at": "2025-08-06T17:10:00Z",
    "created_by": {
      "id": 123,
      "name": "Ada Lovelace"
    },
    "id": "01KH2Y95EFXWNA0BVXD4R2JH22",
    "linked_object_status": "New",
    "nice_id": 456,
    "object_type": "Ticket",
    "private": false,
    "task_item_instance_id": "01KH2TPNQR5WB7MV9XEJD0FZHS",
    "updated_at": "2025-08-06T17:10:00Z",
    "updated_by": {
      "id": 123,
      "name": "Ada Lovelace"
    }
  }
}

List Linked Tickets

• GET /api/v2/tickets/{ticket_id}/task_items/{task_item_id}/task_links

Returns tickets linked to the specified task item.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
task_item_id	string	Path	true	The id of the task item
ticket_id	integer	Path	true	The ID of the ticket

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/task_items/{task_item_id}/task_links.json \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}"

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links"
	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/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links")
		.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/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links',
  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 requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = 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/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links")
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

{
  "task_object_links": [
    {
      "created_at": "2025-08-06T17:10:00Z",
      "created_by": {
        "id": 123,
        "name": "Ada Lovelace"
      },
      "id": "01KH2Y95EFXWNA0BVXD4R2JH22",
      "linked_object_status": "Open",
      "nice_id": 456,
      "object_type": "Ticket",
      "private": false,
      "task_item_instance_id": "01KH2TPNQR5WB7MV9XEJD0FZHS",
      "updated_at": "2025-08-06T17:10:00Z",
      "updated_by": {
        "id": 123,
        "name": "Ada Lovelace"
      }
    }
  ]
}

Link Existing Ticket

• POST /api/v2/tickets/{ticket_id}/task_items/{task_item_id}/task_links

Links an existing ticket to the specified task item. A task item can have one linked ticket.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
task_item_id	string	Path	true	The id of the task item
ticket_id	integer	Path	true	The ID of the ticket

Example body

{
  "link": {
    "linked_object_id": "456",
    "object_type": "Ticket"
  }
}

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/task_items/{task_item_id}/task_links.json \
  -H "Content-Type: application/json" \
  -d '{
    "link": {
      "object_type": "Ticket",
      "linked_object_id": "456"
    }}' \
  -H "Authorization: Bearer {access_token}" -X POST

Go

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://example.zendesk.com/api/v2/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links"
	method := "POST"
	payload := strings.NewReader(`{
  "link": {
    "linked_object_id": "456",
    "object_type": "Ticket"
  }
}`)
	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/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"link\": {
    \"linked_object_id\": \"456\",
    \"object_type\": \"Ticket\"
  }
}""");
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({
  "link": {
    "linked_object_id": "456",
    "object_type": "Ticket"
  }
});

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links',
  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 requests
import json
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links"

payload = json.loads("""{
  "link": {
    "linked_object_id": "456",
    "object_type": "Ticket"
  }
}""")
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = 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/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "link": {
    "linked_object_id": "456",
    "object_type": "Ticket"
  }
})
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)

201 Created

// Status 201 Created

{
  "task_object_link": {
    "created_at": "2025-08-06T17:10:00Z",
    "created_by": {
      "id": 123,
      "name": "Ada Lovelace"
    },
    "id": "01KH2Y95EFXWNA0BVXD4R2JH22",
    "linked_object_status": "Open",
    "nice_id": 456,
    "object_type": "Ticket",
    "private": false,
    "task_item_instance_id": "01KH2TPNQR5WB7MV9XEJD0FZHS",
    "updated_at": "2025-08-06T17:10:00Z",
    "updated_by": {
      "id": 123,
      "name": "Ada Lovelace"
    }
  }
}

Unlink Ticket

• DELETE /api/v2/tickets/{ticket_id}/task_items/{task_item_id}/task_links/{task_object_link_id}

Deletes the link between the specified task item and ticket. This does not delete the ticket or the task item.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
task_item_id	string	Path	true	The id of the task item
task_object_link_id	string	Path	true	The id of the task object link
ticket_id	integer	Path	true	The ID of the ticket

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/task_items/{task_item_id}/task_links/{task_object_link_id}.json \
  -H "Authorization: Bearer {access_token}" -X DELETE

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links/01KH2Y95EFXWNA0BVXD4R2JH22"
	method := "DELETE"
	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/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links/01KH2Y95EFXWNA0BVXD4R2JH22")
		.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("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://example.zendesk.com/api/v2/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links/01KH2Y95EFXWNA0BVXD4R2JH22',
  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 requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links/01KH2Y95EFXWNA0BVXD4R2JH22"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"DELETE",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/tickets/123456/task_items/01KH2TPNQR5WB7MV9XEJD0FZHS/task_links/01KH2Y95EFXWNA0BVXD4R2JH22")
request = Net::HTTP::Delete.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)

204 No Content

// Status 204 No Content

null

List Parent Ticket References

• GET /api/v2/tickets/{ticket_id}/parent_ticket_tasks

Returns parent tickets and task items that link to the specified subticket. If the ticket has no parent task links, parent_ticket_tasks is empty.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
ticket_id	integer	Path	true	The ID of the ticket

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/parent_ticket_tasks.json \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}"

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/tickets/123456/parent_ticket_tasks"
	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/tickets/123456/parent_ticket_tasks")
		.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/tickets/123456/parent_ticket_tasks',
  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 requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/tickets/123456/parent_ticket_tasks"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = 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/tickets/123456/parent_ticket_tasks")
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

{
  "parent_ticket_tasks": [
    {
      "parent_ticket_id": 123456,
      "private": false,
      "status": "Open",
      "task_items": [
        {
          "description": "Create the employee hardware request",
          "name": "Provision laptop",
          "task_item_id": "01KH2TPNQR5WB7MV9XEJD0FZHS"
        }
      ]
    }
  ]
}