Pushing feedback

Single pushes, bulk backfills, file ingest, dedup, and back-dating.

Everything about getting data in, beyond the five-minute version in Getting started: which ingestion path to use, how deduplication and back-dating behave, and what happens after the push.

---

Three ways in

Path	Use when	Behaviour
POST /feedback/push	A steady trickle into one field: each ticket, review, or call as it closes.	Synchronous; the response reports inserted and skipped_duplicates. Each item becomes its own respondent.
POST /feedback/push/bulk	Several fields in one call: a whole record per respondent, backfills, batch jobs.	Async 202 with a task_id and status_url by default; poll until completed. Small batches can run synchronously with "sync": true (below).
POST /feedback/upload	You already have a CSV or XLSX export.	Multipart upload; same async task flow as bulk.

All three land in the same place and trigger the same analysis. Prefer bulk over looping single pushes: one call for thousands of items is friendlier to your rate limits (60/minute per key by default) and to the platform.

Bulk push: one respondent, several fields

/feedback/push/bulk takes a list of fields, each with its own content array, and records the whole batch as one respondent's answers. That is how you push a full record (the open comment and its NPS score) as one row rather than as unrelated lines; the single-push endpoint, by contrast, treats every item as its own respondent. When each record is a different person, send one record per bulk call (the synchronous mode below is built for exactly that). An optional source_reference (up to 255 characters) is stored on every row of the batch, so you can tag which system or job produced it.

Synchronous bulk push

Integration platforms and webhook receivers usually deliver one record per call and cannot poll a task id. Add "sync": true and the batch runs inline, returning 200 with the completed per-field result instead of a task id:

curl -X POST https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/feedback/push/bulk \
  -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-58121-v1" \
  -d '{
    "feedback_group_id": "1842",
    "source_id": "9021",
    "sync": true,
    "source_reference": "crm-webhook",
    "fields": [
      {"field_id": "31245", "content": [{"text": "Support resolved my issue in one call.", "external_id": "ticket-58121"}]},
      {"field_id": "31246", "content": [{"text": "9", "external_id": "ticket-58121"}]}
    ]
  }'

The rules that keep this safe:

• Every row must carry an external_id; otherwise the call is rejected with SYNC_REQUIRES_EXTERNAL_ID (400). An inline push can be cut short by its timeout, and the id is what lets a retry converge on the same rows instead of duplicating them.

• Small batches only: up to 50 items across up to 20 fields. Larger batches, and requests arriving while the inline capacity is busy, silently fall back to the asynchronous path and return 202 with a task id, so a client that always sends sync still works.

• Honest status codes: if no field accepted anything, you get 400 PUSH_FAILED with the per-field detail rather than a 200 that hides rejected rows. A push that exceeds its 60-second budget returns 504 SYNC_PUSH_TIMEOUT; rows already written stay written, so retry with the same external_id values.

---

Structured items: the fields that earn their keep

An item in content can be a bare string, but production integrations should send objects:

{"text": "Support resolved my issue in one call.",
 "external_id": "ticket-58121",
 "customer_id": "cus_310",
 "channel": "support",
 "language": "en",
 "rating": 5,
 "occurred_at": "2026-07-12T09:30:00Z"}

• external_id is your stable identifier, and it's what makes retries safe: within a field, a second push with an external_id that already exists is skipped, and the response counts it under skipped_duplicates with the IDs in duplicate_external_ids. Note that this is a skip, not an update: pushing a corrected text under the same external_id leaves the original in place. Without an external_id, a replayed batch means duplicate comments polluting your analysis.

• occurred_at back-dates the item to when the feedback actually happened. This matters most for time-tracked groups: a June ticket pushed in July lands in June's period, not July's. Omitted, items date to arrival time.

• customer_id ties items to a person across sources, powers bulk erasure, and pairs with the external_id on invites so you can join the full loop in your warehouse.

• channel, language, rating become segmentation metadata, exactly like metadata columns on an upload.

Numeric fields (NPS, ratings) take their value as the item's text ("9"); non-finite values are rejected at ingestion.

Two layers of retry safety compose: external_id deduplicates at the item level forever, and the Idempotency-Key header makes an entire request replayable for 24 hours (same key = same response, no re-processing). Use both; networks fail mid-request more often than anyone likes.

---

What happens after a push

1. Items are cleaned, language-detected, and queued for analysis automatically; there is no "run analysis" call to make.

2. Group monitors with Auto-cover new sources on are already watching API-created sources (Custom Monitoring), so monitor matches and alerts fire from the first pass.

3. When the pass finishes, the analysis.completed webhook fires, and GET /sources/{id}/analysis returns the sentiment distribution, themes, and monitor matches. Analysis takes minutes to tens of minutes depending on volume; until a run has completed, the read returns analysis_status: "none" with zeroed figures that are not results.

4. For a source in a group that tracks feedback over time, the read aggregates every analysed period (the same corpus as the dashboard's Overall view) and returns analysis_status: "available" with analysis_id: null; key on analysis_status, never on analysis_id.

5. The data participates in everything else: Grouped Themes, Evolution periods, reports, and the dashboards, indistinguishable from survey or upload data.

Pushing consumes your organisation's Usage Allowance when analysed, the same metering as every other analysis on the platform; see Settings. The push response's rows_accepted is the number of rows admitted (aps_deducted is a legacy alias of it); nothing is charged at push time, and test keys are never charged.

---

Erasing and listing what you pushed

You stay in control of the data your integration created:

• GET /feedback lists API-pushed items (filter by source_id / field_id, cursor-paginated), useful for reconciliation jobs. It never includes native survey responses.

• POST /feedback/erase bulk-deletes by external_ids or by customer_id, which is the mechanical piece of honouring a GDPR erasure request: one call removes a person's API-pushed feedback across sources. It only touches API-pushed rows; survey responses and uploads have their own product-side deletion flows.

---

Integration checklist

• One key per integration, push scope, Idempotency-Key on every write.

• Always send external_id and occurred_at; your future self doing a re-sync will thank you.

• Use bulk for anything over a handful of items; poll the status_url or subscribe to content.pushed. Use sync: true when your caller needs the outcome in the same response.

• Subscribe to analysis.completed instead of polling the analysis endpoint.

• Map customer_id to the same identifier your CRM uses, so erasure and invite joins stay one-call operations.