Developer docs
Incentives and disclosure
You may thank customers for their time. You may not pay for praise. YouSaid enforces that difference in the data model, not only in policy text. This page describes product behavior; it is not legal advice for your market.
Participation only
- An incentive rewards taking part: the customer responded, with any score and any sentiment, whether or not they allow public use.
- Eligibility rules that mention rating, sentiment, positive, stars, score, favorable or NPS are rejected, and the database refuses any incentive that is not marked sentiment-independent.
- Declining public use never removes a promised reward.
- Rejecting a reward with a reason that cites what the customer said is refused.
Setting an incentive
Workspace owners and admins set one incentive per collection flow. It needs a type and a disclosure text of 10 to 1,000 characters, and may carry a provider, value and currency.
| Type | How it is fulfilled |
|---|---|
| coupon, account_credit, gift_card | Issued through the rewards ledger. Every issuance starts pending and needs a person to approve it; above your dual-control threshold the approver must be a different person from the requester. Gift cards use the configured e-gift provider, or wait for manual fulfilment when none is configured. |
| feature_unlock | Issued through the rewards ledger with the same participation rule and human approval. Set an unlock key on the incentive (for example beta.reports). On approval, the signed proof.reward.feature_unlock webhook carries the reward id, your own customer id and the unlock key; your product switches the feature on and confirms with POST /api/v1/proof/rewards/{id}/confirm (idempotent), or a person confirms it in Automation > Rewards. |
| charity, physical_gift, personal_note, referral | Recorded on the incentive and disclosed, but not issued by the rewards ledger. Fulfil them yourself. |
The ledger exports as CSV for accounting, with coupon codes masked. A proof.reward.issued webhook fires when a reward is issued, so your billing system can apply account credit.
Disclosure
- The disclosure text is copied onto every issuance, so later edits do not rewrite history.
- A story tied to an incentive is shown only when that incentive exists, has disclosure text and is sentiment-independent. Otherwise it is kept out of every placement with the reason incentive_missing, incentive_disclosure_missing or incentive_sentiment_conditioned.
- When it is shown, the render manifest carries the disclosure and the label incentivized_participation. The React components and the Web Component (part disclosure) display it with the story. If you render the headless manifest yourself, you must display it too.
- Structured data is never emitted for incentivized stories.
- Agents that schedule asks with an incentive must include its disclosure text in the message, or the proposal fails its policy check.
No review gating
- Every score band sees the same review destinations on the thank-you screen. Routing rules have no field that could change that.
- Mixed and critical responses stay visible to your team. A detractor response always creates a follow-up task and can open a private support thread or offer a Room; it is never dead-ended.
- Promoters can become ask candidates. Routing never sends an ask by itself: an ask goes out only when a person sends it or an automation policy that a person approved allows it. Nobody is asked for 90 days after a detractor score.
- Request experiments can vary send time, channel or form, never who is asked based on sentiment.