Cloud
Forms / Reference / REST API

Rate this page:

Forms on Issue

Postman Collection
OpenAPI
GET

Get form attachments metadataExperimental

Retrieve metadata for all attachments in a form on an issue.

Permissions required:

Scopes

Connect app scope requiredREAD

read:jira-work

Request

Path parameters

issueIdOrKey

string

Required
formId

string

Required

Responses

Returned when the metadata associated with the attachment fields on the form are successfully retrieved.

application/json

FormAttachmentsMetadata

A response containing all the form's attachments.

GET/issue/{issueIdOrKey}/form/{formId}/attachment
1 2 3 4 curl --request GET \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}/attachment' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'
200Response
1 2 3 { "fields": {} }
GET

Get formExperimental

Gets a single form on an issue as a complete JSON object.

Permissions required:

Scopes

Connect app scope requiredREAD

read:jira-work

Request

Path parameters

issueIdOrKey

string

Required
formId

string

Required

Responses

Returned when the form is retrieved successfully.

application/json

Form

A form associated with an issue or request.

GET/issue/{issueIdOrKey}/form/{formId}
1 2 3 4 curl --request GET \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 { "id": "c18bde7a-d846-11ed-afa1-0242ac120002", "updated": "2023-04-11T08:59:18Z", "design": { "conditions": {}, "layout": [ {} ], "questions": {}, "sections": {}, "settings": { "name": "New employee onboarding", "language": "en", "submit": { "lock": true, "pdf": true } } }, "state": { "visibility": "i", "status": "o", "answers": {} } }
PUT

Save form answersExperimental

Saves form answers on an issue.

Permissions required:

Scopes

Connect app scope requiredWRITE

write:jira-work

Request

Path parameters

issueIdOrKey

string

Required
formId

string

Required

Request bodyapplication/json

A request to save form answers.

answers

object

Required

Responses

Returned when form answers are successfully saved.

application/json

Form

A form associated with an issue or request.

PUT/issue/{issueIdOrKey}/form/{formId}
1 2 3 4 5 6 7 8 curl --request PUT \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "answers": {} }'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 { "id": "c18bde7a-d846-11ed-afa1-0242ac120002", "updated": "2023-04-11T08:59:18Z", "design": { "conditions": {}, "layout": [ {} ], "questions": {}, "sections": {}, "settings": { "name": "New employee onboarding", "language": "en", "submit": { "lock": true, "pdf": true } } }, "state": { "visibility": "i", "status": "o", "answers": {} } }
DEL

Delete formExperimental

Deletes a form from an issue.

Permissions required:

Scopes

Connect app scope requiredDELETE

write:jira-work

Request

Path parameters

issueIdOrKey

string

Required
formId

string

Required

Responses

Returned when the form is deleted successfully.

application/json

string

DEL/issue/{issueIdOrKey}/form/{formId}
1 2 3 4 curl --request DELETE \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'
200Response
1 "<string>"
GET

Get form PDFExperimental

Gets a single form on an issue as a PDF file.

Permissions required:

Scopes

Connect app scope requiredREAD

read:jira-work

Request

Path parameters

issueIdOrKey

string

Required
formId

string

Required

Responses

Returned when the pdf is retrieved successfully.

application/pdf

string

GET/issue/{issueIdOrKey}/form/{formId}/format/pdf
1 2 3 4 curl --request GET \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}/format/pdf' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/pdf'
GET

Get form indexExperimental

Gets a list of forms on the issue with basic metadata about them.

Permissions required:

Scopes

Connect app scope requiredREAD

read:jira-work

Request

Path parameters

issueIdOrKey

string

Required

Responses

The list of forms on the issue.

application/json

array<FormIndexEntry>

GET/issue/{issueIdOrKey}/form
1 2 3 4 curl --request GET \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 [ { "id": "<string>", "formTemplate": { "id": "<string>" }, "internal": true, "submitted": true, "lock": true, "name": "<string>", "updated": "<string>" } ]
POST

Add formExperimental

Adds a form template to an issue.

Permissions required:

Scopes

Connect app scope requiredWRITE

write:jira-work

Request

Path parameters

issueIdOrKey

string

Required

Request bodyapplication/json

A request specifying an attach form.

formTemplate

FormTemplateRef

Required

Responses

Returned when the form template is attached successfully.

application/json

FormIndexEntry

A summary of a form associated with an issue or request.

POST/issue/{issueIdOrKey}/form
1 2 3 4 5 6 7 8 9 10 curl --request POST \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "formTemplate": { "id": "<string>" } }'
200Response
1 2 3 4 5 6 7 8 9 10 11 { "id": "<string>", "formTemplate": { "id": "<string>" }, "internal": true, "submitted": true, "lock": true, "name": "<string>", "updated": "<string>" }
PUT

Submit formExperimental

Changes the status of a form on an issue to submitted.

Depending on how the form is configured the form may either enter the submitted state or the locked state. Locked forms are considered to be submitted and locked and can only be reopened by project admins.

The current iteration of this API does not check that form answers are valid.

Permissions required:

Scopes

Connect app scope requiredWRITE

write:jira-work

Request

Path parameters

issueIdOrKey

string

Required
formId

