Segmentation

Segmentation allows publishers to control which users are eligible for specific survey experiences by attaching custom attributes to a participant’s profile.

These attributes are sent during impanelment and can be used to target or restrict access to certain offers.

How segmentation works

Segmentation is powered by the attributes_hash field on the /players/impanel endpoint.

When a user is impaneled:

1. You send custom attributes via attributes_hash
2. TapResearch stores these attributes on the user profile
3. These attributes are evaluated against your offer targeting rules
4. Only users matching an offer’s targeting rules will qualify

Sending segmentation data

Segmentation attributes are passed as a JSON object:

{
  "attributes_hash": {
    "is_premium_user": "true",
    "subscription_tier": "gold",
    "days_since_signup": 7
  }
}

Attribute names beginning with tapresearch_ are reserved.

Supported value types

Type	Example
Number	1, 42, 3.14
String	"gold", "us_west"

For booleans, send "true"/"false" or 0/1 instead of native booleans.

Example use cases

Use segmentation to target content based on your business logic or user state.

Examples

• Target only new users:

  { "is_new_user": "true" }

• Segment by subscription tier:

  { "subscription_tier": "premium" }

• Limit surveys to highly engaged users:

  { "days_since_signup": 30 }

• Exclude users who have already completed onboarding:

  { "completed_onboarding": "false" }

How targeting is applied

Configure attribute filters on your offers in the Publisher Dashboard. Users must match all filters to receive an offer. These filters select your content, not individual surveys.

When to send attributes

• Attributes should be sent during /players/impanel.
• Call the endpoint again to update attributes. New values are merged with existing attributes.
• Updates take effect immediately for future survey requests

Best practices

• Use clear, consistent naming for keys (e.g. is_premium_user, not premiumFlag)
• Keep attribute values simple and predictable
• Avoid sending sensitive or personally identifiable information (PII)
• Only send attributes that are relevant for targeting decisions

Notes

• attributes_hash is optional
• Attributes are stored per user and persist across sessions
• Segmentation is evaluated automatically — no additional API calls are required
• Attributes determine which of your offers the participant receives