Review Invitations: List
Retrieves all review invitations for an account
path Parameters
| accountId required | string |
query Parameters
| v required | string A date in |
| limit | integer <= 100 Default: 10 Number of results to return |
| offset | integer <= 9900 Default: 0 Number of results to skip. Used to page through results.
Cannot be used together with If the |
| pageToken | string If a response to a previous request contained the The |
| locationIds | Array of strings When provided, only invitations for the requested locations will be returned. Example: loc123,loc456,loc789 |
| folderIds | Array of strings When provided, only invitations for locations in the given folders and their subfolders will be included in the results. |
| locationLabels | Array of strings When present, only invitations for locations with the provided labels will be returned. |
| templateIds | Array of strings When provided, only invitations using the provided templateIds will be returned. |
| status | string Enum: "ACCEPTED" "REJECTED" "PENDING" When provided, only invitations of the chosen status will be returned. |
| type | string Enum: "EMAIL" "SMS" When provided, only invitations of the selected type will be returned. |
Responses
Response samples
- 200
- default
{- "meta": {
- "uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
}, - "response": {
- "countEmail": 0,
- "countSMS": 0,
- "sent": 0,
- "opened": 0,
- "clicked": 0,
- "responded": 0,
- "invitations": [
- {
- "invitationUid": "string",
- "entity": {
- "id": "string"
}, - "firstName": "string",
- "lastName": "string",
- "title": "string",
- "contact": "string",
- "includeImage": true,
- "templateId": "string",
- "transactionId": "string",
- "status": "ACCEPTED",
- "details": "string",
- "language": "string",
- "additionalURLParameters": "string",
- "sendInvitationFromYext": true,
- "feedbackURL": "string",
- "reviewLabels": [
- { }
], - "partnerId": "string",
- "type": "EMAIL",
- "requested": 0,
- "sent": 0,
- "opened": 0,
- "clicked": 0,
- "reviewed": 0,
- "reviewId": "string"
}
]
}
}Review Invitations: Create
Sends review invitations to one or more consumers.
Optional fields
templateIdtransactionId
path Parameters
| accountId required | string |
query Parameters
| v required | string A date in |
Request Body schema: application/json
required | object |
| firstName required | string The first name of the person from whom a review is being requested. |
| lastName required | string The last name of the person from whom a review is being requested. |
| contact required | string The email address or phone number of the person from whom a review is being requested. Phone numbers should be formatted in one of the following ways:
|
| title | string The title of the person from whom a review is being requested (e.g., Mr., Mrs., Miss, etc.). |
| includeImage | boolean Only valid for SMS invitations. If set to true, include the image provided in the relevant template in the SMS invitation. Please note that an image counts as an SMS message towards your SMS capacity. Otherwise, the SMS message will not include an image. If the |
| templateId | string If specified, the ID of the template used to format the email. If not specified, the entity’s default email template is used. If the entity has no default template, the account’s default template is used. |
| transactionId | string The ID of the transaction being reviewed in response to this invitation. |
| language | string The ISO 639-1 code of the review invitation's language. Only valid for invitations created
from built-in templates. Defaults to Supported languages:
|
| additionalURLParameters | string A JSON object containing the key, value pairs for any additional URL parameters. These URL parameters will be appended to the First-Party Review Collection URL. The |
| sendInvitationFromYext | boolean Defaults to true. If set to false, Yext will not fulfill the invitation and will simply return the created invitation object. The |
| reviewLabelNames | Array of strings The names of the Review Labels which will be attached to the resulting review. This is an upsert operation, meaning the system will determine if a Review Label exists already in your account, and create and append a new label if not. The |
Responses
Request samples
- Payload
[- {
- "entity": {
- "id": "string"
}, - "firstName": "string",
- "lastName": "string",
- "contact": "string",
- "title": "string",
- "includeImage": true,
- "templateId": "string",
- "transactionId": "string",
- "language": "string",
- "additionalURLParameters": "string",
- "sendInvitationFromYext": true,
- "reviewLabelNames": [
- "string"
]
}
]Response samples
- 201
- default
{- "meta": {
- "uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
}, - "response": [
- {
- "invitationUid": "string",
- "entity": {
- "id": "string"
}, - "firstName": "string",
- "lastName": "string",
- "title": "string",
- "contact": "string",
- "includeImage": true,
- "templateId": "string",
- "transactionId": "string",
- "status": "ACCEPTED",
- "details": "string",
- "language": "string",
- "additionalURLParameters": "string",
- "sendInvitationFromYext": true,
- "feedbackURL": "string",
- "reviewLabels": [
- { }
]
}
]
}Review Invitation: Get
Retrieve a specific review invitation.
path Parameters
| accountId required | string |
| invitationUid required | string The UID of this Review Invitation. This UID can be included as part of Review Creation requests for attribution. |
query Parameters
| v required | string A date in |
Responses
Response samples
- 200
- default
{- "meta": {
- "uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
}, - "response": {
- "invitationUid": "string",
- "entity": {
- "id": "string"
}, - "firstName": "string",
- "lastName": "string",
- "title": "string",
- "contact": "string",
- "includeImage": true,
- "templateId": "string",
- "transactionId": "string",
- "status": "ACCEPTED",
- "details": "string",
- "language": "string",
- "additionalURLParameters": "string",
- "sendInvitationFromYext": true,
- "feedbackURL": "string",
- "reviewLabels": [
- { }
], - "partnerId": "string",
- "type": "EMAIL",
- "requested": 0,
- "sent": 0,
- "opened": 0,
- "clicked": 0,
- "reviewed": 0,
- "reviewId": "string"
}
}Review Invitation: Update
Supports updating an existing review invitation. This endpoint will not create a new review invitation or trigger a new SMS/Email to be sent, it will only update the data and/or metadata for an existing review invitation. Any optional parameters which are excluded from the request will simply be ignored.
path Parameters
| accountId required | string |
| invitationUid required | string The UID of this Review Invitation. This UID can be included as part of Review Creation requests for attribution. |
query Parameters
| v required | string A date in |
Request Body schema: application/json
| sent | integer <int64> The timestamp the invitation was sent (seconds since epoch), if the invitation was sent. |
| opened | integer <int64> The timestamp the invitation was opened (seconds since epoch), if the invitation was opened. This value will always be null for SMS type invitations. |
| clicked | integer <int64> The timestamp the invitation was clicked (seconds since epoch). |
| reviewed | integer <int64> The timestamp the review was generated as a result of this invitation (seconds since epoch). If the |
| firstName | string The first name of the person from whom a review is being requested. The |
| lastName | string The last name of the person from whom a review is being requested The |
| title | string The title of the person from whom a review is being requested (e.g., Mr., Mrs., Miss, etc.) The |
| contact | string The email address or phone number of the person from whom a review is being requested. Phone numbers should be formatted in one of the following ways:
The |
| transactionId | string The ID of the transaction being reviewed in response to this invitation. The |
| additionalURLParameters | string A JSON object containing the key, value pairs for any additional URL parameters. These URL parameters will be appended to the First-Party Review Collection URL. The |
| status | string Value: "CANCELED" Cancel an existing review invitation with |
| errorCode | string The error code of the invitation if applicable. Required if The |
| errorReason | string The error reason text of the invitation if applicable. Required if The |
Responses
Request samples
- Payload
{- "sent": 0,
- "opened": 0,
- "clicked": 0,
- "reviewed": 0,
- "firstName": "string",
- "lastName": "string",
- "title": "string",
- "contact": "string",
- "transactionId": "string",
- "additionalURLParameters": "string",
- "status": "CANCELED",
- "errorCode": "string",
- "errorReason": "string"
}Response samples
- 200
- default
{- "meta": {
- "uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
}, - "response": {
- "invitationUid": "string",
- "entity": {
- "id": "string"
}, - "firstName": "string",
- "lastName": "string",
- "title": "string",
- "contact": "string",
- "transactionId": "string",
- "additionalURLParameters": "string",
- "status": "SENT",
- "errorCode": "string",
- "errorReason": "string",
- "sent": 0,
- "opened": 0,
- "clicked": 0,
- "reviewed": 0
}
}Review Invitation: Delete
Delete a specific review invitation.
path Parameters
| accountId required | string |
| invitationUid required | string The UID of this Review Invitation. This UID can be included as part of Review Creation requests for attribution. |
query Parameters
| v required | string A date in |
Responses
Response samples
- 200
- default
{- "meta": {
- "uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
}, - "response": { }
}Review Generation Settings: Get
Returns all current generation settings for a specified account.
path Parameters
| accountId required | string |
query Parameters
| v required | string A date in |
Responses
Response samples
- 200
- default
{- "meta": {
- "uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
}, - "response": {
- "maxEmailsPerDay": 200,
- "maxTextsPerMonth": 1,
- "maxTextsPerDay": 1,
- "maxContactsAllTime": 1,
- "maxContactFrequency": 7,
- "reviewQuarantineDays": 7,
- "privacyPolicy": "string",
- "balancingOptimization": "DISTRIBUTION",
- "algorithmConfiguration": [
- "WEBSITE"
], - "siteDistribution": {
- "FACEBOOK": 3,
- "GOOGLEMYBUSINESS": 5,
- "FIRSTPARTY": 1
}
}
}Review Generation Settings: Update
Updates any generation settings specified in a specified account. Call may include any/all settings available to the account. Settings not included will remain unchanged.
path Parameters
| accountId required | string |
query Parameters
| v required | string A date in |
Request Body schema: application/json
| maxEmailsPerDay | integer [ 0 .. 200 ] Enables review invitations by email and indicates the maximum number of email invites our system will send on a per-location, per-day basis. Must contain an integer value between 0 and 200. If 0 or null, review invitations by email will be disabled. |
| maxTextsPerMonth | integer >= 1 Indicates the maximum number of text invites our system will send on a per-location, per-month basis. |
| maxTextsPerDay | integer [ 1 .. 20 ] Enables review invitations by text and indicates the maximum number of text invites our system will send on a per-location, per-day basis. We will send a maximum of 20 text invites per location per day. If null, review invitations by text will be disabled. |
| maxContactsAllTime | integer Value: 1 When enabled, this setting will prevent you from contacting the same person more than once. This setting cannot be set when maxContactFrequency is enabled. If null, this setting will be disabled. |
| maxContactFrequency | integer Enum: 7 30 60 90 Indicates the minimum number of days that must pass before a given contact can be sent another review invitation. This setting will prevent you from contacting the same person repeatedly in a short time period. If null, no maximum contact frequency will be enforced. |
| reviewQuarantineDays | integer [ 0 .. 7 ] Prevents first-party reviews from immediately showing up on your website or wherever else you show your reviews. During this quarantine period, you may respond to reviews, increasing the likelihood that your customers will revise or remove their negative reviews. |
| privacyPolicy | string Review-collection pages contain a link to the Yext privacy policy by default. This field lets you replace that link with a link to your own privacy policy. Update request must contain a URL or null. If null, the Yext privacy policy link will be used. If the |
| balancingOptimization | string Enum: "DISTRIBUTION" "MORE_REVIEWS" "MUST_BE_LOGGED_IN" Defaults to |
| algorithmConfiguration | Array of strings[ items <= 3 items unique ] Items Enum: "WEBSITE" "RECENCY" "RATING" Optionally prioritize the following issues to determine where to send review invites: |
object >= 0 properties Configure the target distribution of reviews for each site by specifying the ratio as an integer for each site to generate reviews for. E.g.
|
Responses
Request samples
- Payload
{- "maxEmailsPerDay": 200,
- "maxTextsPerMonth": 1,
- "maxTextsPerDay": 1,
- "maxContactsAllTime": 1,
- "maxContactFrequency": 7,
- "reviewQuarantineDays": 7,
- "privacyPolicy": "string",
- "balancingOptimization": "DISTRIBUTION",
- "algorithmConfiguration": [
- "WEBSITE"
], - "siteDistribution": {
- "FACEBOOK": 3,
- "GOOGLEMYBUSINESS": 5,
- "FIRSTPARTY": 1
}
}Response samples
- 200
- default
{- "meta": {
- "uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
}, - "response": {
- "maxEmailsPerDay": 200,
- "maxTextsPerMonth": 1,
- "maxTextsPerDay": 1,
- "maxContactsAllTime": 1,
- "maxContactFrequency": 7,
- "reviewQuarantineDays": 7,
- "privacyPolicy": "string",
- "balancingOptimization": "DISTRIBUTION",
- "algorithmConfiguration": [
- "WEBSITE"
], - "siteDistribution": {
- "FACEBOOK": 3,
- "GOOGLEMYBUSINESS": 5,
- "FIRSTPARTY": 1
}
}
}