> This page is for API Reference & Tools.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# Rich Text Forms

> Create, read and update Rich Text Forms through the Moveworks Configuration API: endpoints, fields and examples.

`tool.ticket.rich-text-forms`

Rich ticket-filing forms (MWForm). `form_id` must be unique and not "1"/"2"/"3" (reserved built-in DL forms).

* **Endpoint:** `/tool/ticket/rich-text-forms`  |  **Methods:** GET, PATCH, POST
* **Request shape:** fields go at the top level of the JSON body, with no `resource` wrapper. The item's `id` goes in the URL for reads and updates, not in the body.
* **Updates:** a JSON merge-patch. Send only the fields you change, plus `version: {num, change_description}` with the `num` from your last read. Lists and maps you send replace the stored ones whole.

### Endpoints

All paths are relative to `https://api.moveworks.ai/configurations/v1alpha1`. Each endpoint page lists the request and response schema, an example, and the errors it can return.

| Method  | Path                                | Endpoint reference                                                                                        |
| ------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `GET`   | `/tool/ticket/rich-text-forms`      | [List rich text forms](/api-reference/configuration-api/ticketing/rich-text-forms/list-rich-text-forms)   |
| `POST`  | `/tool/ticket/rich-text-forms`      | [Create rich text form](/api-reference/configuration-api/ticketing/rich-text-forms/create-rich-text-form) |
| `GET`   | `/tool/ticket/rich-text-forms/{id}` | [Get rich text form](/api-reference/configuration-api/ticketing/rich-text-forms/get-rich-text-form)       |
| `PATCH` | `/tool/ticket/rich-text-forms/{id}` | [Update rich text form](/api-reference/configuration-api/ticketing/rich-text-forms/update-rich-text-form) |

### Fields

| Field               | Type                                 | Required  | Notes                                                                                                                                                                                                                                                  |
| ------------------- | ------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                | string                               | read-only | Unique identifier of this configuration, assigned by the server. Send it in update requests to identify the configuration.                                                                                                                             |
| `domain`            | enum                                 | ✅         | The business domain the form belongs to, such as IT_DOMAIN, HR_DOMAIN or FINANCE_DOMAIN. One of: `IT_DOMAIN`, `HR_DOMAIN`, `FACILITY_DOMAIN`, `FINANCE_DOMAIN`, `LEGAL_DOMAIN`, `OTHER_DOMAIN`, `PAYROLL_DOMAIN`, `PROCUREMENT_DOMAIN`, … (12 values). |
| `form_id`           | string                               | ✅         | Your unique identifier for the form. Must not duplicate another form's ID and cannot be changed after creation.                                                                                                                                        |
| `title`             | string                               | ✅         | The title of the form shown to users.                                                                                                                                                                                                                  |
| `short_description` | string                               | ✅         | A short description of the form.                                                                                                                                                                                                                       |
| `description`       | string                               |           | An optional longer description of the form. Up to 1000 characters.                                                                                                                                                                                     |
| `fields`            | array\<TicketFormFieldSettings>      |           | The input fields shown on the form.                                                                                                                                                                                                                    |
| `update_rules`      | array\<TicketFormUpdateRuleSettings> |           | Rules that dynamically change field behavior on the form. Rules run in the order defined, so a later rule overrides an earlier one for the same field.                                                                                                 |
| `updated_time`      | string                               | read-only | When the configuration was last updated.                                                                                                                                                                                                               |
| `updated_by`        | string                               | read-only | Who last updated the configuration.                                                                                                                                                                                                                    |
| `version`           | Version                              | ✅         | Document version. On update, send back the num from your last read.                                                                                                                                                                                    |

### Example create body

```json
{
  "domain": "IT_DOMAIN",
  "form_id": "<id>",
  "title": "Example title",
  "short_description": "What this is for",
  "description": "What this is for",
  "fields": [
    {
      "label": "<string>",
      "field_name": "example-name",
      "type": "TEXT",
      "description": "What this is for",
      "required": true,
      "read_only": true,
      "auto_population_setting": "IGNORE",
      "field_options": [
        {
          "label": "<string>",
          "value": "<string>",
          "mark_as_default": true
        }
      ],
      "default_value": {
        "label": "<string>",
        "value": "<string>"
      }
    }
  ],
  "update_rules": [
    {
      "field_update_condition": {
        "condition_expression": "<string>",
        "condition_expression_policy_field_ids": [
          "field_example"
        ]
      },
      "field_updates_when_true": [
        {
          "policy_field_id": "example_name",
          "field_actions": [
            {
              "property_required_enabled": true
            }
          ]
        }
      ],
      "field_updates_when_false": [
        {
          "policy_field_id": "example_name",
          "field_actions": [
            {
              "property_required_enabled": true
            }
          ]
        }
      ],
      "rule_description": "What this is for"
    }
  ],
  "version": {
    "change_description": "Create rich text form"
  }
}
```