v1.2.0 API documentation

ProForma provides an API to make it easier for our customers to access their data. This version 1.2 the API includes the Export API and a number of new form related features in the Form API. We plan to add more features to the Form API in future versions.

Refer to ProForma API Documentation for general information about the use of this API.

Availability

The API is available in Jira Server and Jira Data Center.

The ProForma Customer API is available in the following versions of ProForma:

ProForma Customer API	ProForma version
v1.2.0 THIS VERSION	v8.4.9 and later
v1.1.0	v8.4.0 and later
v1.0.0	v8.2.0 and later

ProForma Customer API V1.2.0 OAS3

Export API

The export APIs provide a way to export all data from ProForma forms.

POST Start export

/rest/proforma/1/export

/rest/proforma/1/export

Starts an export of ProForma data. Exports are performed as a background process so this API call does not immediately return the result, instead ProForma returns an export ID which you can use to check the status and download the export later. Exporting can be either a quick or a slow process depending on how big your Jira instance is. Expect an export to take a few seconds if your project has a few hundred issues, or take a few minutes if your project has a few thousand issues. Currently ProForma supports two exports: - responses-json a JSON document containing all responses to the specified template form on the specified project. - responses-xlsx an XLSX spreadsheet containing all responses to the specified template form on the specified project.

Parameters

No parameters

Request body

application/json

The body of this POST request describes what will be exported. All form responses in the specified project that match the template form ID you specify will be exported.

Example value

{
  "type": "responses-xlsx",
  "projectKey": "ABC",
  "templateFormId": 1,
  "fields": [
    "summary",
    "priority",
    "customfield_10012"
  ],
  "jql": "(description ~ broken OR description ~ 'not working') AND created >= 2020-08-20"
}

Schema

ExportRequest {
`type*`	string example: responses-xlsx The type of export. Currently `responses-json` and `responses-xlsx` are supported.
`projectKey*`	string example: ABC A string containing the project key to export data from. Only one project can be specified; multiple projects require multiple exports.
`templateFormId*`	number example: 1 The ID of the template form to export data from. To find the ID of a template form, open the form in the ProForma form builder. The URL of that page will end in `ac.form.id`, that number is the template form ID to provide here.
`fields`	[string] example: List [ "summary", "priority", "customfield_10012" ] An optional array with the name(s) of jira fields. The export will include the values of each of these jira fields, for each issue.
`JQL`	string example: (description ~ broken OR description ~ 'not working') AND created >= 2020-08-20 An optional string containing a JQL query. The export will be limited to include only issues that match this JQL query. NB: Including the project in the JQL (e.g. project = MyServiceDesk) is not required since ProForma will automatically include it.
}

Responses

Code Description

200

Indicates that the export process has started successfully. Use the information in this response to check the status of the export later. In particular you can poll the URL returned in the statusUrl value to check the status of the export.
x-summary: Export started successfully

Media type: application/json

Example value

{
  "type": "responses-xlsx",
  "id": "responses-xlsx-ABC-1-1234567890",
  "statusUrl": "https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890"
}

Schema

ExportStartResponse {
`type*`	string example: responses-xlsx A string identifying the export type.
`id*`	string example: responses-xlsx-ABC-1-1234567890 A string identifying the export task. Each export is given this unique ID to allow it to be retrieved later.
`statusURL*`	string example: https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890 The URL of the check status API which you can call to check the progress of this export.
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

Example value

{
  "error": "client"
}

Schema

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	string A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

Example value

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

Schema

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

Example value

{
  "error": "server",
  "message": "string"
}

Schema

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ server ]
message	string A more user-friendly description of the error in English, if available.
}

Extensions

Field	Value
x-permissions	["ProForma: Export All Data"]

GET Check status of export

/rest/proforma/1/export/{exportId}

/rest/proforma/1/export/{exportId}

Checks the status of an export: whether it has completed successfully or failed, and how much progress has been made if not complete. The URL of this API will be provided to you when you start an export using the "Start export" API above. You can poll the URL returned in the statusUrl value to check the status of the export.

