> ## 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 an in-product survey

> Create a Web or Mobile survey, configure targeting, validate it, and launch it.

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.

```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": "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.

```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": "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.

1. Instrument the Event in the appropriate SDK.
2. For a new code Event, approve it in **Events > Manage Requests**.
3. 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.

```bash theme={null}
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](https://docs.sprig.com/reference/study-api-v2/targeting.md) for supported conditions and limits.

## 5. Validate the complete Study

```bash theme={null}
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:

```bash theme={null}
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:

1. Update only `status` to `PAUSED`.
2. Read and save the returned ETag.
3. Change Questions, settings, or targeting.
4. Validate again.
5. Update only `status` to `IN_PROGRESS`.

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