Users & identity
Tie feedback to real people by userId and email — why it matters, how it works, and the API endpoints.
Why identify
#Anonymous feedback tells you what is wrong. Identified feedback tells you who it's hurting and how much it's worth. Once feedback is tied to a user, Sentriment can:
- segment themes by plan, company, or MRR (“what do enterprise accounts complain about?”)
- score each user's health and flag churn risk early
- put a dollar figure on every theme via revenue impact
- honour GDPR access and erasure requests for that person (the endpoints below)
userId, email, or both
#You can identify a user by userId (your own stable ID), by email, or both. Sentriment resolves them in that priority order and treats them as the same person:
curl -X POST https://app.sentriment.com/api/v1/users/identify \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{
"userId": "usr_123",
"traits": {
"email": "dana@acme.com",
"plan": "pro",
"mrr": 499,
"company": "Acme"
}
}'You can also pass userId and email directly on any POST /feedback call — handy for survey tools or forms where you don't call identify separately.
Email-first if you'll sync support tools
#The single most valuable setup decision
If you plan to connect Intercom or Zendesk — or import support history by CSV — always send an email with your users. Email is the join key that stitches a person's widget feedback, API feedback, and support tickets into one profile and one health score.
Here's why it matters. Without email, the same human fragments across sources:
Without email
- ·
usr_123(your app) - ·
zd_991(a Zendesk ticket) - ·
ic_abc(an Intercom chat)
Three “users”, three health scores, MRR counted three times or not at all.
With email
- · one user:
usr_123 - · also known as
dana@acme.com,zd_991,ic_abc
One profile, one health trajectory, one accurate revenue-at-risk number.
It works in any order. If a Zendesk ticket from dana@acme.com arrives before you've identified her, Sentriment creates a shadow user keyed by that email — already scored and alertable. The moment you call identify with the same email, the shadow folds into her real profile, carrying its history along.
Traits
#Traits are arbitrary key/values describing the user — plan, company, mrr, signup_date. They shallow-merge, so you can enrich a user over time, and they power segment filters plus the Impact revenue model (max 32 keys / 8 KB). Send authoritative traits from your server; treat traits sent from a browser (widget keys) as untrusted.
Traits vs metadata
Traits describe the person and persist across their feedback. Metadata describes a single item (which page, which experiment). Rule of thumb: “plan” is a trait; “page: /checkout” is metadata. More in Best practices.
Shadow users & merging
#A shadow user is someone Sentriment knows only by email or a support handle — no userId yet. They show up in Users with a badge, are fully scored, and can trigger at-risk alerts. When you later identify them, an exact email match merges automatically; anything ambiguous (a shared support@ mailbox, two accounts claiming one email) becomes a “possibly the same person” suggestion you confirm with one click.
You control this under Settings → Identity: link by email automatically, suggest-only, or off — plus an ignore list for staff domains and shared inboxes.
GDPR erasure works by any identifier
An erasure request keyed on a user's email erases the whole merged profile — feedback, traits, health history, and every alias — even if their canonical ID is a userId. Both endpoints below accept a userId or a known email.
Endpoints
/api/v1/users/identifysecret or widget keyIdentify — attach traits
Mixpanel-style. Traits (plan, company, MRR, …) shallow-merge and power segment filtering and per-segment cluster breakdowns in the dashboard. Max 32 keys / 8 KB. An email trait doubles as an identity: feedback arriving from Zendesk, Intercom, CSV imports, or the API with that email lands on this user's profile, and any matching shadow user merges in automatically.
curl -X POST https://app.sentriment.com/api/v1/users/identify \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{ "userId": "usr_123", "traits": { "plan": "pro", "mrr": 499, "churned": "true" } }'/api/v1/users/{userId}secret keyGet a user — right of access (Art. 15)
Everything Sentriment holds about one of your users: traits, first/last seen, and their feedback items (PII-redacted, up to 200). Accepts a userId or a known email alias; forward it directly in response to a data-access request.
curl "https://app.sentriment.com/api/v1/users/usr_123" \
-H "Authorization: Bearer sk_live_…"/api/v1/users/{userId}secret keyDelete a user — right to erasure (Art. 17)
Queues a hard delete of the user's entire footprint: every feedback item and the identity profile with its traits and aliases. Accepts a userId or a known email. Cluster counts recompute. Returns 202 with a request id; completes within minutes.
curl -X DELETE https://app.sentriment.com/api/v1/users/usr_123 \
-H "Authorization: Bearer sk_live_…"
# → { "requestId": "01KX…", "status": "pending" }