Parameters

Name Description

exportId*
string

(path)

Export task ID, provided by the response to the 'Start export' API.

Responses

Code Description

200

Export status loaded successfully.

Media type: application/json

Example value

{
  "type": "responses-xlsx",
  "id": "responses-xlsx-ABC-1-1234567890",
  "complete": false,
  "failed": false,
  "progress": 25
}

Schema

ExportStatusResponse {
`type*`	string example: responses-xlsx A string identifying the type of export. The only possible values in this version of the API are: - `responses-json`. - `responses-xlsx`
`id*`	string example: responses-xlsx-ABC-1-1234567890 A string identifying the export task. Each export is given this unique ID to allow it to be retrieved later.
`complete*`	boolean example: true Indicates whether the export has completed successfully. This will initially be `false` for all but the smallest projects, once it turns `true` the export has finished and the file can be downloaded.
`failed*`	boolean example: false Indicates whether the export has failed. If this is `true` then something unexpected has gone wrong in the processing of this export. Please contact us for assistance in resolving this problem.
`progress*`	number example: 25 The estimated percentage complete of this export, expressed as an integer from 0 to 100.
downloadURL	string example: https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890/ProForma-ABC-form-1.xlsx The URL where this export can be downloaded. This `downloadUrl` will not be provided until the export has successfully completed, so once it appears in the response it is safe to call the URL and download the export file.
message	string example: Error constructing JQL query A text-based message providing more information about the status (whether completed or failed) of the export.
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

Example value

{
  "error": "client"
}

Schema

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	string A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

Example value

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

Schema

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

404

ProForma could not find the export for the ID in the request. This may mean the export has been downloaded and is no longer in memory, or it may mean that the ID provided is invalid.

x-summary: Not found

Media type: application/json

Example value

{
  "error": "notFound",
  "message": "Export responses-xlsx-ABC-1-1234567890 not found"
}

Schema

NotFoundApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

Example value

{
  "error": "server",
  "message": "string"
}

Schema

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ server ]
message	string A more user-friendly description of the error in English, if available.
}

Extensions

Field	Value
x-permissions	["ProForma: Export All Data"]

GET Download export

/rest/proforma/1/export/{exportId}/{filename}

/rest/proforma/1/export/{exportId}/{filename}

Downloads the export file once it has completed processing. The URL of this API will be provided to you by calling the "Check status of export" API above. Don't call this API until the URL has been provided by the status check; this API will return an error if called before the export has finished processing. The file can only be downloaded once per export. Once you request the download from this URL the file will be deleted on the server to save resources. You will need to start another export if you wish to retrieve it again.

Parameters

Name Description

exportId*
string

(path)

Export task ID, provided by the response to the 'Start export' API.

filename*
string

(path)

Name of the export file. The filename be provided by the check status API.

Responses

Code Description

200

File download

Media type: application/json

Example value

{
  "type": "responses-xlsx",
  "id": "responses-xlsx-ABC-1-1234567890",
  "complete": false,
  "failed": false,
  "progress": 25
}

Schema

ExportStatusResponse {
`type*`	string example: responses-xlsx A string identifying the type of export. The only possible values in this version of the API are: - `responses-json`. - `responses-xlsx`
`id*`	string example: responses-xlsx-ABC-1-1234567890 A string identifying the export task. Each export is given this unique ID to allow it to be retrieved later.
`complete*`	boolean example: true Indicates whether the export has completed successfully. This will initially be `false` for all but the smallest projects, once it turns `true` the export has finished and the file can be downloaded.
`failed*`	boolean example: false Indicates whether the export has failed. If this is `true` then something unexpected has gone wrong in the processing of this export. Please contact us for assistance in resolving this problem.
`progress*`	number example: 25 The estimated percentage complete of this export, expressed as an integer from 0 to 100.
downloadURL	string example: https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890/ProForma-ABC-form-1.xlsx The URL where this export can be downloaded. This `downloadUrl` will not be provided until the export has successfully completed, so once it appears in the response it is safe to call the URL and download the export file.
message	string example: Error constructing JQL query A text-based message providing more information about the status (whether completed or failed) of the export.
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

Example value

{
  "error": "client"
}

Schema

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	string A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

Example value

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

Schema

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

404

ProForma could not find the export for the ID in the request. This may mean the export has been downloaded and is no longer in memory, or it may mean that the ID provided is invalid.

x-summary: Not found

Media type: application/json

Example value

{
  "error": "notFound",
  "message": "Export responses-xlsx-ABC-1-1234567890 not found"
}

Schema

NotFoundApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

Example value

{
  "error": "server",
  "message": "string"
}

Schema

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ server ]
message	string A more user-friendly description of the error in English, if available.
}

