Every entity subscribed to Review Generation gets a standard, non-customizable Review Collection Page. If you want full control over the look, feel, and additional data collected on your collection experience, build a custom Collection Page using the Review Submission API. This article covers how the API works and the options to consider when building your pages.

How Reviewers Access Collection Pages

• Via invitation: a business sends an invitation with a link directly to a customer.
• Without an invitation: a business publishes a standard, publicly accessible Collection Page that customers can access on their own.

Common Collection Page Structures

• One page per entity: the most common structure, with a unique Collection Page for each entity you want reviews for. A business with 100 products, for example, would have one page per product.
• One page with an entity selector: a single page serves multiple entities, and the reviewer selects which entity to review. The page includes the selected entity in its API request. A business might use one page for an entire product category, with a selector for the specific product.
• One page collecting multiple entities: a single page collects reviews for more than one entity in the same session. For example, a business with separate "Auto Insurance - Coverage" and "Auto Insurance - Service" entities might let one customer review both from a single form.

Plan Your Implementation

Before you start building, consider:

• Which entities need a Collection Page, and whether you need one form template or several depending on entity type.
• Which experiences you want to support: just review creation, or also update and delete.
• Whether you plan to collect additional attributes beyond the standard review fields.

Design is entirely up to you. The only requirement is that your page can make requests to the Review Submission endpoints to submit a review, and optionally to update or delete one.

Review Requirements

Reviews collected through your page must conform to the Yext review object: a 1-5 star rating, review text, and author information. The review object doesn't support sub-ratings or custom fields for additional reviewer attributes, but you can attach review labels to a submitted review. See the API Documentation for the full review object reference.

Prevent Spam

Building a custom Collection Page means exposing an API key client-side, which lets anyone who finds it submit reviews directly to your account. Yext doesn't currently offer built-in CAPTCHA support for these requests. If you want to verify that submissions come from real users, add a CAPTCHA solution, such as Google reCAPTCHA or hCaptcha, with a proxy server between your Collection Page and the Yext API. The proxy validates the CAPTCHA response, then forwards verified requests to Yext.

Review Submission API Endpoints

Set Up API Access

Create an app in the Developer Console and grant it access to the Review Submission Content Delivery API, which covers create, update, and delete. Since this API key is exposed client-side, scope the app to this permission only.

Create a Review

Collect the required fields on your page, typically through a form, and submit them to the Review Submission: Create endpoint when the user submits.

Handle the API Response

The Create endpoint doesn't create the review synchronously, so it can't return a review ID right away. A successful request returns a 202 Accepted response along with an apiIdentifier either the invitationUid you passed in the request, or a newly generated UUID if you didn't pass one. This value maps 1:1 to the resulting review and is required to update or delete it later. A request with validation issues, such as an invalid email address, returns a 400 error your page can display to the user.

Support Updating and Deleting Reviews

Support letting end users update or delete their own reviews. Two scenarios come up most often:

• The user wants to fix a mistake or change their mind immediately after submitting.
• The business responds to a review, and the resolution prompts the end user to update or delete their original review, sometimes well after submission.

These two scenarios call for different approaches.

Immediate Updates

Because a review submitted through Review Submission: Create isn't available right away through Review: Get or Review: List, support immediate updates by storing the review content and the returned apiIdentifier on the client side. Any update or delete request the user triggers right after submission can reuse that stored value.

Non-Immediate Updates

To support edits after the user has left the page, fetch the review later using the Streams API rather than relying on stored client-side data. Filter your Streams API request on the apiIdentifier field to retrieve the matching review, then render an edit experience with that data. Please note that the review in question will need to have the LIVE status in order to be returned by Streams API. If the review is still QUARANTINED, it will not be returned by Streams API.

Two examples illustrate when this comes up:

• Notifying a reviewer of a response: listen for REVIEW_COMMENT_UPDATED webhook events. When a business responds to a first-party review, email the reviewer a link back to the Collection Page with the apiIdentifier as a query parameter. When they click through, the page fetches the review by apiIdentifier and renders the edit experience.
• Returning through the original invitation link: if a user clicks their original invitation email again after already leaving a review, the page receives the same invitationUid as a query parameter. Since apiIdentifier equals invitationUid whenever an invitation was used to create the review, fetch the review using that value. If a matching review exists, render the edit experience; if not, render the standard creation experience.

A review's apiIdentifier is a generated UUID rather than an incremental Review ID, which is more secure for this purpose: an incremental ID would let anyone increment or decrement a known value to access other reviews.

Fetch Reviews via Streams API

The Streams API is a low-latency, customizable API suited to fetching reviews from the client side. Yext provides a preconfigured app for this use case that creates a Streams Endpoint with the ID reviewsStreamsEndpoints_reviews, so you don't need to configure indexing manually. A sample request looks like: