> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracecat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms

Read and edit [forms](/automations/triggers/forms) and manage their
submissions from a workflow.

## `core.forms.list_forms`

List the workspace's forms, newest first.

<Badge icon="lock" color="blue" size="lg" shape="pill">Enterprise Edition</Badge>

### Inputs

<ParamField path="cursor" type="string | null">
  `next_cursor` from a previous page.

  Default: `null`.
</ParamField>

<ParamField path="limit" type="integer">
  Maximum number of forms to return.

  Default: `20`.
</ParamField>

### Examples

**List forms**

```yaml theme={null}
- ref: list_forms
  action: core.forms.list_forms
  args:
    limit: 50
```

## `core.forms.get_form`

Get a form: its status, its config, the issues the config has against the workflow's inputs, and its URL.

<Badge icon="lock" color="blue" size="lg" shape="pill">Enterprise Edition</Badge>

### Inputs

<ParamField path="form_id" type="string" required>
  The form ID, as returned by `list_forms`.
</ParamField>

### Examples

**Get a form**

```yaml theme={null}
- ref: get_form
  action: core.forms.get_form
  args:
    form_id: 0b9f6c1e-5a47-4d1b-9c3e-2f7a8d6e4b10
```

## `core.forms.update_form`

Update the form of a workflow, creating it if the workflow has none. A form turns the workflow's input schema into a page people fill in; submitting it runs the workflow. Returns the form, including any `issues` with the config.

<Badge icon="lock" color="blue" size="lg" shape="pill">Enterprise Edition</Badge>

### Inputs

<ParamField path="workflow_id" type="string" required>
  The workflow the form belongs to (short `wf_...` or full ID).
</ParamField>

<ParamField path="config" type="object | null">
  The whole form config; it replaces the stored one. Keys, all optional: `title`, `description` (markdown), `success_message`, and `layout`, an ordered list of entries. An entry is one of `&#123;field: &lt;input name>&#125;`, `&#123;heading: &lt;text>&#125;`, `&#123;text: &lt;markdown>&#125;`, `&#123;notice: &lt;text>, tone: info|success|warning|danger&#125;` or `&#123;divider: true&#125;`. A field entry may add `label`, `help`, `placeholder`, `widget` (text, long\_text, number, toggle, select, multi\_select, cards, tags, date, datetime, user, file), `options` (`[&#123;value, label, description&#125;]`), `visible_if` (`&#123;field, equals&#125;`), `autofill` (requester, requester.user\_id, requester.email, requester.first\_name, requester.last\_name, submission.id) or `hidden`. A `file` field may add `accept` (extensions or MIME types, e.g. `[".pdf", "image/*"]`) and `max_files` (1 to 10; more than 1 needs a `list[dict]` input). Workflow inputs left out of `layout` are appended in schema order. Omit `config` to leave it unchanged.

  Default: `null`.
</ParamField>

<ParamField path="status" type="string | null">
  `online` lets people submit the form (the workflow must be published); `offline` stops submissions. Omit to leave unchanged.

  Default: `null`.
</ParamField>

### Examples

**Put a form online with a card picker**

```yaml theme={null}
- ref: update_form
  action: core.forms.update_form
  args:
    workflow_id: wf_3mYp8JkL2nQr7sTu9vWx0Z
    status: online
    config:
      title: Laptop request
      layout:
        - field: model
          widget: cards
```

## `core.forms.list_submissions`

List a form's submissions with their answers, newest first.

<Badge icon="lock" color="blue" size="lg" shape="pill">Enterprise Edition</Badge>

### Inputs

<ParamField path="form_id" type="string" required>
  The form ID.
</ParamField>

<ParamField path="cursor" type="string | null">
  `next_cursor` from a previous page.

  Default: `null`.
</ParamField>

<ParamField path="limit" type="integer">
  Maximum number of submissions to return.

  Default: `20`.
</ParamField>

<ParamField path="submitted_after" type="string | null">
  Only submissions at or after this time.

  Default: `null`.
</ParamField>

<ParamField path="submitted_before" type="string | null">
  Only submissions before this time.

  Default: `null`.
</ParamField>

### Examples

**List submissions older than 90 days**

```yaml theme={null}
- ref: list_expired
  action: core.forms.list_submissions
  args:
    form_id: 0b9f6c1e-5a47-4d1b-9c3e-2f7a8d6e4b10
    submitted_before: ${{ FN.now() - FN.days(90) }}
    limit: 200
```

## `core.forms.get_submission`

Get one form submission with its answers and who submitted it.

<Badge icon="lock" color="blue" size="lg" shape="pill">Enterprise Edition</Badge>

### Inputs

<ParamField path="submission_id" type="string" required>
  The submission ID. A form-triggered workflow gets its own from an input with `autofill: submission.id`.
</ParamField>

### Examples

**Get the submission that started this run**

```yaml theme={null}
- ref: get_submission
  action: core.forms.get_submission
  args:
    submission_id: ${{ TRIGGER.submission_id }}
```

## `core.forms.delete_submission`

Delete a form submission and its stored answers. The workflow run it started keeps its own copy of the inputs. Files uploaded with the submission are deleted too.

<Badge icon="lock" color="blue" size="lg" shape="pill">Enterprise Edition</Badge>

### Inputs

<ParamField path="submission_id" type="string" required>
  The submission ID.
</ParamField>

### Examples

**Delete each listed submission**

```yaml theme={null}
- ref: delete_expired
  action: core.forms.delete_submission
  depends_on:
    - list_expired
  for_each: ${{ for var.submission in ACTIONS.list_expired.result.items }}
  args:
    submission_id: ${{ var.submission.id }}
```

## `core.forms.download_file`

Download a file uploaded with a form submission. File integrity is verified via SHA256.

<Badge icon="lock" color="blue" size="lg" shape="pill">Enterprise Edition</Badge>

### Inputs

<ParamField path="file_id" type="string" required>
  The file ID: the `id` of the file object a `file` field puts in the workflow's inputs.
</ParamField>

### Examples

**Download a file attached to the submission**

```yaml theme={null}
- ref: download_quote
  action: core.forms.download_file
  args:
    file_id: ${{ TRIGGER.quote.id }}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.