> ## Documentation Index > Fetch the complete documentation index at: https://help.skillsdb.com/llms.txt > Use this file to discover all available pages before exploring further. # The Survey object > A survey run: its template version, population, lifecycle and participation counts **Quick Summary:** A survey is one *run* of a survey template against a population of people. A template with its questions can be created over the API (`POST /api/v1/survey-templates`) or in the app; the API creates runs from a template version, manages who receives them, drives the lifecycle, and reads the results. ## Attributes | Field | Type | Description | | ------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Opaque survey id | | `name` | string | Display name | | `description` | string \| null | Description | | `status` | enum | `draft`, `scheduled`, `launched`, `ended`, `cancelled` | | `templateVersion` | object \| null | The pinned template version: `{ id, name, version, templateId, templateName }`. A run is pinned to one version — later template edits never change a running survey | | `toAllPeople` | boolean | Whether the population is everyone in the company | | `scheduledFor` | string \| null | Future launch time, when scheduled | | `launchedAt` | string \| null | When it launched | | `dueDate` | string \| null | Responses due by | | `lastNudgeSentAt` | string \| null | When participants were last reminded | | `participants` | object | Counts by participation status: `{ notStarted, inProgress, completed }` | | `createdById` | string \| null | Person who created the run | | `createdAt` / `updatedAt` | string \| null | Timestamps (UTC) | ## Templates A run points at a template **version**, so a brand-new company needs a template before its first survey. | Operation | Method and path | Scope | | ------------------------------------ | ----------------------------------- | --------------- | | List templates | `GET /api/v1/survey-templates` | `surveys:read` | | Create a template with its questions | `POST /api/v1/survey-templates` | `surveys:write` | | Read a template and its questions | `GET /api/v1/survey-templates/{id}` | `surveys:read` | Create takes the template's `name`, an optional `description` and `visibility` (`visible_to_all` — the default — or `private`), and its `questions` in order. Each question is `{ name, text, type, responseRequired?, allowsMultipleResponses?, options? }`; `type` is one of `rating`, `text`, `multiple_choice`, `drop_down`. Choice questions need at least two `options` (`{ "label": "HQ" }`); rating and text questions take none. The response carries `latestVersion.id` — the value to send as `templateVersionId` when creating a survey — and the questions in the same shape `GET /surveys/{id}/questions` returns. The list shows each template's newest version with `questions: null`; the single read includes them. Editing a template (which cuts a new version) is done in the app. ## Lifecycle `draft → scheduled → launched → ended`, with `cancelled` reachable before ending. The transitions are explicit operations, and an out-of-order call answers a [409 conflict](/api-docs/errors/conflict) describing the required state: * `POST /api/v1/surveys/{id}/schedule` — set a future launch time on a draft; re-scheduling is allowed while the current time is still more than an hour away. * `POST /api/v1/surveys/{id}/launch` — launch now: the population is materialised into participants and notified. A survey nobody would receive is a 409. * `POST /api/v1/surveys/{id}/end` — close a launched survey to further responses. * `POST /api/v1/surveys/{id}/cancel` — cancel a run. * `POST /api/v1/surveys/{id}/nudge` — remind everyone who has not completed; answers **202**, the reminders send asynchronously. ## Population The population is defined while the survey is a draft (or still more than an hour from a scheduled launch), and materialised at launch: * `GET /api/v1/surveys/{id}/scope` — the definition: `toAllPeople`, the nine org-dimension id lists, `personIds` (named individuals), `excludedPersonIds`. State ids appear read-only. * `PUT /api/v1/surveys/{id}/scope` — replace the definition. Turning `toAllPeople` off and naming `people` scopes the run to exactly those individuals. * `POST /api/v1/surveys/{id}/exclusions` / `DELETE …/exclusions` — exclude named individuals from any population, or lift the exclusion. Refused once launched. People in write bodies are **emails**; every response carries the opaque `personId` and the email. ## Reading a run * `GET /api/v1/surveys` — paginated, filterable by `status` (public values above), name and dates. * `GET /api/v1/surveys/{id}` — one run. * `GET /api/v1/surveys/{id}/questions` — the pinned question set: `{ id, name, text, description, version, type, responseRequired, allowsMultipleResponses, options }` with `type` one of `multiple_choice`, `drop_down`, `rating`, `text`, `document_upload`, `certification_update`. * `GET /api/v1/surveys/{id}/people` — participants with `person {id, name, email}`, `status` (`assigned`, `in_progress`, `completed`, `archived`), how each was included (`all_people`, `org_schema`, `manual`), and timestamps. `GET …/people/{person}` reads one participation; the person slot takes an email or the opaque id. Responses live on the [Survey Response](/api-docs/resources/survey-response) page. ## Scopes Reads require `surveys:read`; every write requires `surveys:write`. Employee-bound credentials are read-only apart from submitting their own responses.