> For the complete documentation index, see [llms.txt](https://boundaryai.gitbook.io/boundaryai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boundaryai.gitbook.io/boundaryai-docs/api-and-webhooks/concepts-and-naming.md).

# 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](/boundaryai-docs/feedback-groups/feedback-groups.md) | 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](/boundaryai-docs/analysing-your-feedback/custom-monitoring.md)) 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](/boundaryai-docs/analysing-your-feedback/tracking-feedback-over-time-evolution.md), 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](/boundaryai-docs/api-and-webhooks/changelog.md). 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](/boundaryai-docs/bringing-in-your-feedback/uploading-an-existing-dataset.md).

***

### `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`.