> ## 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.

# Submit reviews

> Learn how to load a review form definition and submit reviews through Masivo's REST API

<Note>
  See the full parameter and response reference for [`GET review
      form`](/api-reference/review-forms/\[id]/get), [`POST
      review`](/api-reference/review-forms/\[id]/reviews/post), and [`GET
      reviews`](/api-reference/reviews/get).
</Note>

### Prerequisites

Authenticate with the Storefront API using a Bearer access token. See [Integrate with Masivo](/api-reference/guides/integrate-with-masivo).

<Note>
  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.
</Note>

### 1. Load the active review form

Fetch the review form schema before rendering your UI:

```typescript theme={null}
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):

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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

| 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.

### Related documentation

* [Review forms concept](/concepts/review-forms)
* [Create and manage review forms](/guides/create-and-manage-review-forms)
* [Customer events](/concepts/events) — includes `REVIEW` events