Triggering Surveys from Code

There are two ways to get a survey in front of a specific user: fire an event and let the survey’s trigger rules decide, or target the user directly from your backend. Which one fits depends on whether the moment is a client-side event or something your server already knows.

Event-driven triggering

Call track() after the action that should be able to surface a survey — a completed checkout, a finished onboarding step, a support ticket closed:

oneSygnal.track('checkout_completed', { orderTotal: 84.5 });

Every track() call runs the same two-stage check on every platform: does any survey’s Trigger match this event name, and if so, do its Rules (evaluated against the event’s properties, the user’s traits, and eventHistory) pass? See How Triggering Works for the full Stage 1/Stage 2 breakdown. A survey with no triggerEventNames matches any event — so track() calls you already make for analytics can surface a survey without any code change on your side once the survey is configured to listen for that event name.

Pair track() with identify() so trigger rules can read user traits, not just event properties:

oneSygnal.identify('user_123', { plan: 'pro' });
oneSygnal.track('checkout_completed', { orderTotal: 84.5 });

This is subject to Throttling (Cooldown/Daily Cap) like any other survey — an event matching a trigger doesn’t guarantee a display.

Targeting from your backend

Event-driven triggering only works for things the client observes. If the moment lives on your server — a subscription renewal, a support ticket resolution, a batch job — target the user directly via the Server API instead:

POST /v1/surveys/{surveyId}/targets
Authorization: Bearer sk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
Content-Type: application/json
 
{ "userIds": ["user_123"] }

A targeted user sees the survey on their next page load regardless of trigger rules — targeting adds recipients on top of whatever the trigger already delivers to, it doesn’t replace it. This requires a plan with API-triggered surveys enabled, and the userIds you pass must match IDs you’ve already established via identify().

See Webhooks → wasDirectTarget for how targeted vs. trigger-delivered respondents show up in your webhook payloads afterward.