Build an in-product survey

An in-product survey has type: IN_PRODUCT_SURVEY and is presented by a Sprig SDK when a visitor matches its targeting configuration.

1. Create the draft

Choose WEB or MOBILE at creation time. The platform cannot change later.

curl --request POST https://api.sprig.com/v2/studies \
  --header "Authorization: API-Key $SPRIG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "IN_PRODUCT_SURVEY",
    "platform": "WEB",
    "name": "New dashboard feedback",
    "appearance": {
      "layout": "FIXED",
      "showBranding": true,
      "replayDurationSeconds": 120,
      "replayDurationType": "BEFORE"
    },
    "responseSettings": {
      "completion": {
        "mode": "ONGOING"
      },
      "sampling": {
        "mode": "PERCENTAGE",
        "percentage": 10
      },
      "recontact": {
        "retakeSurvey": false,
        "resurveyWindowSeconds": 2592000
      }
    }
  }'

Save the returned Study id, version, and ETag. studyUrl opens the Study in the Sprig dashboard for authors.

Completion and sampling

Completion can be:

FIXED with a total responseLimit.
UNTIL_DATE with an ISO 8601 closeAt.
ONGOING.

An ongoing Study can sample by a percentage of eligible users or a daily send cap. Omitting sampling on an ongoing Study uses 7 percent. Fixed in-product surveys also use Sprig’s non-configurable daily delivery cap.

Recontact

retakeSurvey controls whether the same respondent may respond again. resurveyWindowSeconds overrides the product-level recontact period; send null to use the product default.

2. Add supported Questions

Create Questions with the Study’s current ETag. The API validates Question kinds and settings against the in-product platform.

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": "RATING_SCALE",
    "name": "dashboard-ease",
    "title": {
      "html": "How easy was it to use the new dashboard?"
    },
    "required": true,
    "range": 5,
    "scaleLabelType": "NUMBER",
    "lowEndLabel": "Very difficult",
    "highEndLabel": "Very easy"
  }'

Use the Question schema as the source of truth for each request. Blocks can group and organize Questions, but Pages (displayAsPage: true), uploaded assets, and invitations are not supported for in-product surveys through the Study API.

3. Prepare trigger Events

Your SDK must send the code Event or observe the page URL Event that should trigger the Study.

Instrument the Event in the appropriate SDK.
For a new code Event, approve it in Events > Manage Requests.
Call GET /v2/events and save the Event’s public UUID.

The Study API lists existing Event definitions but does not create them.

4. Configure targeting

The first PUT creates the targeting sub-resource. Every later PUT replaces it completely.

curl --request PUT "https://api.sprig.com/v2/studies/$STUDY_ID/targeting" \
  --header "Authorization: API-Key $SPRIG_API_KEY" \
  --header 'If-Match: "126301"' \
  --header "Content-Type: application/json" \
  --data '{
    "triggers": [
      {"id": "11111111-1111-4111-8111-111111111111"}
    ],
    "audience": {
      "operator": "AND",
      "conditions": [
        {
          "type": "ATTRIBUTE",
          "attribute": "plan",
          "comparator": "EQUALS",
          "value": "enterprise"
        },
        {
          "type": "PAGE_VIEW_COUNT",
          "comparator": "GREATER_THAN_OR_EQUAL",
          "value": 3
        }
      ]
    },
    "delaySeconds": 5
  }'

PAGE_VIEW_COUNT and DEVICE_TYPE are Web-only conditions. For all platforms, multiple triggers use OR semantics and nested audience groups use their explicit AND or OR operator. See In-product targeting for supported conditions and limits.

5. Validate the complete Study

curl --request POST "https://api.sprig.com/v2/studies/$STUDY_ID/validate" \
  --header "Authorization: API-Key $SPRIG_API_KEY"

An in-product survey requires at least one supported Question and one Event trigger. Resolve every validation issue, including platform-specific appearance, replay, Question, and targeting issues.

6. Launch

Read the Study again to obtain its latest ETag, then send a lifecycle-only update:

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

If the Study changed after validation, launch can still return STUDY_NOT_READY. Resolve the returned issues, read the latest ETag, and retry.

7. Update a running program

Pause the Study before changing authored settings or content:

Update only status to PAUSED.
Read and save the returned ETag.
Change Questions, settings, or targeting.
Validate again.
Update only status to IN_PROGRESS.

Do not combine a lifecycle transition with settings in one PATCH.

​1. Create the draft

​Completion and sampling

​Recontact

​2. Add supported Questions

​3. Prepare trigger Events

​4. Configure targeting

​5. Validate the complete Study

​6. Launch

​7. Update a running program