Submit reviews

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. Both from and to are required (zero-based, inclusive range):

const params = new URLSearchParams({
  from: "0",
  to: "20",
  review_form_id: reviewFormId,
  customer_id: "user_abc123",
  source: "app",
  platform: "ios",
  brand_id: "0001",
  store_id: "store_1",
  channel_id: "mobile",
  anonymous: "true",
  created_from: "2026-07-01T00:00:00Z",
  created_to: "2026-07-31T23:59:59Z"
});
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();

Query param	Description
`from`, `to`	Required pagination indices (0-based)
`review_form_id`	Filter by review form UUID
`customer_id`	Filter by customer external id
`anonymous`	`"true"` returns only reviews with `customer_id: null`
`source`, `platform`	Attribution dimensions
`brand_id`, `store_id`, `channel_id`	Commerce scope filters
`created_from`, `created_to`	ISO timestamps for submission window

Common errors

Status	Cause	Example `details`
`400`	Answer validation failed	`Field score is required`
`400`	Invalid option value	`Field reason must only include configured options`
`404`	Review form not found or inactive	—
`422`	Missing or invalid body fields	Zod issues (for example missing `source`)

Answer rules by field type

Field type	`answers` value
`SCORE`	Number within `min`–`max`
`TEXT`	String
`SELECT`	String matching an option `value`
`MULTI_SELECT`	Array of strings, each matching an option `value`

Required fields must be present and non-empty. Optional fields can be omitted.

Review forms concept
Create and manage review forms
Customer events — includes REVIEW events

API Documentation

Endpoints

Guides

Resources

Submit reviews

Prerequisites

1. Load the active review form

2. Submit a review

Anonymous reviews

3. List reviews (optional)

Common errors

Answer rules by field type

​Prerequisites

​1. Load the active review form

​2. Submit a review

​Anonymous reviews

​3. List reviews (optional)

​Common errors

​Answer rules by field type

​Related documentation

Prerequisites

1. Load the active review form

2. Submit a review

Anonymous reviews

3. List reviews (optional)

Common errors

Answer rules by field type

Related documentation