Yext Review Generation allows businesses to send email and SMS invitations to their customers to request a review using the Review Balancing URL. This URL directs users to third-party review sites and/or your first-party review collection page, depending on the distribution you set for the review balancing algorithm. You can learn more about the Review Balancing Algorithm in the Get Started with Reviews guide.
You can use the Review Invitations API to integrate with an external system and manage invitations programmatically.
Integration Patterns
Most Review Invitations integrations use one of two patterns.
Push: your external system notifies your application as soon as a trigger occurs, and your application then creates the invitation. Common push triggers include:
- A customer receives a product, and the fulfillment system signals that delivery is complete.
- A customer completes a purchase at a physical location, and the point-of-sale system signals that the transaction is complete.
- A patient completes a visit, and the scheduling system signals that the appointment status has updated.
Pull: your application periodically fetches invitation-triggering data instead of receiving a real-time notification. Pull integrations are common when the external system doesn't support webhooks for the relevant trigger, or when invitation data is exported to an FTP location on a schedule.
Review Invitations API Endpoints
| Endpoint | Description | URL |
|---|---|---|
| Review Invitations: Create | Creates a new Review invitation | POST https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites |
| Review Invitations: Get/List | Fetches existing Review Invitations | GET https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites |
| Review Invitations: Update | Updates an existing Review invitation | PUT https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites/{uid} |
| Review Invitations: Delete | Deletes an existing Review Invitation | DELETE https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites/{uid} |
Invitation Fields
An invitation includes the following core fields. Additional fields are required in the request body; see the API Documentation for a complete reference.
| Field | Description |
|---|---|
| Entity ID* | The entity the review is being requested for. |
| First Name* | The first name of the person the review is being requested from. |
| Last Name* | The last name of the person the review is being requested from. |
| Title | The title of the person the review is being requested from, such as Mr., Mrs., or Miss. |
| Contact* | The email address or phone number of the person the review is being requested from. |
| Template ID | The template used to format the invitation. |
| Transaction ID | The ID of the transaction the invitation relates to. |
| Review Label Names | The names of the review labels to attach to the resulting review. |
| Additional URL Parameters | A JSON object of key-value pairs to append to the Review Balancing URL. |
*Required field.
Confirm your application can supply all the fields it needs before you build your integration.
Set Up API Access
Create an App
Create an app in the Developer Console and grant it access to the Review Invitations API. Read access is sufficient for the Get/List endpoints. However, to Create, Update, or Delete invitations, write access is required. An API key will be generated for your app to access the Review Invitations endpoints. You will not want to expose this API Key on your client-side pages, so make sure you are not using this App for any client-side requests.
Create an Invitation
A request to the Review Invitations: Create endpoint sends an invitation to the contact you specify. The Review Generation system will send an SMS if you provide a phone number or an email if you provide an email address.
The response includes two fields you'll need for later requests:
-
invitationUid: a unique identifier for the invitation. -
feedbackUrl: the full URL included in the invitation, withinvitationUidappended as a query parameter. When the recipient submits a review from this URL, include theinvitationUidin the review creation request so the system can attribute the review to the invitation.
Include Additional Details on an Invitation
The API supports two ways to pass additional context with an invitation, which you can then use in the resulting review.
Review labels: pass values in the reviewLabelNames field. When a review is created with the matching invitationUid, those values are applied to the review as review labels. For example, passing "In-Store" in reviewLabelNames applies an "In-Store" label to the resulting review.
Additional URL parameters: pass a JSON object of key-value pairs in the additionalURLParameters field. These are appended as query parameters to the feedback URL, so your Collection Page can read them and use them however you need, including sending the data to an external attribution system rather than applying it as a label.
Send Invitations from an External System
If your business handles its own email or SMS delivery, you can create an invitation record in Yext without having Yext fulfill it by passing sendInvitationFromYext = FALSE in the request body. This is useful when:
- You want Yext to remain the source of truth for invitations sent, even though your own system delivers them.
- You want to accept reviews only from customers who received an invitation, which requires the additional configuration described below.
Require an Invitation UID for Submission
By default, a public Collection Page allows anyone with the URL to leave a review, which many businesses want. To restrict submissions to invited customers only, enable Require Invitations for First-Party Reviews in your account settings. Once enabled, every request to the Review Submission: Create endpoint must include a valid invitationUid, or the review is rejected.
If you're fulfilling invitations from an external system and also require this setting, send the returned feedbackURL to your customers yourself after creating the invitation record with sendInvitationFromYext = FALSE.
Redirect Invitations to a Custom Collection Page
By default, the Review Balancing URL routes recipients to Yext's standard Collection Page. To redirect first-party invitations to a custom Collection Page instead:
- Navigate to Reviews > Generation > Settings.
- Enable First Party Review Collection Page Override.
- Select a custom field to hold your custom URLs, or create one if you don't already have one.
- Populate that custom field for each entity you want to redirect.
After you complete these steps, the First Party Review Page field populates with the value from your custom field. The Review Balancing URL itself doesn't change; it still applies your balancing algorithm settings to decide which publisher to route to, and uses your custom URL when it routes to a first-party review.
Format Invitations with Templates
Invitation templates control how an invitation appears to the recipient. Yext supports both email and SMS templates, which you can customize from the platform. See Review Generation Templates for setup steps. If you don't specify a Template ID when creating an invitation, Yext uses your account's default template.
Comply with CAN-SPAM
The CAN-SPAM Act requires commercial emails to include the sender's physical postal address. To send invitations through Yext's email system, add a brand name and address in your Review Generation account settings. Yext includes this information in the footer of invitation emails automatically.
Update or Delete an Invitation
Use the Update endpoint to cancel an invitation that hasn't been sent yet, or to make other changes before delivery. Use the Delete endpoint to permanently remove an invitation record. Deleting an invitation doesn't affect the delivery status of an invitation that was already sent.
Test Your Integration
Test your integration against a non-production or Sandbox account before rolling it out. For automated tests, such as a nightly check that your data pipeline is sending invitations correctly, create a test invitation and then delete it using the Delete endpoint.