Extensions

Field	Value
x-permissions	["ProForma: Export All Data"]

Form API

The form APIs provide a way to interact with forms on an issue.

POST Add form to issue

/rest/proforma/1/issue/{issueKey}/form

/rest/proforma/1/issue/{issueKey}/form

Adds a form to an issue. The ID of the template form to add is provided in the body of the request, optionally along with the number of copies to add and whether to make it available externally (on the Jira Service Desk portal). ProForma will only add the form if the user calling the API has permission to edit that issue. This API does not check if the form already exists on the issue; if the form already exists on the issue that form will be added again without affecting the existing form. Multiple copies of the same form can be added by using the add parameter of the API.

Parameters

Name Description

issueKey*
string

(path)

Issue key for Jira issue

Request body

application/json

The body of this POST request describes the form to add to an issue.

Example value

{
  "templateFormId": 1,
  "visibility": "external",
  "add": 2
}

Schema

AddFormRequest {
`templateFormId*`	number example: 1 The ID of the template form to export data from. To find the ID of a template form, open the form in the ProForma form builder. The URL of that page will end in `ac.form.id`, that number is the template form ID to provide here.
`visibility`	string example: external Optional parameter specifying whether the form is visible externally (on the Jira Service Desk portal). Only applicable to Service Desk projects. The form will be an internal form if no value is specified. Enum: Array [ 2 ] [ internal, external ]
`add`	number($int64) example: 2 A number specifying the number of times to add this form. One form will be added if no value is specified.
}

Responses

Code Description

200

Indicates the form has been added successfully.
x-summary: Form added successfully

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

Example value

{
  "error": "client"
}

Schema

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	string A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

Example value

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

Schema

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

404

Proforma could not find the specified form.

x-summary: Not found

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

Example value

{
  "error": "server",
  "message": "string"
}

Schema

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ server ]
message	string A more user-friendly description of the error in English, if available.
}

Extensions

Field	Value
x-permissions	["Edit issues"]

GET Get an array containing the visible form answers

/rest/proforma/1/issue/{issueKey}/form/{formId}/answers

/rest/proforma/1/issue/{issueKey}/form/{formId}/answers

Get an array containing the visible form answers. Forms may have sections which are hidden based on conditions of the form and the answers selected. Questions in sections which are hidden by answers will not be included in this response.

Parameters

Name Description

issueKey*
string

(path)

Issue key for Jira issue.

formId*
string

(path)

ID of the ProForma form.

Responses

Code Description

200

Operation completed successfully

Media type: application/json

Example value

[
  {
    "label": "Choose three colours from the list below",
    "questionKey": "three_colours",
    "answer": "red, green, blue"
  }
]

Schema

CustomerFormAnswers [
An array of form answers, in the order that they appear within the form.
ExportStartResponse {
`label*`	string example: Choose three colors from the list below The label of the form question
`questionKey*`	string example: three_colours If present, the question key associated with the form question
`answer*`	string example: red, green, blue The answer to the form question, represented as a string
}]

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

Example value

{
  "error": "client"
}

Schema

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	string A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

Example value

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

Schema

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

Example value

{
  "error": "server",
  "message": "string"
}

Schema

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ server ]
message	string A more user-friendly description of the error in English, if available.
}

Extensions

Field	Value
x-permissions	["Browse Projects"]

POST Copy a form from one issue to another

