> 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.

# Submit modal

POST https://api.moveworks.ai/rest/v1/conversations/{conversation_id}/responses/{response_id}/messages/{message_id}/modals/{modal_id}/submit
Content-Type: application/json

Submits the filled values of a modal.

Rule evaluation is authoritative on the server: fields that resolve to hidden are neither required nor persisted, and `DISPLAY` blocks are never submitted.

The response is an acknowledgement receipt, not the outcome of the downstream action. The follow-up assistant response arrives on the conversation through the usual response channels.

Reference: https://docs.moveworks.com/api-reference/conversations-api/conversations-api/modals/submit-modal

## Authentication

- `Authorization` header (bearer token, required) — JWT bearer token authentication. Obtain an access token from the Moveworks auth endpoint and include it in the Authorization header as 'Bearer \<token>'.

## Request

### Path parameters

- `conversation_id` (string, required) — A base-62 identifier prefixed by a short resource type
- `response_id` (string, required) — A base-62 identifier prefixed by a short resource type
- `message_id` (string, required) — A base-62 identifier prefixed by a short resource type
- `modal_id` (string, required) — Opaque modal identifier, taken from the `modal_action.modal_id` of the action that surfaced this modal. Pass it back exactly as received.

### Headers

- `Assistant-Name` (string, required) — The Moveworks assistant identifier that was configured for your organization.

### Body (application/json)

This endpoint expects a SubmitModalRequest.

- `values` (map from string to ModalFieldValue, required) — Values to submit, keyed by the field's `name`.

## Response

### 200

Modal submitted successfully

- `status` (enum, required) — Modal submission status.
  - Allowed values: `SUBMITTED`
- `receipt_text` (string, optional) — Acknowledgement that the values were accepted. This is a receipt, not the outcome of the downstream action.

## Errors

### 400 Bad Request Error

Invalid request - a required field is missing, a submitted value does not match its field type, or a file id has expired

- `error` (InvalidModalRequestErrorResponseError, required)

### 401 Unauthorized Error

Unauthorized - Invalid or missing authentication

- `error` (UnauthorizedErrorResponseError, required)

### 403 Forbidden Error

Forbidden - Invalid assistant

- `error` (ForbiddenErrorResponseError, required)

### 404 Not Found Error

Not found - conversation, response, message, or modal does not exist

- `error` (NotFoundErrorResponseError, required)

### 429 Too Many Requests Error

Rate limit exceeded

- `error` (RateLimitExceededErrorResponseError, required)

### 500 Internal Server Error

Internal server error

- `error` (InternalErrorResponseError, required)

## Types

### ModalFieldValue

A submitted value for a single modal field. Exactly one member is present, and it must match the field's `type`: `TEXT` uses `text`, `DATE` uses `date`, `DATETIME` uses `datetime`, `BOOLEAN` uses `bool`, `CHOICE` uses `option` when `multi` is `false` and `options` when it is `true`, and `FILE` uses `files`. A value whose member does not match the field type is rejected.

- `text` (string, optional) — `TEXT` value, in whatever language the user typed.
- `date` (date, optional) — `DATE` value as `YYYY-MM-DD`.
- `datetime` (datetime, optional) — `DATETIME` value as an RFC 3339 timestamp, in UTC or with an explicit offset.
- `bool` (boolean, optional) — `BOOLEAN` value. Submitted explicitly rather than omitted, since an untouched toggle is `false` rather than unanswered.
- `option` (string, optional) — Single-select `CHOICE` value, holding the option's `value`.
- `options` (list of string, optional) — Multi-select `CHOICE` values, each holding an option's `value`.
- `files` (list of ModalFileValue, optional) — `FILE` values. At most `max_files` entries.

### InvalidModalRequestErrorResponseError

- `code` (enum, required)
  - Allowed values: `INVALID_REQUEST`
- `message` (string, required)

### UnauthorizedErrorResponseError

- `code` (enum, required)
  - Allowed values: `UNAUTHORIZED`
