Modifying checklists using a 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’ }).

The only supported update operation is the set operation. 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.

JSON schema structure

When a checklist is manipulated with REST APIs, it will be an array of checklist items.
[ checklist-item, checklist-item, ...]

The properties of a checklist item are as follows:

Parameter	Type	Description			Accessibility
`name` (mandatory)	String	The name of the checklist item. The names of global items cannot be changed.			read-write
`id`	Number	The ID for the checklist item. The ID is automatically created and does not need to be manually set. If you do set an ID, ensure that it is unique across the entire checklist.			read-write
`isHeader`	Boolean	Whether the item is a header or not. Can only be set to `true` if the Section Headings setting is enabled.			read-write
`rank`	Number	The rank of the item in the checklist, starting from 0. When the checklist is updated, the rank value is ignored, and the order in which the items are set in the array of checklist items is applied.			read
`checked`	Boolean	Whether the item is checked or not. A disabled global item cannot be checked.			read-write
`option`	Boolean	Whether the item is a global item (previously called an “option”) or not. It this value is set to `true`, the item ID must be set to a valid global item ID. Global items cannot be created through this REST interface.			read-write
`mandatory`	Boolean	Whether the item is mandatory or not.			read-write
`assigneeIds`	String[]	A list of the usernames to which the item is assigned (only one assignee is currently supported). Can only be set if the User Assignment setting is enabled.			read-write
`priorityId`	String	The numeric priority ID of the item as a string. Can only be set if the Priorities setting is enabled.			read-write
`dueDate`	String	The due date of the item as an ISO string. Can only be set if the Due Dates setting is enabled.			read-write
`status`	Object	The object that contains the status information. Only valid status IDs are accepted. Can only be updated if the Statuses setting is enabled. Also comes with the following sub-parameters:			read-write
		`name`	String	The name of the status.	read
		`id`	String	The status ID.	read-write

Sample request payload

Here is a sample request that updates a Checklist custom field value with one global item and one local item:

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

JSON schema structure

Sample request payload

SERVER DOCUMENTATION (On Cloud? Go here.)

Have questions? Contact our Service Desk for help anytime.