Service forms

Service forms let you define reusable questionnaires in the Masivo dashboard and collect answers from your apps, websites, or integrations through the Storefront API. Each form stores its field schema in Masivo; your client renders the UI and submits reviews. The dashboard calls them service forms. Existing API paths and permission keys keep the technical review-forms and review_forms names for compatibility. Common use cases include post-purchase ratings, NPS-style surveys, comment threads, and custom feedback flows. To create and manage service forms in the dashboard, see the Create and manage service 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.

Ticket automation

Service forms can open a support ticket from the responses they receive. Enable Ticket automation in the form settings, pick the pipeline and priority the generated tickets should use, and decide which responses deserve a ticket.

Setting	Default	Description
`enabled`	`false`	Turns the automation on for this form
`pipeline_id`	—	Explicit pipeline for generated tickets; required when automation is enabled
`priority`	`medium`	Priority applied to every generated ticket
`trigger`	`always`	`always` opens a ticket per response; `conditions` filters them
`conditions`	`[]`	Condition groups evaluated against the response

The ticket title comes from the form name and the description is a recap of the submitted answers. The response is linked to the ticket, so agents can open the original submission from the ticket detail.

Conditions

Conditions use the same rule set as campaigns, rewards, and journeys: conditions is a list of groups, every condition inside a group must match (AND), and any group matching is enough to open the ticket (OR).

Condition type	Reads	Operators
`Response answer`	The answer named in `field`	Depend on the field type, see below
`Response sentiment score`	The AI sentiment score of the response (0-100)	`greater than`, `less than`, `equal to`, and their variants
`Response emotion`	The emotions the AI detected in the response	`is` (detected), `is not` (not detected)
`Response risk flag`	The risk flags the AI detected in the response	`is` (detected), `is not` (not detected)

Response answer is only offered when the form has at least one field, and the operators follow the type of the answer you pick:

Field type	Operators	Value
`SCORE`	`greater than`, `greater than or equal to`, `less than`, `less than or equal to`, `equal to`, `not equal to`	Number between the field `min` and `max`
`TEXT`	`equal to`, `not equal to`, `contains`, `starts with`, `ends with`	Free text
`SELECT`, `MULTI_SELECT`	`equal to`, `not equal to`	One of the configured options

Answers that arrive empty never match, so a missing field cannot open a ticket on its own. On multi-select answers, equal to matches when the value is one of the selected options. Text comparisons ignore letter casing.

{
  "enabled": true,
  "priority": "high",
  "trigger": "conditions",
  "conditions": [
    [
      {
        "primitive": "custom",
        "type": "Response answer",
        "field": "score",
        "operator": "less than or equal to",
        "value": "2"
      }
    ],
    [
      {
        "primitive": "custom",
        "type": "Response risk flag",
        "operator": "is",
        "value": "churn_risk"
      }
    ]
  ]
}

Answer conditions are evaluated as soon as the response is stored. Conditions that read the AI analysis (sentiment, emotions, risk flags) are evaluated when the review analysis job processes the response, so those tickets appear a few minutes later. A group whose answer conditions already fail is discarded without waiting for the analysis, and a group that fully matches on answers opens the ticket right away. Ticket creation runs after the response is stored: if the pipeline or the routing is misconfigured, the response is still saved and the API keeps returning 201. New tickets are assigned to the available agent with the lightest open load, respecting each agent’s maximum open tickets. Accounts without a configured agent roster get unassigned tickets.

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

New responses take priority in each run. The remaining slots go to reviews that need another attempt: those left in failed, and those stuck in pending because a previous run was interrupted. Each attempt increases retryCount, and a review stops being picked up after 3 of them, so a permanently broken response cannot block the queue. A successful analysis resets retryCount to 0. Because ticket automation runs right after the analysis, recovering a failed analysis also recovers the ticket that was waiting for it. 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 Service forms section in the dashboard is controlled by the review_forms role resource:

read — view service forms and reviews
write — create and edit service forms
delete — delete service forms

Configure permissions under Settings → Roles.

Get Started

Guides

Use cases

Integrations

Form types vs field types

Field images

Lifecycle and visibility

Ticket automation

Conditions

Events and analytics

Review analysis operations

Permissions

​Form types vs field types

​Field images

​Lifecycle and visibility

​Ticket automation

​Conditions

​Events and analytics

​Review analysis operations

​Permissions

Form types vs field types

Field images

Lifecycle and visibility

Ticket automation

Conditions

Events and analytics

Review analysis operations

Permissions