- `message` (string, required)

### ForbiddenErrorResponseError

- `code` (enum, required)
  - Allowed values: `FORBIDDEN`
- `message` (string, required)

### NotFoundErrorResponseError

- `code` (enum, required)
  - Allowed values: `NOT_FOUND`
- `message` (string, required)

### RateLimitExceededErrorResponseError

- `code` (enum, required)
  - Allowed values: `RATE_LIMIT_EXCEEDED`
- `message` (string, required)

### InternalErrorResponseError

- `code` (enum, required)
  - Allowed values: `INTERNAL_ERROR`
- `message` (string, required)

### ModalFileValue

Reference to a file uploaded ahead of submission.

- `file_id` (string, required) — Id of a file uploaded ahead of submission. The bytes themselves never travel through the modal endpoints, and the file name and content type are resolved from the upload rather than submitted, so what gets attached is what was actually uploaded. Uploads expire roughly 24 hours after they are created, and an expired id fails submission validation.

## Examples

**Request**

```json
{
  "values": {
    "business_impact": {
      "text": "Cannot reach internal tools from home."
    },
    "priority": {
      "option": "high"
    },
    "screenshots": {
      "files": [
        {
          "file_id": "file_32bt9KpQ4xRsNvY7wLc2f"
        }
      ]
    },
    "short_description": {
      "text": "Laptop will not connect to the VPN"
    }
  }
}
```

**Response**

```json
{
  "status": "SUBMITTED",
  "receipt_text": "Your request has been submitted."
}
```

**SDK Code**

```python Modals_submitModal_example
import requests

url = "https://api.moveworks.ai/rest/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/resp_32bt7rXXugeJjvE3pQzOk/messages/msg_32bt8vagXAoRwRLIdI2Oj/modals/modal_32bt9QpLmRvXnTkWzc4Ha/submit"

payload = { "values": {
        "business_impact": { "text": "Cannot reach internal tools from home." },
        "priority": { "option": "high" },
        "screenshots": { "files": [{ "file_id": "file_32bt9KpQ4xRsNvY7wLc2f" }] },
        "short_description": { "text": "Laptop will not connect to the VPN" }
    } }
headers = {
    "Assistant-Name": "acmecorp-conversations-rest-api",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Modals_submitModal_example
const url = 'https://api.moveworks.ai/rest/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/resp_32bt7rXXugeJjvE3pQzOk/messages/msg_32bt8vagXAoRwRLIdI2Oj/modals/modal_32bt9QpLmRvXnTkWzc4Ha/submit';
const options = {
  method: 'POST',
  headers: {
    'Assistant-Name': 'acmecorp-conversations-rest-api',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"values":{"business_impact":{"text":"Cannot reach internal tools from home."},"priority":{"option":"high"},"screenshots":{"files":[{"file_id":"file_32bt9KpQ4xRsNvY7wLc2f"}]},"short_description":{"text":"Laptop will not connect to the VPN"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Modals_submitModal_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moveworks.ai/rest/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/resp_32bt7rXXugeJjvE3pQzOk/messages/msg_32bt8vagXAoRwRLIdI2Oj/modals/modal_32bt9QpLmRvXnTkWzc4Ha/submit"

	payload := strings.NewReader("{\n  \"values\": {\n    \"business_impact\": {\n      \"text\": \"Cannot reach internal tools from home.\"\n    },\n    \"priority\": {\n      \"option\": \"high\"\n    },\n    \"screenshots\": {\n      \"files\": [\n        {\n          \"file_id\": \"file_32bt9KpQ4xRsNvY7wLc2f\"\n        }\n      ]\n    },\n    \"short_description\": {\n      \"text\": \"Laptop will not connect to the VPN\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Assistant-Name", "acmecorp-conversations-rest-api")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Modals_submitModal_example
require 'uri'
require 'net/http'

url = URI("https://api.moveworks.ai/rest/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/resp_32bt7rXXugeJjvE3pQzOk/messages/msg_32bt8vagXAoRwRLIdI2Oj/modals/modal_32bt9QpLmRvXnTkWzc4Ha/submit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Assistant-Name"] = 'acmecorp-conversations-rest-api'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"values\": {\n    \"business_impact\": {\n      \"text\": \"Cannot reach internal tools from home.\"\n    },\n    \"priority\": {\n      \"option\": \"high\"\n    },\n    \"screenshots\": {\n      \"files\": [\n        {\n          \"file_id\": \"file_32bt9KpQ4xRsNvY7wLc2f\"\n        }\n      ]\n    },\n    \"short_description\": {\n      \"text\": \"Laptop will not connect to the VPN\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Modals_submitModal_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.moveworks.ai/rest/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/resp_32bt7rXXugeJjvE3pQzOk/messages/msg_32bt8vagXAoRwRLIdI2Oj/modals/modal_32bt9QpLmRvXnTkWzc4Ha/submit")
  .header("Assistant-Name", "acmecorp-conversations-rest-api")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"values\": {\n    \"business_impact\": {\n      \"text\": \"Cannot reach internal tools from home.\"\n    },\n    \"priority\": {\n      \"option\": \"high\"\n    },\n    \"screenshots\": {\n      \"files\": [\n        {\n          \"file_id\": \"file_32bt9KpQ4xRsNvY7wLc2f\"\n        }\n      ]\n    },\n    \"short_description\": {\n      \"text\": \"Laptop will not connect to the VPN\"\n    }\n  }\n}")
  .asString();
```

