> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masivo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Review forms

> Learn what review forms are in Masivo and how to collect structured feedback through the API.

Review forms let you define reusable questionnaires in the Masivo dashboard and collect answers from your apps, websites, or integrations through the Storefront API. Each review form stores its field schema in Masivo; your client renders the UI and submits reviews.

Common use cases include post-purchase ratings, NPS-style surveys, comment threads, and custom feedback flows.

To create and manage review forms in the dashboard, see the [Create and manage review forms guide](/guides/create-and-manage-review-forms). To integrate programmatically, see [Submit reviews](/api-reference/guides/submit-reviews).

## Form types vs field types

**Form type** describes the overall intent of the review form. It is metadata for your team and does not change API validation by itself:

| Form type | Typical use                          |
| --------- | ------------------------------------ |
| `RATING`  | Star or numeric satisfaction surveys |
| `COMMENT` | Open feedback                        |
| `THREAD`  | Multi-step or conversational flows   |
| `CUSTOM`  | Any other structured feedback        |

**Field types** define how each answer is validated when a review is submitted. Answers are always keyed by the field **`name`** (not an internal id).

| Field type     | Answer shape     | Validation                              |
| -------------- | ---------------- | --------------------------------------- |
| `SCORE`        | Number           | Between `min` and `max` (defaults: 1–5) |
| `TEXT`         | String           | Free text                               |
| `SELECT`       | String           | Must match one `options[].value`        |
| `MULTI_SELECT` | Array of strings | Each value must be in `options[].value` |

## Field images

Each field can include up to **5 images** (for example, icons for a score scale). Images are stored as public URLs from your account **multimedia** library, plus an optional `alt` text for accessibility.

## Lifecycle and visibility

| Status     | Dashboard | Storefront API                                   |
| ---------- | --------- | ------------------------------------------------ |
| `ACTIVE`   | Visible   | `GET /review-forms/{id}` returns the review form |
| `INACTIVE` | Visible   | Treated as not found (`404`)                     |

Deleting a review form in the dashboard performs a soft delete and sets the form to inactive.

## Events and analytics

Every successful review submission creates a resolved **`REVIEW`** [customer event](/concepts/events) linked to the review. You can use `source`, `platform`, `brand_id`, `store_id`, and `channel_id` on the review for attribution, similar to other storefront activity.

Review forms can optionally be linked to a journey. New submissions copy the configured journey id to `reviews.journey_id` and enqueue the `REVIEW` event for that journey, so follow-up automation can branch from the submitted review.

Anonymous reviews are supported: omit `customer_id` in the API request. The review row stores `customer_id` as `null`, while the linked event uses the review id as the customer identifier for tracking.

## Review analysis operations

Masivo can process submitted reviews with an internal AI cron route and store validated review analysis in the `reviews.review_analysis` JSON column. The job is not trigger-based. It is designed to be scheduled externally, typically every five minutes, and processes up to 50 reviews per run using a Redis cursor.

The processor:

* reads new review rows from `reviews`
* analyzes answer content, including score-only reviews
* validates strict JSON output against the configured analysis catalog
* stores `pending`, `processed`, or `failed` status per review
* updates the source review row, including `updated_at`, so review backfills can sync AI changes
* records AI validation errors for debugging

The operational route is:

`POST /api/cron/analytics/review-analysis`

It requires the standard `x-masivo-cron-auth` header. Passing `force: true` resets the Redis cursor so processing starts from the beginning again.

## Permissions

Access to the Review forms section in the dashboard is controlled by the **`review_forms`** role resource:

* **read** — view review forms and reviews
* **write** — create and edit review forms
* **delete** — delete review forms

Configure permissions under **Settings → Roles**.