> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sprig.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a shareable survey

> Create, author, validate, launch, and distribute a link survey through the Study API.

A shareable survey has `type: SURVEY` and is delivered through a respondent link. It supports Blocks
and Pages, uploaded assets, translations, and generated invitations.

## 1. Create the draft

```bash theme={null}
curl --request POST https://api.sprig.com/v2/studies \
  --header "Authorization: API-Key $SPRIG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "SURVEY",
    "name": "Quarterly product feedback",
    "responseSettings": {
      "completion": {
        "mode": "FIXED",
        "responseLimit": 500
      },
      "requireIdentifiedRespondent": true,
      "allowBackwardNavigation": true,
      "retake": {
        "invitationMode": "GENERATED",
        "responseLimit": "PER_INVITATION",
        "resume": {
          "enabled": true,
          "windowDays": 14
        }
      }
    }
  }'
```

Save the returned Study `id`, `version`, and ETag. `studyUrl` opens the Study in the Sprig dashboard
for authors. `shareUrl` is `null` while the Study is `DRAFT`; read the Study after launch to obtain
its respondent URL. Retake settings can change only before the Study launches.

## 2. Add Questions

Question titles use an object so they can support rich text and variables:

```bash theme={null}
curl --request POST "https://api.sprig.com/v2/studies/$STUDY_ID/questions" \
  --header "Authorization: API-Key $SPRIG_API_KEY" \
  --header 'If-Match: "126300"' \
  --header "Content-Type: application/json" \
  --data '{
    "type": "OPEN_TEXT",
    "name": "improvement",
    "title": {
      "html": "What should we improve?"
    },
    "required": true,
    "responsePlaceholder": "Share your feedback"
  }'
```

Use the returned ETag for the next authored write. Caller-defined `name` values make later logic and
positioning easier to maintain, but they must be unique within the Study.

The Question reference documents every supported Question kind, Option structure, display logic,
skip logic, response piping, carry-forward rule, and positioning rule. Do not reuse a request body
across Question kinds without validating it against that kind's schema.

## 3. Organize Blocks and Pages

Blocks group related Questions. Set `displayAsPage: true` to present all direct member Questions on
one page.

```json theme={null}
{
  "name": "product-usage",
  "label": "Product usage",
  "displayAsPage": true
}
```

Create a Block, save its UUID, then set a Question's `blockId` when creating the Question. You can
also position a Question or Block before or after an existing resource.

Block and Page rules own their group-level display and skip logic. A Page owns skip logic for its
member Questions, so Question-level skip logic is rejected for Page members.

## 4. Upload and attach assets

Shareable surveys support:

* `CONSENT_DOCUMENT`: one PDF up to 10 MB.
* `QUESTION_IMAGE`: GIF, JPEG, PNG, or WebP up to 10 MB.

Upload an asset first, then reference the returned `assetId` from a compatible Question. Asset
operations do not change the Study version and do not require `If-Match`.

Deleting an asset fails with `ASSET_IN_USE` while a Question still references it.

## 5. Add translations

Use translation resources for precise authored copy, or start a translation job for asynchronous
machine translation.

* `PUT` replaces the complete translation for one locale.
* `PATCH` changes only supplied fields.
* Translation resource writes require `If-Match`.
* Starting or checking a translation job does not require `If-Match`.

Wait for a job to reach a terminal status before assuming all output is available. Cancelling a job
does not roll back translation content already committed.

## 6. Validate and launch

```bash theme={null}
curl --request POST "https://api.sprig.com/v2/studies/$STUDY_ID/validate" \
  --header "Authorization: API-Key $SPRIG_API_KEY"
```

Resolve every item in `errors`. Then read the Study again and launch with its latest ETag:

```bash theme={null}
curl --request PATCH "https://api.sprig.com/v2/studies/$STUDY_ID" \
  --header "Authorization: API-Key $SPRIG_API_KEY" \
  --header 'If-Match: "126307"' \
  --header "Content-Type: application/json" \
  --data '{"status":"IN_PROGRESS"}'
```

Lifecycle updates must contain only `status`.

## 7. Generate invitation links

Generated invitations provide one respondent link per invitation and support idempotent batch
creation:

```bash theme={null}
curl --request POST "https://api.sprig.com/v2/studies/$STUDY_ID/invitations" \
  --header "Authorization: API-Key $SPRIG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "count": 500,
    "idempotencyKey": "quarterly-feedback-2026-q4"
  }'
```

Reuse the same `idempotencyKey` when retrying the same logical batch. Sprig returns the original
batch instead of creating duplicate invitations, even if a retry sends a different `count`.

Invitation operations are available only for `SURVEY` Studies.