Submit form response

Developer Hub

Request

Mutation

graphql
01mutation SubmitFormResponse($input: SubmitFormResponseInput!) {
02  submitFormResponse(input: $input) {
03    activity {
04      id
05      status
06    }
07  }
08}

Variables

json
01{
02  "input": {
03    "activity_id": "{{FORM_ACTIVITY_ID}}",
04    "response": [
05      {
06        "question_id": "{{HEIGHT_QUESTION_ID}}",
07        "value": "183" // String format
08      },
09      {
10        "question_id": "{{WEIGHT_QUESTION_ID}}",
11        "value": "95" // String format
12      }
13    ]
14  }
15}

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

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"

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
01{
02  "X-User-ID": "{{USER_ID}}"
03}

The following input fields are available:

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

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
01{
02    "errors": [
03        {
04            "message": "One or more required questions are unanswered.",
05            "name": "GraphQLError",
06            "originalError": {...},
07            "extensions": {
08                "errorId": "V8FiQfu8agvU7hjtakX7o",
09                "data": {
10                    "data": [
11                        {
12                            "_key": "6NGOn6QxLqra",
13                            "_id": "QuestionComponent/6NGOn6QxLqra",
14                            "definition_id": "jYQeP4fgq1_9",
15                            "title": "Q1"
16                        },
17                        {
18                            "_key": "-Nfe4khOpu4T",
19                            "_id": "QuestionComponent/-Nfe4khOpu4T",
20                            "definition_id": "VwQm8oP_u90s",
21                            "title": "Q4"
22                        }
23                    ],
24                    "customMessage": "One or more required questions are unanswered."
25                },
26                "type": "MISSING_REQUIRED_ANSWER",
27                "statusCode": 400,
28                "code": "INTERNAL_SERVER_ERROR"
29            },
30            ...
31        }
32    ],
33    "data": null
34}

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

Submit checklist response Resend EMR report