In-product targeting

Targeting is a single sub-resource of an IN_PRODUCT_SURVEY Study. It contains the complete delivery decision:

triggers: existing Events that can trigger the Study.
audience: visitor conditions evaluated for eligibility.
delaySeconds: how long to wait after the trigger before presentation.

Targeting does not apply to a shareable SURVEY.

Create or replace targeting

PUT /v2/studies/{studyId}/targeting creates targeting when none exists and replaces the complete resource on later calls. There is no separate create operation and no partial update.

Read the Study and save its ETag.
List Events and select at least one Event UUID.
Optionally list Attribute definitions and compose an audience expression.
Send the entire targeting document with If-Match.
Save the new ETag returned by the 204 response.

curl --request PUT "https://api.sprig.com/v2/studies/$STUDY_ID/targeting" \
  --header "Authorization: API-Key $SPRIG_API_KEY" \
  --header 'If-Match: "126300"' \
  --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": "SESSION_COUNT",
          "comparator": "GREATER_THAN_OR_EQUAL",
          "value": 2
        }
      ]
    },
    "delaySeconds": 10
  }'

GET /v2/studies/{studyId}/targeting returns null when targeting has not been configured. DELETE /v2/studies/{studyId}/targeting clears every trigger, audience rule, and delay without deleting referenced Event, Attribute, or Group definitions.

Trigger Events

Call GET /v2/events to list Event definitions in the authenticated environment. A trigger references the returned id, not an internal numeric Event ID or Event name. Supported Event definitions are:

TRACKED: a code Event sent by a Sprig SDK.
PAGE_URL: a page URL Event configured for Web delivery.

Each Study needs 1–10 unique triggers. Multiple triggers use OR semantics: any one matching Event can trigger the Study. Event properties are not part of this public targeting contract.

The Study API lists existing Events but does not create them. A new code Event must be sent by an SDK and approved in Events > Manage Requests before it can be used.

Audience expressions

Set audience to null to make every visitor eligible after a trigger. Otherwise, provide one condition or a nested group:

{
  "operator": "OR",
  "conditions": [
    {
      "type": "USER_ID",
      "comparator": "EXISTS"
    },
    {
      "type": "LANGUAGE",
      "comparator": "EQUALS",
      "value": "fr"
    }
  ]
}

Groups use AND or OR and can contain conditions or more groups. The limits are:

At most 5 expression levels.
At most 20 direct children in one group.
At most 100 conditions in the complete audience expression.

Condition reference

Condition	Purpose	Comparators
`ATTRIBUTE`	Match a visitor attribute by stable key.	Scalar comparison, text matching, `EXISTS`, `NOT_EXISTS`
`USER_ID`	Distinguish identified and anonymous visitors.	`EXISTS`, `NOT_EXISTS`
`LANGUAGE`	Match the SDK locale or language code.	`EQUALS`
`DEVICE_TYPE`	Match `DESKTOP` or `MOBILE` browser class. Web only.	`EQUALS`, `NOT_EQUALS`
`GROUP`	Match an existing environment Group by stable ID.	`IN`, `NOT_IN`
`SESSION_COUNT`	Match total visitor sessions from 1–999.	Numeric comparison
`PAGE_VIEW_COUNT`	Match page views in the current session from 1–999. Web only.	Numeric comparison

Numeric comparators are EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, and LESS_THAN_OR_EQUAL. Attribute scalar comparison also supports NOT_EQUALS. Text comparison supports CONTAINS, NOT_CONTAINS, STARTS_WITH, and ENDS_WITH. Call GET /v2/attributes for valid Attribute keys and authoring value types. Definitions do not include observed visitor values. Reference fields have these limits:

Attribute keys and Group IDs: 1–128 characters.
Language or locale values: 1–35 characters.
Session and page-view counts: integers from 1–999.

GROUP requires an existing environment Group ID. Study API V2 does not create or list Groups, so an integration must already have the stable ID. If your integration does not have it, configure a different supported condition or contact support@sprig.com.

Delivery delay

delaySeconds is an integer from 0 through 999. Use 0 to present immediately after a qualifying trigger. A delay can protect a critical flow from interruption, but eligibility can change while the timer runs.

Validation and compatibility

An in-product survey cannot launch without at least one trigger. The validation endpoint reports TARGETING_REQUIRED at targeting/triggers when targeting is missing. The API returns:

INVALID_STUDY with detailed issues for an invalid expression or unresolved reference.
STUDY_NOT_FOUND when targeting is requested for a shareable survey.
UNSUPPORTED_TARGETING when existing legacy targeting cannot be represented safely.
400 INVALID_VALUE for a malformed or unquoted If-Match, 412 CONCURRENT_UPDATE for a stale ETag, or 428 CONCURRENT_UPDATE when If-Match is missing.

Do not replace incompatible legacy targeting merely to suppress UNSUPPORTED_TARGETING; review the Study in Sprig first.

​Create or replace targeting

​Trigger Events

​Audience expressions

​Condition reference

​Delivery delay

​Validation and compatibility

Create or replace targeting

Trigger Events

Audience expressions

Condition reference

Delivery delay

Validation and compatibility