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. To integrate programmatically, see 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 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.

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.