
## Request

### Mutation

```graphql
mutation SubmitFormResponse($input: SubmitFormResponseInput!) {
  submitFormResponse(input: $input) {
    activity {
      id
      status
    }
  }
}
```

### Variables

```json
{
  "input": {
    "activity_id": "{{FORM_ACTIVITY_ID}}",
    "response": [
      {
        "question_id": "{{HEIGHT_QUESTION_ID}}",
        "value": "183" // String format
      },
      {
        "question_id": "{{WEIGHT_QUESTION_ID}}",
        "value": "95" // String format
      }
    ]
  }
}
```

### Serialization

**Given form responses are polymorphic, the answer value for a question should always be sent as a string.** Values are validated and deserialized on the Awell side and we will throw an error if a value does not match the corresponding data point value type.

In the table below you can find an overview of all question types, their corresponding data point value type, and the value type you should be sending to the Awell API.

<div className="table-wrapper">
  <table>
    <thead>
      <tr>
        <th>Question type</th>
        <th>Data point value type</th>
        <th>Value type to send</th>
        <th>Examples</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Date</td>
        <td>date</td>
        <td>ISO8601 string</td>
        <td>"2023-01-01"</td>
      </tr>
      <tr>
        <td>Number</td>
        <td>number</td>
        <td>string</td>
        <td>"10"</td>
      </tr>
      <tr>
        <td>Short Text</td>
        <td>string</td>
        <td>string</td>
        <td>"Awell is great"</td>
      </tr>
      <tr>
        <td>Long Text</td>
        <td>string</td>
        <td>string</td>
        <td>"A long story about why Awell is so great"</td>
      </tr>
      <tr>
        <td>Multiple Choice</td>
        <td>number</td>
        <td>
          string
          <br /> (value of selected option)
        </td>
        <td>"1"</td>
      </tr>
      <tr>
        <td>Multiple Select</td>
        <td>numbers_array</td>
        <td>
          string
          <br /> (array of values of the selected options)
        </td>
        <td>
          "[1, 2, 4]"
          <br />
          "['1', '2', '4']"
        </td>
      </tr>
      <tr>
        <td>Slider</td>
        <td>number</td>
        <td>string</td>
        <td>"50"</td>
      </tr>
      <tr>
        <td>Yes/No</td>
        <td>boolean</td>
        <td>
          string
          <br /> (we accept different values for booleans)
        </td>
        <td>
          "true" | "false"
          <br /> "t" | "f"
          <br /> "yes" | "no"
          <br /> "y" | "n"
          <br /> "1" | "0"
        </td>
      </tr>
    </tbody>
  </table>
</div>

### Specifying the user

The optional `X-User-ID` header can be used to specify which user is submitting the form response. When this header is present, Awell Orchestration will log a subactivity indicating that this specific user filled in the form.

```json
{
  "X-User-ID": "{{USER_ID}}"
}
```

The following input fields are available:

<div className="table-wrapper">
  <table>
    <thead>
      <tr>
        <th>Field</th>
        <th>Required</th>
        <th>Description</th>
        <th>Type</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>activity_id</td>
        <td>Yes</td>
        <td>the id of the form activity</td>
        <td>string</td>
      </tr>
      <tr>
        <td>response</td>
        <td>Yes</td>
        <td>the responses to questions in the form</td>
        <td>array of response objects</td>
      </tr>
      <tr>
        <td>response.question_id</td>
        <td>Yes, for each response object</td>
        <td>the id of the question for this response</td>
        <td>string</td>
      </tr>
      <tr>
        <td>response.value</td>
        <td>Yes, for each response object</td>
        <td>
          the value of the response, corresponding to the question's data point
          value type
        </td>
        <td>string</td>
      </tr>
    </tbody>
  </table>
</div>

## Errors

### Missing Value for Required Question

When submitting a form response, if one or more required questions are left unanswered, the backend will return a GraphQL error. The error response will appear as follows:

```json
{
    "errors": [
        {
            "message": "One or more required questions are unanswered.",
            "name": "GraphQLError",
            "originalError": {...},
            "extensions": {
                "errorId": "V8FiQfu8agvU7hjtakX7o",
                "data": {
                    "data": [
                        {
                            "_key": "6NGOn6QxLqra",
                            "_id": "QuestionComponent/6NGOn6QxLqra",
                            "definition_id": "jYQeP4fgq1_9",
                            "title": "Q1"
                        },
                        {
                            "_key": "-Nfe4khOpu4T",
                            "_id": "QuestionComponent/-Nfe4khOpu4T",
                            "definition_id": "VwQm8oP_u90s",
                            "title": "Q4"
                        }
                    ],
                    "customMessage": "One or more required questions are unanswered."
                },
                "type": "MISSING_REQUIRED_ANSWER",
                "statusCode": 400,
                "code": "INTERNAL_SERVER_ERROR"
            },
            ...
        }
    ],
    "data": null
}
```

The `extensions` field in the error object will provide details about the missing values. The unanswered questions are listed under `extensions.data.data`.

## How to use

<HowToUse storyIds={['conversational-form', 'form']} />


Question type	Data point value type	Value type to send	Examples
Date	date	ISO8601 string	"2023-01-01"
Number	number	string	"10"
Short Text	string	string	"Awell is great"
Long Text	string	string	"A long story about why Awell is so great"
Multiple Choice	number	string (value of selected option)	"1"
Multiple Select	numbers_array	string (array of values of the selected options)	"[1, 2, 4]" "['1', '2', '4']"
Slider	number	string	"50"
Yes/No	boolean	string (we accept different values for booleans)	"true" \| "false" "t" \| "f" "yes" \| "no" "y" \| "n" "1" \| "0"

Field	Required	Description	Type
activity_id	Yes	the id of the form activity	string
response	Yes	the responses to questions in the form	array of response objects
response.question_id	Yes, for each response object	the id of the question for this response	string
response.value	Yes, for each response object	the value of the response, corresponding to the question's data point value type	string