/rest/proforma/1/issue/{issueKey}/form/{formId}/copy/{toIssueKey}

/rest/proforma/1/issue/{issueKey}/form/{formId}/copy/{toIssueKey}

Copy a form from one issue to another

Parameters

Name Description

issueKey*
string

(path)

Issue key for Jira issue.

formId*
number

(path)

ID of the ProForma form.

toIssueKey*
string

(path)

Issue key for Jira issue.

Request body

application/json

Example value

{
  "status": "open",
  "visibility": "internal"
}

Schema

CopyFormRequest {

status

FormStatusCustomer string

The status of a form, which can be

open - for forms which are open
submitted - for forms which have been submitted
locked - for forms which have been locked

Enum:

Array [ 3 ]

[ open, submitted, locked ]

visibility

FormVisibility string

The visibility of the form, which is only applicable for Service Desk projects.

internal - for forms which are set to Internal and only accessible via the Agent view
external - for forms which are set to External and accessible via the Portal

Enum:

Array [ 2 ]

[ internal, external ]

}

Responses

Code Description

200

Operation completed successfully.

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

Example value

{
  "error": "client"
}

Schema

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	string A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

Example value

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

Schema

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

Example value

{
  "error": "server",
  "message": "string"
}

Schema

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ server ]
message	string A more user-friendly description of the error in English, if available.
}

Extensions

Field	Value
x-permissions	["Browse Projects","Edit Issues"]

POST Submit a form

/rest/proforma/1/issue/{issueKey}/form/{formId}/submit

/rest/proforma/1/issue/{issueKey}/form/{formId}/submit

Change the status of a form attached to an issue to submitted

Parameters

Name Description

issueKey*
string

(path)

Issue key for Jira issue.

formId*
number

(path)

The number of the form attached to an issue. The number is determined by the order in which the forms are added to an issue. So the first form is 1, the second form is 2; however, if the the second form is then delete the next form will take the id 3 (not 2).

Responses

Code Description

200

The form has been successfully submitted.

Media type: application/json

Example value

{
  "status": "o",
  "transitioned": true
}

Schema

FormStateChangeResult {
The status and visibility of an issue form, as well as a flag indicating if the issue was transitioned to a new status (due to ProForma automation rules) as a result of the change.
`status`	FormStatus string The status of a form, which can be o - for forms which are open s - for forms which have been submitted l - for forms which have been locked Enum: Click here to expand... [ o, s, l ]
transitioned	boolean
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

Example value

{
  "error": "client"
}

Schema

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	string A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

Example value

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

Schema

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

Example value

{
  "error": "server",
  "message": "string"
}

Schema

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ server ]
message	string A more user-friendly description of the error in English, if available.
}

Extensions

Field	Value
x-permissions	["Edit Issues"]

POST Reopen a form

/rest/proforma/1/issue/{issueKey}/form/{formId}/reopen

/rest/proforma/1/issue/{issueKey}/form/{formId}/reopen

Change the status of a submitted form to open

Parameters

Name Description

issueKey*
string

(path)

Issue key for Jira issue.

formId*
number

(path)

The number of the form attached to an issue. The number is determined by the order in which the forms are added to an issue. So the first form is 1, the second form is 2; however, if the the second form is then delete the next form will take the id 3 (not 2).

Responses

Code Description

200

The form has been successfully reopened.

Media type: application/json

Example value

{
  "status": "o",
  "transitioned": true
}

Schema

FormStateChangeResult {
The status and visibility of an issue form, as well as a flag indicating if the issue was transitioned to a new status (due to ProForma automation rules) as a result of the change.
`status`	FormStatus string The status of a form, which can be o - for forms which are open s - for forms which have been submitted l - for forms which have been locked Enum: Click here to expand... [ o, s, l ]
transitioned	boolean
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

Example value

{
  "error": "client"
}

Schema

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	string A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

Example value

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

Schema

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

Example value

{
  "error": "server",
  "message": "string"
}

Schema

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ server ]
message	string A more user-friendly description of the error in English, if available.
}

Extensions

