Surveys

Overview

Surveys are tenant-owned data-collection definitions. Eligible tenant users discover active surveys that are visible to authenticated users, load a complete runtime definition, and create one or more responses. A field task may reference a survey, but tasks are not the only discovery or submission path.

Accessing Your Surveys

Authenticated surveys are accessible in two API-driven ways:

1. From a task — use its optional surveyId only when canStartSurvey is true.
2. From discovery — call GET /api/mobile/surveys; this list is not limited to field-task assignments.

The survey list displays:

• Survey title and description
• Access mode, allowed channel, consent settings, and response-editing flag
• myResponsesCount and lastRespondedAtUtc for the current user
• canStartNewResponse and newResponseUnavailableReason

Survey Availability

Opening a Survey

1. Tap a survey in the list (or navigate from the task detail screen).
2. Call GET /api/mobile/surveys/{surveyId} to load sections, groups, questions, choices, conditions, repeat metadata, dynamic tables, static content, lookup options, and HiddenAnswerPolicy.
3. The open policy checks tenant, audience/assignment rules, allowed channel, active state, and capacity. A list item does not bypass that policy.

Survey Structure

A survey may be organized into one or more sections (pages). Each section groups related questions together. The progress bar at the top of the screen shows how far through the survey you are.

Question types you may encounter:

• Single choice — select one answer from a list of options.
• Multiple choice — select all answers that apply.
• Text entry — type a free-form written response.
• Rating scale — choose a value on a numbered or labeled scale.
• Yes / No — tap Yes or No.
• Date / Time picker — select a date or time from a calendar widget.

Required questions are marked with an asterisk (*). You cannot move to the next section until all required questions in the current section are answered.

Saving Progress

The server does not auto-save navigation state. Persist a draft only by sending an explicit request with the intended response status, or keep it locally in a client that implements secure offline storage. Use a stable clientSubmissionId for create retries.

Submitting a Survey

1. Answer all questions in every section.
2. On the final section, tap Submit.
3. A summary screen may display your answers for review before final submission.
4. Confirm the submission.

After submission, use the owned-response endpoints. A completed response may be editable when the server returns canEdit=true; edit with PATCH /api/mobile/submissions/{instanceId} and an expected revision.

Viewing Submitted Surveys

The survey list remains a survey-definition list and exposes per-user counts, not one Submitted state. List owned responses with GET /api/mobile/submissions?page=1&pageSize=25&surveyId={surveyId}; page size is capped at 100.

Notes

• Discovery returns active tenant surveys visible to authenticated users; the open policy may additionally enforce audience assignment and channel rules.
• If an expected survey is absent, check tenant, active/visibility settings, access mode, assignment where required, mobile channel, permission, and subscription/response capacity.
• Survey availability and acceptance controls are server-authoritative even when the runtime exposes informational flags.

Subscription requirement

Downloading a survey runtime requires an active organization subscription. While it is expired the request is refused with errorCode 1001 / code "SubscriptionExpired"; the survey list and your own past submissions stay readable. The definition export route GET /api/Surveys/{surveyId}/ExportFile is gated the same way.

After renewal the same token downloads the runtime again immediately, including conditional revalidation.

See Mobile Subscription Contract.