string

Required

Responses

Returned when the form is submitted successfully.

application/json

FormStatusResponse

A response indicating the current status of a form on an issue or request.

PUT/issue/{issueIdOrKey}/form/{formId}/action/submit
1 2 3 4 curl --request PUT \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}/action/submit' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'
200Response
1 2 3 { "status": "open" }
PUT

Reopen formExperimental

Changes the status of a submitted form on an issue to open to enable editing. Locked forms can only be reopened by a project admin.

Permissions required:

Scopes

Connect app scope requiredWRITE

write:jira-work

Request

Path parameters

issueIdOrKey

string

Required
formId

string

Required

Responses

Returned when the form is reopened successfully.

application/json

FormStatusResponse

A response indicating the current status of a form on an issue or request.

PUT/issue/{issueIdOrKey}/form/{formId}/action/reopen
1 2 3 4 curl --request PUT \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}/action/reopen' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'
200Response
1 2 3 { "status": "open" }
POST

Copy formsExperimental

Copy forms from one issue to another.

Permissions required:

Scopes

Connect app scope requiredWRITE

write:jira-work

Request

Path parameters

sourceIssueIdOrKey

string

Required
targetIssueIdOrKey

string

Required

Request bodyapplication/json

A request with a list of form IDs to copy.

ids

array<string>

Responses

Returned when the forms are copied successfully, or with partial success.

application/json

CopyFormsResponse

Response after copying forms.

POST/issue/{sourceIssueIdOrKey}/form/copy/{targetIssueIdOrKey}
1 2 3 4 5 6 7 8 9 10 curl --request POST \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{sourceIssueIdOrKey}/form/copy/{targetIssueIdOrKey}' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "ids": [ "<string>" ] }'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 { "errors": [ { "id": "<string>", "status": 28, "code": "<string>", "title": "<string>", "detail": "<string>", "context": [ { "type": "<string>", "id": "<string>" } ] } ], "copiedForms": [ { "id": "<string>", "newId": "<string>" } ] }
GET

Get form XLSXExperimental

Gets a single form on an issue as an XLSX file.

Permissions required:

Scopes

Connect app scope requiredREAD

read:jira-work

Request

Path parameters

issueIdOrKey

string

Required
formId

string

Required

Responses

Returned when the xlsx is retrieved successfully.

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

string

GET/issue/{issueIdOrKey}/form/{formId}/format/xlsx
1 2 3 4 curl --request GET \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}/format/xlsx' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
GET

Get form simplified answersExperimental

Gets the answers from a form on an issue that are simplified into a flattened list for scripting tool ease of use. Multivalued answers will be flattened to a comma-separated string.

Permissions required:

Scopes

Connect app scope requiredREAD

read:jira-work

Request

Path parameters

issueIdOrKey

string

Required
formId

string

Required

Responses

Returned when the form answers are retrieved successfully.

application/json

array<FormSimplifiedAnswer>

GET/issue/{issueIdOrKey}/form/{formId}/format/answers
1 2 3 4 curl --request GET \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}/format/answers' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 [ { "label": "<string>", "fieldKey": "<string>", "answer": "<string>", "choice": "<string>" } ]
GET

Get external form dataExperimental

Get all external form data for questions and answers on a form on an issue. Forms can be linked to external sources including Jira fields and data connections, with this API returning the latest responses on these linked fields.

Permissions required:

Scopes

Connect app scope requiredREAD

read:jira-work

Request

Path parameters

issueIdOrKey

string

Required
formId

string

Required

Responses

The external field data for questions and answers on a form.

application/json

ExternalFieldDataResponse

A response containing all external data for questions and answers on a form.

GET/issue/{issueIdOrKey}/form/{formId}/externaldata
1 2 3 4 curl --request GET \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}/externaldata' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'
200Response
1 2 3 { "fields": {} }
PUT

Change visibility to externalExperimental

Changes the visibility of a form on an issue from internal only to external. External forms can be viewed in the portal by customers.

Permissions required:

Scopes

Connect app scope requiredWRITE

write:jira-work

Request

Path parameters

issueIdOrKey

string

Required
formId

string

Required

Responses

Returned when the form is successfully set to external.

application/json

FormVisibilityResponse

The visibility of a form on an issue or request.

PUT/issue/{issueIdOrKey}/form/{formId}/action/external
1 2 3 4 curl --request PUT \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}/action/external' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'
200Response
1 2 3 { "visibility": "internal" }
PUT

Change visibility to internalExperimental

Changes the visibility of a form on an issue from external to internal only. Internal forms can not be viewed in the portal by customers.

Permissions required:

Scopes

Connect app scope requiredWRITE

write:jira-work

Request

Path parameters

issueIdOrKey

string

Required
formId

string

Required

Responses

Returned when the form is successfully set to internal.

application/json

FormVisibilityResponse

The visibility of a form on an issue or request.

PUT/issue/{issueIdOrKey}/form/{formId}/action/internal
1 2 3 4 curl --request PUT \ --url 'https://api.atlassian.com/jira/forms/cloud/{cloudId}/issue/{issueIdOrKey}/form/{formId}/action/internal' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'
200Response
1 2 3 { "visibility": "internal" }