Form API
The Form API controller provides an API to query forms.
Endpoints
Get form
Get the form details by formId and processDefinitionKey required parameters.
URL
/v1/forms/{formId}?processDefinitionKey={processDefinitionKey}&version={formVersion}
Method
GET
Request parameters
| Parameter name | Type | Required | Description |
|---|---|---|---|
| formId | path | true | ID of the form |
| processDefinitionKey | query | true | Reference to the process definition |
| version | query | false | Version of the form, valid only for deployed forms |
In Camunda, there are two types of forms: embedded forms and deployed forms.
Embedded forms are stored in the process definition and are not versioned. The formId is a value generated by the internal Tasklist API and is distinct from the ID specified in the form editor. When retrieving a task, the key follows the format camunda-forms:bpmn:<formId>, and only the <formId> segment is required to access the form schema.
Deployed forms in Camunda are forms that are reusable between multiple processes, allowing for standardized and consistent form usage across various workflows. The formId is unique by the form and set by the developer on the process of the form design. The version is specifically used for deployed forms and increases after a new form deployment. When it is null, the system returns the latest active version of the form.
HTTP request example
Send a token issue GET request to the authorization server with the following content:
{
"form_id": "<form-id>",
"process_definition_key": "<process-definition-key>",
"version": "<version>",
}
Refer to the following example with curl:
curl -X 'GET' \
'http://{host}/v1/forms/{formId}?processDefinitionKey={processDefinitionKey}&version={formVersion}' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {yourBearerToken}'
See details on Tasklist API (REST) authentication if you have not already authenticated.
Responses
| HTTP status | Description | Response schema |
|---|---|---|
| 200 | On success | JSON object with FormResponse structure |
| 404 | An error is returned when the form with the formId, processDefinitionKey, and optionally specified version is not found. | JSON object with Error structure |