Concepts & naming

How API nouns map to what you see in the product.

The API speaks the same model as the product. Four nouns cover almost everything:

API noun (recommended)	In the product	What it is
feedback_group	Feedback Group	The project container. Everything about one programme lives in one group.
source	A source inside a group	One stream of feedback: a survey, an upload, a connector, or your API push.
field	A question / column	One typed slot on a source: open text, NPS, a scale, metadata.
item (in content)	A response / comment	One piece of feedback pushed into a field.

Two product concepts you'll meet in responses:

• Monitors (Custom Monitoring) appear in analysis reads under the flags key, and the related webhook event is flag.raised. Those are the legacy wire names for what the product now calls monitors; the payloads are stable so existing subscribers don't break.

• Analysis is asynchronous. Pushing returns immediately; themes, sentiment, and monitor matches appear when the analysis pass completes (subscribe to analysis.completed rather than polling). For a source in a group that tracks feedback over time, the analysis read aggregates every analysed period and returns analysis_id: null, because there is no single all-time run to name; key on analysis_status ("available" or "none"), never on analysis_id.

---

Already integrated on the older vocabulary?

Integrations built when the API spoke survey_series / survey / question keep working unchanged: those routes (/survey_series/create, /survey/create, /content/push, and friends) hit the same handlers as the routes documented here, are fully supported, and are covered by the compatibility policy. We keep them out of the main reference so there's exactly one documented way to do each thing; they are listed under Classic vocabulary (aliases). The mapping, should you read old code: survey_series = feedback group, survey = source, question = field.

---

Field types

When creating a source, each field takes a field_type:

Type	Use for
DEPTH_TEXT	Long free text: the field the AI analyses for themes, sentiment, monitors.
TEXT	Short free text: names, one-liners.
NPS	The 0-10 likelihood-to-recommend score.
RATING	A numeric scale with your own bounds (min_value / max_value).
SCQ / MCQ	Single / multiple choice (field_options).
DROPDOWN	Single choice presented as a drop-down list (field_options).
RANKING	Respondents order the field_options.
METADATA	Context for segmentation (region, tier, agent); imported but not analysed.

Names are case-insensitive, and long_answer / short_answer are accepted as synonyms for DEPTH_TEXT / TEXT. A source takes up to 100 fields per create call.

The richest analytical signal comes from DEPTH_TEXT fields; METADATA fields power segmentation in the analysis views, exactly as with uploads.

---

feedback_type: tell the platform what the data is

Sources take an optional feedback_type (survey, call_transcript, app_review, support_ticket, chat, email, social_media, review, other; default survey). It's echoed in listings and helps the platform frame the data correctly. Pick the closest one rather than defaulting everything to other.