Back
Step 1: Review Invitations Overview
Introduction to Review Invitations
Using the Yext Management API, you can integrate with an external system to automatically create and send review invitations. These integrations would typically include some combination of “PUSH”, where the external system proactively notifies the business application when the trigger occurs, or “PULL”, where the application fetches the data periodically.
Some common “push” use cases for automating review invitations are:
- A business wants to send an invitation after their consumer receives a product
- The external system would notify the application when the delivery is complete
- A business wants to send an invitation after a consumer makes a purchase at a physical location
- The external system would notify the application when the transaction is completed
- A health system wants to send an invitation after a patient completes a visit
- The external system would notify the application when the appointment status is updated
Standard Flow for “Push” Integrations
“Pull” integrations would be more common when the external system does not have a mechanism for proactively notifying the application when some trigger has occurred. For example, the external system might not have webhook support (at least for the relevant trigger). In this case, the application might still be able to fetch the data via API, or the business may need some way to export the invitation data periodically and upload it to an FTP to be fetched.
Standard Flow for “Pull” Integrations
Endpoint Overview
There are four Review Invitations endpoints which will be relevant to programmatically manage invitation data through Yext.
| 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} |
Anatomy of an Invitation
An invitation consists of the following attributes. Please note that there are additional fields required in your API requests, but this set of fields encapsulates the core data which comprises an invitation. For a more complete breakdown of the requests, please refer to the API Documentation .
| Field | Description |
|---|---|
| Entity ID* | ID of the entity the review is being requested for |
| First Name* | The first name of the person from whom a review is being requested |
| Last Name* | The last name of the person from whom a review is being requested |
| Title | The title of the person from whom a review is being requested (e.g., Mr., Mrs., Miss, etc.) |
| Contact* | The email address or phone number of the person from whom a review is being requested. |
| Template ID | The template used to format the invitation. |
| Transaction ID | The ID of the transaction being reviewed in response to this invitation. |
| Review Label Names | The names of the Review Labels which will be attached to the resulting review. |
| Additional URL Parameters | A JSON object containing the key, value pairs for any additional URL parameters. These URL parameters will be appended to the Review Balancing URL. |
*denotes required field
When considering how to programmatically upload invitations to Yext, please ensure that your application will be able to provide all of the information listed above.
Invitation Templates
Invitation Templates are used to format the review invitation sent from Yext to your customer. We offer both Email & SMS templates, and users can customize these templates from the platform. Please see the Configure Review Generation Email Templates help article for more information.
Whenever a template is not specified when creating an invitation, the system will use the default template (specified in the account) to format the invitation.
Invitation Redirects
You may notice that all invitations link to a URL on the locationrater.com or leavefeedback.app domain. This URL is known as the Review Balancing URL (learn more here ), and it is used to redirect the end user to third-party review sites or your first-party collection page, depending on the distribution of publishers you set in the review balancing algorithm. The Review Balancing URL will handle passing all query parameters to your collection page URL in the redirect.
Populating your Collection Page URLs in Yext
If you would like the invitations to redirect to Custom Review Collection Pages for your first-party reviews, you simply need to populate the entity-specific collection page URLs on the relevant entities. You should populate the URL in the First Party Review Page field on the entity in the platform. You will then need to navigate to Reviews > Generation > Settings, enable the “First Party Review Collection Page Override” setting, and set it to this field. The system will handle redirecting based on the value in this field, instead of the standard Yext-built Review Collection page.
CAN-SPAM Compliance
The CAN-SPAM Act requires that all commercial emails contain the physical postal address where the sender is located. In order to send emails using the Yext Invitations system, a business will need to supply a Brand Name & Address in Review Generation Account Settings, which will be populated in the footer of any emails sent by the system.