Review Invitations: List

Retrieves all review invitations for an account

path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

limit
integer <= 100
Default: 10

Number of results to return

offset
integer
Default: 0

Number of results to skip. Used to page through results. Cannot be used together with pageToken.

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

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Review Invitations: Create

Sends review invitations to one or more consumers.

Optional fields

  • templateId
  • transactionId

path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

Request Body schema: application/json
Array
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.

title
required
string

The title of the person from whom a review is being requested (e.g., Mr., Mrs., Miss, etc.).

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:

  • E.164 standard international format, with a leading "+"
  • National format, according to the country of the corresponding location
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 v parameter is before 20210728, please refer to image as the parameter name instead of includeImage.

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 en.

Supported languages:

  • en
  • de
  • fr
  • es
  • it
  • nl
  • ja
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 additionalUrlParameters parameter will only be respected with the inclusion of a v parameter of 20210728 or later.

sendInvitationFromYext
boolean

Defaults to true. If set to false, Yext will not fulfill the invitation and will simply return the created invitation object.

The sendInvitationFromYext parameter will only be respected with the inclusion of a v parameter of 20210728 or later.

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 reviewLabelNames parameter will only be respected with the inclusion of a v parameter of 20210728 or later.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": [
    ]
}

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 YYYYMMDD format.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

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 YYYYMMDD format.

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 v parameter is before 20210728, please refer to responded as the parameter name instead of reviewed.

firstName
string

The first name of the person from whom a review is being requested.

The firstName parameter will only be respected for v parameters of 20210728 or later.

lastName
string

The last name of the person from whom a review is being requested

The lastName parameter will only be respected for v parameters of 20210728 or later.

title
string

The title of the person from whom a review is being requested (e.g., Mr., Mrs., Miss, etc.)

The title parameter will only be respected for v parameters of 20210728 or later.

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:

  • E.164 standard international format, with a leading "+"
  • National format, according to the country of the corresponding location

The contact parameter will only be respected for v parameters of 20210728 or later.

transactionId
string

The ID of the transaction being reviewed in response to this invitation.

The transactionId parameter will only be respected for v parameters of 20210728 or later.

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 additionalURLParameters parameter will only be respected for v parameters of 20210728 or later.

status
string
Value: "CANCELED"

Cancel an existing review invitation with PENDING status by updating status to CANCELED Please note that if the invitation status is not PENDING, attempting to set the status to CANCELED will fail.

errorCode
string

The error code of the invitation if applicable. Required if errorReason is specified.

The errorCode parameter will only be respected for v parameters of 20210727 or earlier.

errorReason
string

The error reason text of the invitation if applicable. Required if errorCode is specified.

The errorReason parameter will only be respected for v parameters of 20210727 or earlier.

Responses

Request samples

Content type
application/json
{
  • "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

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

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 YYYYMMDD format.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "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 YYYYMMDD format.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

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 YYYYMMDD format.

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 v parameter is before 20200910, please refer to privacyPolicyOverride as the parameter name instead of privacyPolicy.

Responses

Request samples

Content type
application/json
{
  • "maxEmailsPerDay": 200,
  • "maxTextsPerMonth": 1,
  • "maxTextsPerDay": 1,
  • "maxContactsAllTime": 1,
  • "maxContactFrequency": 7,
  • "reviewQuarantineDays": 7,
  • "privacyPolicy": "string"
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}
Feedback