Skip to main content

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.

See the full parameter and response reference for GET review form, POST review, and GET reviews.

​
Prerequisites

Authenticate with the Storefront API using a Bearer access token. See Integrate with Masivo.
These endpoints are available with CLIENT and SERVER API keys. CLIENT keys are suitable for embedded apps that only need to read review form definitions and submit reviews.

​
1. Load the active review form

Fetch the review form schema before rendering your UI: 
const reviewFormId = "your-review-form-uuid";
const response = await fetch(
  `https://app.masivo.ai/api/storefront/v1/review-forms/${reviewFormId}`,
  {
    headers: { Authorization: `Bearer ${accessToken}` }
  }
);
const { data: reviewForm } = await response.json();
Only review forms with status: "ACTIVE" are returned. Inactive or deleted forms respond with 404. Use reviewForm.fields to build inputs. Each field has a name (API key), label, type, and optional options, images, min, and max.

​
2. Submit a review

Send answers keyed by field name (not field id): 
const payload = {
  customer_id: "unique-customer-id",
  source: "app",
  platform: "ios",
  brand_id: "0001",
  store_id: "store_1",
  channel_id: "mobile",
  answers: {
    score: 4,
    reason: ["wait_time"],
    comment: "Good follow-up"
  },
  respondent: {
    name: "Jane Doe"
  },
  metadata: {
    trip_id: "trip_1"
  }
};

const submit = await fetch(
  `https://app.masivo.ai/api/storefront/v1/review-forms/${reviewFormId}/reviews`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);
const { data: review } = await submit.json();
On success you receive 201 with the created review, including event_id for the linked REVIEW event.

​
Anonymous reviews

Omit customer_id when the respondent is not known: 
const payload = {
  source: "google_maps",
  answers: {
    score: 5
  },
  respondent: {
    name: "Anonymous reviewer"
  }
};
The review stores customer_id: null. The linked event uses the review id as the customer identifier.

​
3. List reviews (optional)

Paginate and filter stored reviews: 
const params = new URLSearchParams({
  from: "0",
  to: "20",
  review_form_id: reviewFormId,
  source: "app"
});
const list = await fetch(
  `https://app.masivo.ai/api/storefront/v1/reviews?${params}`,
  {
    headers: { Authorization: `Bearer ${accessToken}` }
  }
);
const { count, from, to, data } = await list.json();

​
Common errors

StatusCauseExample details
400Answer validation failedField score is required
400Invalid option valueField reason must only include configured options
404Review form not found or inactive—
422Missing or invalid body fieldsZod issues (for example missing source)

​
Answer rules by field type

Field typeanswers value
SCORENumber within min–max
TEXTString
SELECTString matching an option value
MULTI_SELECTArray of strings, each matching an option value
Required fields must be present and non-empty. Optional fields can be omitted.