Questionnaire Submit

Overview

Submitting a questionnaire creates a tenant response through POST /api/mobile/surveys/{surveyId}/submissions. A response may optionally reference a field task, but a task is not required for direct authenticated survey submission.

Before You Submit

Make sure you have:

• Loaded an active survey through GET /api/mobile/surveys/{surveyId} and verified that the runtime permits a new authenticated response.
• Supplied a stable, client-generated clientSubmissionId so retries are idempotent.
• Read any instructions displayed at the beginning of the questionnaire.

Filling In the Questionnaire

Work through each question one at a time:

1. Read each question carefully before selecting or typing your answer.
2. Required questions are marked with an asterisk (*). You must answer all required questions in a section before advancing.
3. Optional questions may be skipped, but answer them if you have relevant information.
4. Use the Next button to move to the next section after completing all questions on the current page.
5. Use the Back button to review or correct answers on a previous section.

Answer Types

Drafts and Offline Work

The backend does not auto-save merely because the user changes sections or backgrounds the app. A client that offers drafts or offline work must implement that behavior explicitly:

• Keep unsent work in client storage when offline.
• Submit a request with the intended status when server persistence is required.
• Reuse the same clientSubmissionId when retrying an uncertain create request.

Do not promise automatic local persistence or synchronization unless the specific client implements and tests it.

Reviewing Your Answers Before Submission

On the final section of the questionnaire, the app may display a Summary screen showing all your answers grouped by section. Use this screen to:

• Verify that all required questions are answered.
• Spot any responses you want to revisit.
• Use Edit next to a section to go back and change an answer.

Submitting

When you are satisfied with your answers:

1. Tap the Submit button on the final section or summary screen.
2. Send the runtime-compatible QuestionnaireInstanceViewModel; the route value is authoritative for surveyId and public token ids are cleared.
3. Include GPS fields when the survey requires completed-location metadata, and upload File answers first so final JSON contains opaque UploadId values.

After successful submission:

• A Submission Successful message is displayed.
• The persisted questionnaire uses the submitted QuestionnaireInstanceStatus, normally Completed for a final response.
• If fieldTaskId is supplied, task effects are determined by the server; task completion is also exposed separately at POST /api/mobile/tasks/{id}/complete.

After Submission

• You can view current file descriptors and download authorized files without seeing storage paths or internal metadata ids.
• An attributed authenticated response can be edited only when the survey remains active, response editing is enabled, the response is Completed, the current user is the original submitter, and the origin-specific acceptance control still permits editing. Anonymous public submissions remain immutable.
• Editing a File answer uploads replacements first and sends retained current AnswerFileId values plus new UploadId values. Successful replacement creates new association ids, so the client must reload current response details.
• The submitted data is securely stored and used for reporting and analysis by your organization.

Troubleshooting

• "Required questions not answered" error: Return to the section indicated and fill in the missing answers.
• Submission failed — network error: Retry with the same clientSubmissionId to receive the previously accepted instance instead of creating a duplicate.
• response_limit_reached: The tenant has no remaining response capacity; retrying unchanged will not bypass the limit.
• A completed response needs correction: Load the owned response and honor canEdit; use PATCH /api/mobile/submissions/{instanceId} only when permitted.

Subscription requirement

Submission requires an active organization subscription. While it is expired the request is refused with errorCode 1001 / code "SubscriptionExpired", and the server creates no response and no answers — and does not consume the clientSubmissionId.

A queued offline submission must therefore be kept, not discarded: keep the same clientSubmissionId, the original SurveyVersionId and answers, and retry the identical payload after renewal. It is then accepted exactly once, and a further retry returns the canonical already-accepted result.

The file-upload retry key clientUploadId is a different key for a different operation; do not substitute one for the other. See Mobile Offline Work and Operations.