Page Comparison

Table of Contents

maxLevel	3
exclude	On this page

...

You can use the Jira REST API to interact with the Issue Checklist. This page documents the REST resources available to use, including example requests and responses. Use this API to build script interactions with your checklist, or develop any other type of integration.

Note

This guide applies to Jira REST API version 2 calls only. While the latest Jira REST API version is 3, it

is still in beta and doesn't work with the Issue Checklist

does not currently work with Checklists.

Note

This guide applies to Jira Company-managed (Classic) projects only. Team-managed (Next-Gen) projects do not support global custom fields, which are required for checklist REST API access.
Note that you can access checklist data from local (not Global) checklists stored in custom fields even if the

...

Checklist app has been uninstalled.
The endpoints described here access local checklists only. You can use entity properties to access the overall state of checklists on the issue, with global checklists included.

Requirements

To use Issue Checklists with the API, the Save checklist data to Jira custom fields global setting must be enabled.
To update or remove an existing checklist via the API, the Checklist Text custom field must be present on the Edit issue screen. Follow these instructions for adding a custom field to a screen.
No configuration are required for reading a checklist, or checklist metadata via the API.

...

Item	Replace with	Example
email@example.com	The email address provided in your Atlassian ID account	stefan@herocoders.com
`<api_token>`	A valid API token for your Atlassian ID	`J3D4smrVz29cxzsd`
https://your-domain.atlassian.net	The URL of your Jira Cloud instance	`https://herocoders.atlassian.net`
`{issueIdOrKey}`	The relevant issue key	`DEMO-1`
`"customfield_10034"XXXXX"` where XXXXX is the custom field ID number	The ID of the Checklist Text custom field in your instance. Follow these instructions for getting the custom field ID.	`"customfield_1005810034"`

...

Get, Update or Remove Checklist

Note
You will need to replace the custom field ID with the ID of the Checklist Text fieldin your instance.

Get a Checklist

GET /rest/api/2/issue/{issueIdOrKey} (reference)

Returns the details of an issue, including the checklist in text format.

...

Code Block

breakoutMode	wide

{
  "expand": "",
  "id": "10002",
  "self": "https://your-domain.atlassian.net/rest/api/2/issue/10002",
  "key": "DEMO-1",
  "fields": {
  (...) // omitted for brevity
    "customfield_10034XXXXX": "--- Tested on\n* Chrome\n* Safari\n* Firefox\n* Edge\n* [x] IE11",
  }
  (...) // omitted for brevity
}

...

Create or Update a Checklist

PUT /rest/api/2/issue/{issueIdOrKey} (reference)

Updates the issue by adding or updating a formatted checklist.

...

Code Block

breakoutMode	full-width

curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": {
      "customfield_10034XXXXX": "--- Tested on\n* [x] Chrome\n* Safari\n* Firefox\n* Edge\n* [x] IE11\n--- Mobile\n* Android\n* iPhone"
    }
  }'

...

Code Block

breakoutMode	full-width

{"errorMessages":[],"errors":{"customfield_10034":"Field 'customfield_10034XXXXX' cannot be set. It is not on the appropriate screen, or unknown."}}

...

Code Block

curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": {
      "customfield_10034XXXXX": null
    }
  }'

Read, Modify & Update Checklists

...

Retrieve a representation of the issue via GET /rest/api/2/issue/{issueIdOrKey}
Using Checklist Text field id, extract and parse checklist value: representation → fields → customfield_xxxxx XXXXX (parse items by new line characters)
Modify the parsed checklist as needed. For example, to check an item as complete, put an "x" in the square brackets (so that "* [] summary" becomes "* [x] summary").
Upload the modified value back to the issue via PUT /rest/api/2/issue/{issueIdOrKey}

...

Expand

title	Example: Add a Checklist to an Issue (cURL)

Open terminal.
Save the content of the snippet below to a local file, e.g. example.json:
Text
Code Block
{"fields": {"customfield_12345XXXXX": "[x] example item"}}
Replace customfield_12345 string with the ID of Checklist Text custom field in your Jira instance. See instructions here for finding custom field ID.
Type following command in the terminal.
Code Block
curl -D- -u "jack@herocoders.com:api_token" --request PUT --header "Content-Type: application/json" --url 'https://jiraUrl.atlassian.net/rest/api/2/issue/DEMO-1' --data-binary @example.json
Replace jack@herocoders.com with the email address provided in your Atlassian ID account.
Replace api_token with a valid token generated in your Atlassian ID account (see instructions for generating tokens).
Replace jiraUrl with URL of your Jira instance.
Replace DEMO-1 with the appropriate issue key.
Go to Jira issue page to confirm that:
1. Checklist has been updated and contains a single checked item "example item".
2. The Checklist Text field has been updated with the checklist provided in example.json file. This will be visible if the Checklist Text field is on theView Issue Screen:
  
  You can also see that the other checklist custom fields (Checklist Progress and Checklist Completed) has been updated accordingly.

...

Info
Note that the API can also be used to retrieve checklist metadata stored in issue entity properties. Note that entity properties will reflect the sum of both local and global checklists on the issue.

Versions Compared

Old Version 3

New Version 4

Key

Requirements

Get, Update or Remove Checklist

Get a Checklist

Create or Update a Checklist

Read, Modify & Update Checklists