Skip to documentation

Collect feedback with the REST API

Submit a rating or comment to an inbox, attach context, and handle collection errors.

Updated Read as Markdown

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.

bash
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:

json
{ "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.