Field	Value
x-permissions	["Edit Issues"]

POST Unlock a form

/rest/proforma/1/issue/{issueKey}/form/{formId}/unlock

/rest/proforma/1/issue/{issueKey}/form/{formId}/unlock

Change the status of a locked form to unlocked, so it can then be reopened.

Parameters

Name Description

issueKey*
string

(path)

Issue key for Jira issue.

formId*
number

(path)

The number of the form attached to an issue. The number is determined by the order in which the forms are added to an issue. So the first form is 1, the second form is 2; however, if the the second form is then delete the next form will take the id 3 (not 2).

Responses

Code Description

200

The form has been successfully unlocked.

Media type: application/json

Example value

{
  "status": "o",
  "transitioned": true
}

Schema

FormStateChangeResult {
The status and visibility of an issue form, as well as a flag indicating if the issue was transitioned to a new status (due to ProForma automation rules) as a result of the change.
`status`	FormStatus string The status of a form, which can be o - for forms which are open s - for forms which have been submitted l - for forms which have been locked Enum: Click here to expand... [ o, s, l ]
transitioned	boolean
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

Example value

{
  "error": "client"
}

Schema

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	string A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

Example value

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

Schema

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

Example value

{
  "error": "server",
  "message": "string"
}

Schema

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ server ]
message	string A more user-friendly description of the error in English, if available.
}

Extensions

Field	Value
x-permissions	["Administer Projects","Edit Issues"]

GET Download a PDF of a form

/rest/proforma/1/issue/{issueKey}/form/{formId}/pdf

/rest/proforma/1/issue/{issueKey}/form/{formId}/pdf

Download a PDF of a form. A rich PDF is downloaded by default, or you can download a plain PDF by indicating with a query param.

Parameters

Name Description

issueKey*
string

(path)

Issue key for Jira issue.

formId*
number

(path)

The number of the form attached to an issue. The number is determined by the order in which the forms are added to an issue. So the first form is 1, the second form is 2; however, if the the second form is then delete the next form will take the id 3 (not 2).

plain
boolean

(query)

Query param to specify a plain formatted PDF

Default value : false

Responses

Code Description

200

File download

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

Example value

{
  "error": "client"
}

Schema

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	string A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

Example value

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

Schema

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

Example value

{
  "error": "server",
  "message": "string"
}

Schema

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ server ]
message	string A more user-friendly description of the error in English, if available.
}

Extensions

Field	Value
x-permissions	["Browse Projects"]

POST Change the visibility for an issue form

/rest/proforma/1/issue/{issueKey}/form/{formId}/visibility/{visibility}

/rest/proforma/1/issue/{issueKey}/form/{formId}/visibility/{visibility}

Change the visibility for an issue form. NB: The form can only have its visibility set to external for issues in a Service Desk project.

Parameters

Name Description

issueKey*
string

(path)

Issue key for Jira issue.

formId*
number

(path)

The number of the form attached to an issue. The number is determined by the order in which the forms are added to an issue. So the first form is 1, the second form is 2; however, if the the second form is then delete the next form will take the id 3 (not 2).

visibility*
string

(path)

Action to take for the issue form

Available values : internal, external

Responses

Code Description

200

Operation completed successfully.

Media type: application/json

Example value

{
  "visibility": "internal"
}

Schema

VisibilityChangeResult {
The visibility of the issue form.
`visibility`	FormVisibility string The visibility of the form, which is only applicable for Service Desk projects. internal - for forms which are set to Internal and only accessible via the Agent view external - for forms which are set to External and accessible via the Portal Enum: Array [ 1 ] [ internal, external ]
}

400

ProForma could not understand the request. This usually indicates that invalid data was provided in the API call; please check your code to confirm whether it is calling the API correctly.
x-summary: Bad request

Media type: application/json

Example value

{
  "error": "client"
}

Schema

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	string A more user-friendly description of the error in English, if available.
}

401

An error indicating that Jira did not accept the user credentials that were provided. This error indicates that either no user credentials were provided, or that the credentials were invalid. It does not indicate a problems with permissions; invalid permissions result in a 403 Forbidden error.
x-summary: Unauthorized