```php Modals_submitModal_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.moveworks.ai/rest/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/resp_32bt7rXXugeJjvE3pQzOk/messages/msg_32bt8vagXAoRwRLIdI2Oj/modals/modal_32bt9QpLmRvXnTkWzc4Ha/submit', [
  'body' => '{
  "values": {
    "business_impact": {
      "text": "Cannot reach internal tools from home."
    },
    "priority": {
      "option": "high"
    },
    "screenshots": {
      "files": [
        {
          "file_id": "file_32bt9KpQ4xRsNvY7wLc2f"
        }
      ]
    },
    "short_description": {
      "text": "Laptop will not connect to the VPN"
    }
  }
}',
  'headers' => [
    'Assistant-Name' => 'acmecorp-conversations-rest-api',
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Modals_submitModal_example
using RestSharp;

var client = new RestClient("https://api.moveworks.ai/rest/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/resp_32bt7rXXugeJjvE3pQzOk/messages/msg_32bt8vagXAoRwRLIdI2Oj/modals/modal_32bt9QpLmRvXnTkWzc4Ha/submit");
var request = new RestRequest(Method.POST);
request.AddHeader("Assistant-Name", "acmecorp-conversations-rest-api");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"values\": {\n    \"business_impact\": {\n      \"text\": \"Cannot reach internal tools from home.\"\n    },\n    \"priority\": {\n      \"option\": \"high\"\n    },\n    \"screenshots\": {\n      \"files\": [\n        {\n          \"file_id\": \"file_32bt9KpQ4xRsNvY7wLc2f\"\n        }\n      ]\n    },\n    \"short_description\": {\n      \"text\": \"Laptop will not connect to the VPN\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Modals_submitModal_example
import Foundation

let headers = [
  "Assistant-Name": "acmecorp-conversations-rest-api",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["values": [
    "business_impact": ["text": "Cannot reach internal tools from home."],
    "priority": ["option": "high"],
    "screenshots": ["files": [["file_id": "file_32bt9KpQ4xRsNvY7wLc2f"]]],
    "short_description": ["text": "Laptop will not connect to the VPN"]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.moveworks.ai/rest/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/resp_32bt7rXXugeJjvE3pQzOk/messages/msg_32bt8vagXAoRwRLIdI2Oj/modals/modal_32bt9QpLmRvXnTkWzc4Ha/submit")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```