The forms REST API provides programmatic access to forms in Jira Cloud. Use this API to build apps that work with forms, automate form workflows with scripting, and export form data for processing elsewhere.
Forms in all editions of Jira Cloud are supported, including Jira Service Management, Jira Software, and Jira Work Management. ProForma is referred to as Advanced forms in Jira Work Management, with the forms REST API working with this type only. Learn more about advanced forms in Jira Work Management.

Note: the authentication methods described below use different URIs.

Forge apps

Forge apps can access the forms API easily by using product authentication. Use the requestJira() method of the product fetch API to have authentication applied automatically. Forge apps must declare OAuth 2.0 scopes to be authorized to access forms APIs.

The URIs for Forge app REST API calls have this structure:

/forms/<resource-name>

For example: /forms/issue/ISS-1/form/c18bde7a-d846-11ed-afa1-0242ac120002

Connect apps

For Connect apps, authentication (JWT-based) is built into the Connect libraries. Authorization is implemented using either scopes (shown as App scope required for operations on this page) or user impersonation. See Security for Connect apps for details.

The URIs for Connect app REST API calls have this structure:

https://<site-url>/gateway/api/jira/forms/cloud/<cloudId>/<resource-name>

For example: https://your-domain.atlassian.net/gateway/api/jira/forms/cloud/33398233-27d5-48f6-9dea-d0ea33d97528/forms/issue/ISS-1/form/c18bde7a-d846-11ed-afa1-0242ac120002

Other integrations

For integrations that are not Forge or Connect apps, use OAuth 2.0 authorization code grants (3LO) for security (3LO scopes are shown as for operations OAuth scopes required). See OAuth 2.0 (3LO) apps for details.

The URIs for OAuth 2.0 (3LO) app REST API calls have this structure:

https://api.atlassian.com/ex/jira/<cloudId>/forms/<resource-name>

For example: https://api.atlassian.com/ex/jira/33398233-27d5-48f6-9dea-d0ea33d97528/forms/issue/ISS-1/form/c18bde7a-d846-11ed-afa1-0242ac120002

Ad-hoc API calls

For personal scripts, bots, and ad-hoc execution of the REST APIs use basic authentication. See Basic auth for REST APIs for details. The URIs for basic authentication method have this structure:

https://api.atlassian.com/jira/forms/cloud/<cloudId>/<resource-name>

For example: https://api.atlassian.com/jira/forms/cloud/33398233-27d5-48f6-9dea-d0ea33d97528/issue/ISS-1/form/c18bde7a-d846-11ed-afa1-0242ac120002

Guides

To learn more about authentication and authorization, view the security overview.

The forms REST API uses standard HTTP status codes, with one code being adapted slightly for use in the forms API.

412 Precondition Failed

This response code is applied in two distinct situations:

• When the X-ExperimentalApi: opt-in header is not present.

• When a form possesses an invalid or unsupported value.

Error Codes

Responses that return an error status code will also return a response body containing an errors array with one or more errors. For example:

1
2
{
  "errors": [
    {
      "status": 404,
      "code": "EXAMPLE_NOT_FOUND",
      "title": "Example Not Found",
      "detail": "Example error detail.",
      "context": [
          {
              "type": "example",
              "id": "EXMPL-1"
          }
      ]
    }
  ]
}

Each error will contain status, code, and title at a minimum. Refer to the documentation of individual endpoints below for more specific information about possible errors.

Experimental features

Features and methods marked as experimental may change without notice. Note that currently all methods are marked experimental. To call experimental methods the X-ExperimentalApi: opt-in header must be provided on the request.

Using basic auth

Get the cloudId for a Jira instance by calling https://your-domain.atlassian.net/_edge/tenant_info and then call the API by following the Basic auth for REST APIs instructions in either of the following approaches.

Simple example

You can use an email address associated with an Atlassian account and the API token to build required authentication headers. For example, to get form index, you can specify the -u argument in the example curl command as follows:

1
2
curl -D- \
   -u <your_email@domain.com>:<your_user_api_token> \
   -X GET \
   -H "Content-Type: application/json" \
   -H "X-ExperimentalApi: opt-in" \
   https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/ISS-1/form

Replace <your_email@domain.com>and <your_user_api_token> with your user information and {cloudId} instance information before running it in the terminal.

Supply basic auth headers

Alternatively you can construct and send basic auth headers as follows:

1
2
curl -D- \
   -X GET \
   -H "Authorization: Basic ZnJlZDpmcmVk" \
   -H "Content-Type: application/json" \
   -H "X-ExperimentalApi: opt-in" \
   https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/ISS-1/form

Using Forge

1
2
import api, {route} from "@forge/api";
await api
   .asUser()
   .requestJira(route`/forms/issue/ISS-1/form`)

Using Connect app

1
2
export function callFormsApi(addon) {
  return (req, res) => {
    const httpClient = addon.httpClient(req);
    httpClient.asUserByAccountId(accountId).get(
        {
          headers: {
            Accept: "*/*",
            "X-ExperimentalAPI": "opt-in",
          },
          url = "/gateway/api/jira/forms/cloud/33398233-27d5-48f6-9dea-d0ea33d97528/forms/issue/ISS-1/form",
        },
        function (err, response, body) {
          if (err || response.statusCode >= 400) {
            console.log(`API call failed: ${response.statusCode}: ${err}`);
          } else {
            console.log(`API call succeeded: ${response.statusCode}: ${body}`);
          }
        }
    );
} ```

Any of the resources that require a {serviceDeskId} path parameter also accepts other identifiers.

For example, if a ServiceDesk(id: 15) corresponds to a Project(id: 10012, key: ABC) and this project has a RequestType(id: 56), then issuing a request to any of:

1
2
/servicedesk/ABC/requesttype/56/form

/servicedesk/projectKey:ABC/requesttype/56/form

/servicedesk/projectId:10012/requesttype/56/form

/servicedesk/serviceDeskId:15/requesttype/56/form

is equivalent to issuing a request to:

1
2
/servicedesk/15/requesttype/56/form

Limitations to the Forms REST API include:

• Experimental methods changing in backward-incompatible ways. To opt-in to these methods, X-ExperimentalApi: opt-in request header is required.

• The submit form endpoint doesn’t check whether form answers are valid. Callers are expected to validate answers before calling the submit form endpoint.