403

The API was called by a user who does not have permission to make that request.
x-summary: Forbidden

Media type: application/json

Example value

{
  "error": "forbidden",
  "message": "Access to this API requires a user with the 'ProForma: Export All Data' global permission"
}

Schema

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

500

An error indicating that something went wrong in either Jira or ProForma while processing this request. The error is not expected in the normal operation of the ProForma Customer API.
x-summary: Server error

Media type: application/json

Example value

{
  "error": "server",
  "message": "string"
}

Schema

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ server ]
message	string A more user-friendly description of the error in English, if available.
}

Extensions

Field	Value
x-permissions	["Edit Issues"]

Schemas

AddFormRequest

AddFormRequest {
`templateFormId*`	number($int64) example: 1 The ID of the template form to add to this issue. To find the ID of a template form, open the form in the ProForma form builder. The URL of that page will end in `ac.form.id`, that number is the template form ID to provide here.
`visibility`	number($int64) example: 2 A number specifying the number of times to add this form. One form will be added if no value is specified. Array [ 2 ] [ internal, external ]
`add`	number($int64) example: 2 A number specifying the number of times to add this form. One form will be added if no value is specified.
}

CustomerFormAnswer

CustomerFormAnswer {
`label*`	string example: Choose three colours from the list below The label of the form question
`questionKey`	string example: three_colours If present, the question key associated with the form question
`answer*`	string example: red, green, blue The answer to the form question, represented as a string
}

CustomerFormAnswers

CustomerFormAnswers [
An array of form answers, in the order that they appear within the form.
CustomerFormAnswers {
`label*`	string example: Choose three colours from the list below The label of the form question
`questionKey`	string example: three_colours If present, the question key associated with the form question
`answer*`	string example: red, green, blue The answer to the form question, represented as a string
}]

ExportRequest

ExportRequest {
`type*`	string example: responses-xlsx The type of export. Currently `responses-json` and `responses-xlsx` are supported.
`projectKey*`	string example: ABC A string containing the project key to export data from. Only one project can be specified; multiple projects require multiple exports.
`templateFormId*`	number example: 1 The ID of the template form to export data from. To find the ID of a template form, open the form in the ProForma form builder. The URL of that page will end in `ac.form.id`, that number is the template form ID to provide here.
fields	[string] example: List [ "summary", "priority", "customfield_10012" ]
jql	string example: (description ~ broken OR description ~ 'not working') AND created >= 2020-08-20 An optional string containing a JQL query. The export will be limited to include only issues that match this JQL query. NB: Including the project in the JQL (e.g. project = MyServiceDesk) is not required since ProForma will automatically include it.
}

ExportStartResponse

ExportStartResponse {
`type*`	string example: responses-xlsx A string identifying the export type.
`id*`	string example: responses-xlsx-ABC-1-1234567890 A string identifying the export task. Each export is given this unique ID to allow it to be retrieved later.
`statusURL*`	string example: https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890 The URL of the check status API which you can call to check the progress of this export.
}

ExportStatusResponse

ExportStatusResponse {
`type*`	string example: responses-xlsx A string identifying the type of export. The only possible values in this version of the API are: - `responses-json`. - `responses-xlsx`
`id*`	string example: responses-xlsx-ABC-1-1234567890 A string identifying the export task. Each export is given this unique ID to allow it to be retrieved later.
`complete*`	boolean example: true Indicates whether the export has completed successfully. This will initially be `false` for all but the smallest projects, once it turns `true` the export has finished and the file can be downloaded.
`failed*`	boolean example: false Indicates whether the export has failed. If this is `true` then something unexpected has gone wrong in the processing of this export. Please contact us for assistance in resolving this problem.
`progress*`	number example: 25 The estimated percentage complete of this export, expressed as an integer from 0 to 100.
downloadURL	string example: https://jira.example.com/jira/rest/proforma/1/export/responses-xlsx-ABC-1-1234567890/ProForma-ABC-form-1.xlsx The URL where this export can be downloaded. This `downloadUrl` will not be provided until the export has successfully completed, so once it appears in the response it is safe to call the URL and download the export file.
message	string example: Error constructing JQL query A text-based message providing more information about the status (whether completed or failed) of the export.
}

