Updating checklists using Jira's REST API

You can manipulate checklists using Jira’s REST APIs to:

Retrieve an issue's checklist data.
- Use Jira’s Get Issue REST API.
Create an issue and supply checklist data.
- Use Jira’s Create Issue REST API.
Update an existing issue’s checklist data.
- Use Jira’s Edit Issue REST API.
Get the default value of a checklist, meaning the global items and default items.
- Use Jira’s CreateMeta REST API or EditMeta REST API.
- The data is available in the allowedValues property.
- The status returned by these APIs will only have an ID and no name.
  (e.g. { id: ‘inProgress’ } } and not { id: ‘inProgress’, name: ‘In Progress’ }).

JSON schema structure

See here for the checklist item JSON structure for Jira REST APIs.

Update operations

When you update an issue, you can perform different operations on the checklist. Here’s a list of supported operations and how to use them.

Set

The set operation overwrites the whole checklist with a new set of items. This means that all checklist items (including global items) must be provided on every update. As a result, a good operation workflow would be to query the existing issue value, modify the payload, and update it back.

Example payload of a set operation with one global item and one local item:

JSON

{
	"update": {
		"customfield_10101": [
			{
				"set": [
					{
						"id": 1,
						"name": "Code Review",
						"checked": false,
						"mandatory": true,
						"priorityId": "2",
						"dueDate": "2020-01-25T00:00:00.000Z",
						"assigneeIds": ["admin"],
						"globalItemId": 12001
					},
					{
						"id": 2,
						"name": "Reviewed by Architect",
						"checked": false,
						"mandatory": true,
						"status": {
							"id": "inProgress"
						}
					}
				]
			}
		]
	}
}

Add

The add operation lets you add local items to an existing list. When an item is added, the id field is ignored, and a new identifier is generated for the item.

The rank is a zero-based position that represents where the item will be located in the checklist. If no rank is provided, the item will automatically be added at the end of the checklist.

Example payload that adds two items, with one at the beginning of the checklist, and one at the end:

JSON

{
	"update": {
		"customfield_10101": [
			{
				"add": [
					{
						"name": "Run integration tests",
						"status" {
							"id": "blocked"
						},
						"rank": 0
					},
					{
						"name": "Publish to production"
					}
				]
			}
		]
	}
}

Edit

The edit operation lets you modify an item in the checklist. The id field is required to identify which item will be modified.

The rank is a zero-based position that represents where the item will be located in the checklist.

Example payload that moves an item to the 4th position in the list and changes the due date and priority of another item:

JSON

{
	"update": {
		"customfield_10101": [
			{
				"edit": [
					{
						"id": 1,
						"rank": 3
					},
					{
						"id": 2,
						"dueDate": "2000-01-01T00:00:00.000Z",
						"priorityId": 2
					}
				]
			}
		]
	}
}

Remove

The remove operation lets you remove an item in the checklist. The id field is required to identify which item will be removed.

Example payload that removes the items with IDs 1 and 2:

JSON

{
	"update": {
		"customfield_10101": [
			{
				"remove": [
					{
						"id": 1
					},
					{
						"id": 2
					}
				]
			}
		]
	}
}