Step 2: Building out a Review Invitations Integration

Creating an App

The first thing you’ll want to do is create a new app in the Developer Console and grant access to the Review Invitations API. In order to use the GET/LIST endpoints, only read access on this endpoint group is required. However, to Create, Update, or Delete invitations, write access is required. An API key will be generated for your app that you can use 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.

Creating Invitations

The standard request to the Review Invitations: Create endpoint will trigger the Yext Review Generation system to send an invitation to the specified contact with the provided information; depending on whether a phone number or email address is provided, the system will fulfill an SMS or Email to the contact, respectively.

The request to the Create endpoint will return the created Invitation object, which will include invitationUid, a UUID to identify the invitation. The invitation will also include a feedbackUrl field, which will contain the full URL which will be included in the invitation. This URL will have the invitationUid included as a query parameter, so that the page which the user is redirected to can pass this invitationUid in the subsequent request to create a review, allowing the system to attribute the review to the specific invitation.

review creation flow

Collecting Additional Attributes

The Invitations API also supports the ability to provide additional attributes, which can then be passed in the subsequent Review Creation. For example, the developer could include information about the channel with which the recipient transacted (online, in-store, etc) in the invitation creation request. There are two ways with which this information can be provided.

Review Labels

The first option is to pass the additional information in the reviewLabelNames field. When a review is created and the invitationUid is passed in the Review Creation request, the strings passed in this field will be appended to the review as Review Labels. Concretely, referencing the example above, if “in-store” was passed in the reviewLabelNames field to the Invitation Creation request, the resulting review would have an “in-store” label applied.

review label flow

Note: The In-Store Review Label is simply an example of a reviewLabelName which could be included in the Invitation request.

URL Paramters

A second, more advanced, flexible option is to pass additional attributes using the additionalURLParameters field, which takes a JSON object including key, value pairs which will be appended as query parameters to the Feedback URL. This option allows the Collection Page to grab the URL Parameters and apply them wherever they see fit; a developer could replicate the labels functionality described above by simply sending these attributes as labels in the Review Creation request, or send those attributes elsewhere, such as an external attribution system. For example, a business may want to also send information about the transaction channel to a different CRM to preserve greater visibility into Review Generation and Collection.

additional url attributes

Note: loyaltyId is simply an example of an additionalUrlParam which could be included

Fulfilling Invitations from an External System

Some businesses may have their own preferred email or SMS delivery workflows, and may prefer to use these systems to fulfill their invitations in place of Yext. In this case, we also provide the ability to create an Invitation record without having Yext handle the invitation fulfillment, by passing sendInvitationFromYext = FALSE in the request body.

In practice, this implementation is most clearly useful in two scenarios:

  • The business wants to maintain a source of truth in Yext of the invitations sent to their customers, despite the fact that Yext will not be fulfilling these invitations
  • The business only wants to collect reviews from users from which they have requested reviews. This scenario is most common if a business only wants reviews from verified customers. In order to support this use case, some additional configuration is required.

business fulfills invitation

Requiring an Invitation UID for Submission

If the collection page is publicly accessible via URL, any user who obtains the URL could leave a review. For many businesses, a public collection page is desirable; they may want to distribute this URL on their website, on receipts, etc.

However, some businesses may want to ensure that only users who have specifically received an invitation are able to leave a review via their Review Collection Page. To support this use case, there is a specific Account Setting called Require Invitations for First-Party Reviews; when this setting is enabled, all requests to create reviews (via Review Submission: Create endpoint) will require an invitationUid to be passed in order for the review to be created.

As referenced in the section above regarding Fulfilling Invitations from an External System, if a business wanted some level of verification in order for an end-user to write a review on the Collection Page, but still wanted to use their own invitation delivery mechanism, the business would want to enable the aforementioned setting, and send requests to create invitations with sendInvitationFromYext = FALSE, and then distribute the returned feedbackUrl when requesting a review from their customers.

Updating an Invitation

Businesses may also want a method to programmatically update an invitation. For example, if a developer wanted to build functionality such that a user action in an integrated system could cancel an invitation, this could be achieved through the Review Invitations: Update endpoint.

Deleting an Invitation

Similar to updating an existing invitation, the Review Invitations: Delete endpoint provides an interface to delete an existing invitation programmatically. As opposed to updating your invitation, which would primarily be used to cancel an invitation which has not yet been sent, deleting an invitation will actually delete the invitation record from Yext permanently. However, deleting an invitation will not affect the delivery status for any invitations which have already been sent.

Testing Your Invitation Integration

A crucial part of building a complex integration is testing; as will all Yext integrations, we encourage developers to test against a non-production (e.g., developer or sandbox) instance. However, if a business wants to build some automated testing, such as a nightly task to ensure the ETL to send invitation data to Yext is working properly, we would recommend simply creating the invitation and subsequently deleting it using the Invitations: Delete endpoint.