CustomerApiError

CustomerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred
`message`	string A more user-friendly description of the error in English, if available.
}

ClientApiError

ClientApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ client ]
`message`	string A more user-friendly description of the error in English, if available.
}

ForbiddenApiError

ForbiddenApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ forbidden ]
`message`	string A more user-friendly description of the error in English, if available.
}

NotFoundApiError

NotFoundApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ not found ]
`message`	string A more user-friendly description of the error in English, if available.
}

ServerApiError

ServerApiError {
A general error type. More specific errors extend this type with additional information.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ server ]
`message`	string A more user-friendly description of the error in English, if available.
}

InvalidJsonApiError

InvalidJsonApiError {
Error response specific to request JSON parsing errors. It may include further details on the cause of the parsing error.
`error*`	string The type of error that occurred Enum: Array [ 1 ] [ json ]
`message`	string A more user-friendly description of the error in English, if available.
}

FormStatus

FormStatus string

The status of a form, which can be

o - for forms which are open
s - for forms which have been submitted
l - for forms which have been locked

Enum:

Array [ 3 ]

[ o, s, l ]

CopyFormRequest

CopyFormRequest {
status	FormStatusCustomer string The status of a form, which can be open - for forms which are open submitted - for forms which have been submitted locked - for forms which have been locked Enum: Array [ 3 ] [ open, submitted, locked ]
`visibility`	FormVisibility string The visibility of the form, which is only applicable for Service Desk projects. internal - for forms which are set to Internal and only accessible via the Agent view external - for forms which are set to External and accessible via the Portal Enum: Array [ 2 ] [ internal, external ]
}

FormStatusCustomer

FormStatusCustomer string

The status of a form, which can be

open - for forms which are open
submitted - for forms which have been submitted
locked - for forms which have been locked

Enum:

Array [ 3 ]

[ open, submitted, locked ]

FormVisibility

FormVisibility string

The visibility of the form, which is only applicable for Service Desk projects.

internal - for forms which are set to Internal and only accessible via the Agent view
external - for forms which are set to External and accessible via the Portal

Enum:

Array [ 3 ]

[ internal, external ]

FormStateChangeResult

FormStateChangeResult {
The status and visibility of an issue form, as well as a flag indicating if the issue was transitioned to a new status (due to ProForma automation rules) as a result of the change.
`status`	FormStatus string The status of a form, which can be o - for forms which are open s - for forms which have been submitted l - for forms which have been locked Enum: Click here to expand... [ o, s, l ]
transitioned	boolean
}

VisibilityChangeResult

VisibilityChangeResult {
The visibility of the issue form.
`visibility`	FormVisibility string The visibility of the form, which is only applicable for Service Desk projects. internal - for forms which are set to Internal and only accessible via the Agent view external - for forms which are set to External and accessible via the Portal Enum: Array [ 1 ] [ internal, external ]
}

Page

Viewport

Confluence

v1.2.0 API documentation

ProForma developer documentation

On this page

Related content

Still need help?

Availability

ProForma Customer API V1.2.0 OAS3

Export API

Parameters

Request body

Example value

Schema

Example value

Schema

Example value

Schema

Example value

Schema

Example value

Schema

Extensions

Parameters

Responses

Example value

Schema

Example value

Schema

Example value

Schema

Example value

Schema

Example value

Schema

Extensions

Parameters

Responses

Example value

Schema

Example value

Schema

Example value

Schema

Example value

Schema

Example value

Schema

Extensions

Form API

Parameters

Request body

Example value

Schema

Example value

Schema

Example value

Schema

Example value

Schema

Extensions

Parameters

Responses

Example value

Schema

Example value

Schema

Example value

Schema

Example value

Schema

Extensions

Parameters

Request body

Example value

Schema

Responses

Example value

Schema