Build a shareable survey

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

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:

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.

{
  "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

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:

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:

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.

​1. Create the draft

​2. Add Questions

​3. Organize Blocks and Pages

​4. Upload and attach assets

​5. Add translations

​6. Validate and launch

​7. Generate invitation links