Collect feedback with the REST API
Submit a rating or comment to an inbox, attach context, and handle collection errors.
Send your first event
Create a brand and inbox, then an organization API key with the collect scope. Find the inbox's key, not its database ID, in the inbox or widget setup.
curl -i https://api.pollenate.dev/collect \
-H "Content-Type: application/json" \
-H "X-Pollenate-Key: $POLLENATE_COLLECT_KEY" \
--data '{
"inboxKey": "YOUR_INBOX_KEY",
"type": "thumbs",
"score": 1,
"comment": "The setup example answered my question.",
"pageUrl": "https://example.com/docs/setup",
"context": {
"surface": "documentation",
"release": "2026-11"
}
}'A successful write returns HTTP 201:
{ "id": "GENERATED_FEEDBACK_ID", "success": true }Open the matching inbox and confirm the rating, comment and context. The ID identifies this event; it is not a form-response ID.
Request body
| Field | Requirement |
|---|---|
inboxKey |
Required nonempty string |
type |
Required: thumbs, stars, csat, nps, emoji or text |
score |
Optional number from 0 through 10; send it for scored feedback |
comment |
Optional string, at most 2,000 characters |
context |
Optional JSON object for your product context |
sessionId |
Optional string to correlate events |
pageUrl |
Optional string; omit sensitive query parameters |
userAgent |
Optional string; otherwise the request's User-Agent is used |
impressionId |
Optional existing widget impression ID |
Use 0/1 for thumbs, 1–5 for the usual stars/CSAT presentation, and 0–10 for NPS. The collection schema accepts a score across 0–10; your custom UI should enforce its chosen scale.
The field is context, not meta. The route currently accepts externalUserId but does not persist that dedicated field in the feedback row; do not depend on it when reading collected events. Events submitted here have source widget, including direct API calls. MCP and Zapier submission have their own contracts.
Credentials and failures
Only organization API keys in X-Pollenate-Key are accepted here. A brand-scoped key must match the inbox's brand. Prefer collect over broader write or admin keys in an embedded widget.
| Status | Check |
|---|---|
| 400 | JSON fields, supported type, comment length and score range |
| 401 | Missing, expired, revoked or unsupported key |
| 403 | Missing collection scope, wrong organization or wrong brand |
| 404 | Inbox key does not exist |
| 429 | Daily feedback allowance or request rate limit |
| 500 | Persistence failed; record the request details without exposing credentials |
A daily-limit response includes plan, limit and resetIn seconds. Wait before retrying; avoid a tight retry loop. Collection is not idempotent: retrying a request whose outcome is uncertain can create another event.
Comment indexing and automation delivery happen after the write, so a 201 does not promise that a webhook has already arrived or a semantic index has refreshed. See search, webhooks and custom UI.