openapi: 3.0.0 info: title: Yext Admin Account Settings Reviews API version: '2.0' servers: - url: https://api.yextapis.com/v2 security: - api_key: [] - api-key: [] tags: - name: Reviews paths: /accounts/{accountId}/reviews: parameters: - $ref: '#/components/parameters/accountId' get: operationId: listReviews summary: 'Reviews: List' tags: - Reviews description: 'Retrieve all Reviews matching the given criteria. **NOTE:** Not all publishers'' reviews will be included in the response. For more details, please contact your Account Manager. ' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' - name: limit in: query schema: type: integer default: 10 maximum: 100 description: Number of results to return. - name: offset in: query required: false schema: type: integer default: 0 maximum: 9900 description: ' Number of results to skip. Used to page through results. Cannot be used together with **`pageToken`**. If the **`v`** parameter is before `20211115`, the maximum offset is not enforced. However, users are still encouraged to migrate to **`pageToken`** for queries requiring large offsets, as these may result in errors. ' - name: entityIds in: query schema: type: array items: type: string description: 'When provided, only reviews for the requested entities will be returned. Before 12/13/21, the parameter name was **`locationIds`**. Specifying either **`locationsIds`** or **`entityIds`** as the parameter name will have the same result. By default, reviews will be returned for all entities subscribed to Review Monitoring. **Example:** entity123,entity456,entity789 ' style: simple - name: apiIdentifiers in: query schema: type: array items: type: string description: 'When provided, only reviews for the requested API identifiers will be returned. ' style: simple - name: folderId in: query schema: type: string description: When provided, only reviews for locations in the given folder and its subfolders will be included in the results. - name: countries in: query schema: type: array items: type: string description: When present, only reviews for locations in the given countries will be returned. Countries are denoted by ISO 3166 2-letter country codes. - name: locationLabels in: query schema: type: array items: type: string description: When present, only reviews for locations with the provided labels will be returned. - $ref: '#/components/parameters/listingsPublisherIds' - name: reviewContent in: query schema: type: string description: When specified, only reviews that include the provided content will be returned. - name: minRating in: query schema: type: number format: double description: When specified, only reviews with the provided minimum rating or higher will be returned. - name: maxRating in: query schema: type: number format: double description: When specified, only reviews with the provided maximum rating or lower will be returned. - name: minPublisherDate in: query schema: type: string format: date description: '(`YYYY-MM-DD` format) When specified, only reviews with a publisher date on or after the given date will be returned. If the **`v`** parameter is before `20170617`: returns reviews with a publisher date on or after the given date in **EST** If the **`v`** parameter is `20170617` or later: returns reviews with a publisher date on or after the given date in **UTC** ' - name: maxPublisherDate in: query schema: type: string format: date description: '(`YYYY-MM-DD` format) When specified, only reviews with a publisher date on or before the given date will be returned. If the **`v`** parameter is before `20170617`: returns reviews with a publisher date on or before the given date in **EST** If the **`v`** parameter is `20170617` or later: returns reviews with a publisher date on or before the given date in **UTC** ' - name: minLastYextUpdateDate in: query schema: type: string format: date description: '(`YYYY-MM-DD` format) When specified, only reviews with a last Yext update date on or after the given date will be returned. If the **`v`** parameter is before `20170617`: returns revies with a last Yext update date on or after the given date in **EST** If the **`v`** parameter is `20170617` or later: returns revies with a last Yext update date on or after the given date in **UTC** ' - name: maxLastYextUpdateDate in: query schema: type: string format: date description: '(`YYYY-MM-DD` format) When specified, only reviews with a last Yext update date on or before the given date will be returned. If the **`v`** parameter is before `20170617`: returns reviews with a last Yext update date on or before the given date in **EST** If the **`v`** parameter is `20170617` or later: returns reviews with a last Yext update date on or before the given date in **UTC** ' - name: awaitingResponse in: query schema: type: string enum: - REVIEW - COMMENT - REVIEW_OR_COMMENT description: 'When specified, only reviews that are awaiting an owner reply on the given objects will be returned. For example, when `awaitingResponse=COMMENT`, reviews will only be returned if they have at least one comment that has not been responded to by the owner. ' - name: minNonOwnerComments in: query schema: type: integer description: When specified, only reviews that have at least the provided number of non-owner comments will be returned. - name: reviewerName in: query schema: type: string description: When specified, only reviews whose authorName contains the provided string will be returned. - name: status in: query schema: type: string enum: - LIVE - QUARANTINED - REMOVED description: 'When specified, only reviews with the given **`status`** values will be returned. The **`status`** parameter will only be respected with the inclusion of a **`v`** parameter of `20170830` or later. ' - name: pageToken in: query schema: type: string description: 'If a response to a previous request contained the **`nextPageToken`** field, pass that field''s value as the **`pageToken`** parameter to retrieve the next page of data. The **`pageToken`** parameter will only be respected with the inclusion of a **`v`** parameter of `20170901` or later. ' - name: reviewLanguage in: query schema: type: string description: 'When provided, only reviews in the given languages will be included in the results. Languages must be specified by their ISO 639-1 codes. If specifying multiple languages, enter the language codes as a comma-separated list. **Example:** ''en,fr,zh'' ' - name: labelIds in: query schema: type: array items: type: string description: When present, only reviews with the provided review label IDs will be returned. - name: reviewType in: query schema: type: string enum: - Rating - Recommendation description: 'When specified, only reviews that are of the given **`reviewType`** will be returned. Only applicable to Facebook reviews. The **`reviewType`** parameter will only be respected with the inclusion of a **`v`** parameter of `20181002` or later. ' - name: recommendation in: query schema: type: string enum: - Recommended - Not Recommended description: 'When specified, only reviews with the given **`recommendation`** value will be returned. Only applicable to Facebook reviews. The **`recommendation`** parameter will only be respected with the inclusion of a **`v`** parameter of `20181002` or later. ' - name: flagStatus in: query schema: type: string enum: - FLAGGED - NOT_FLAGGED description: 'When specified, only reviews with the given **`flagStatus`** value will be returned. **`flagStatus`** indicates whether the review has been flagged for inappropriate or irrelevant content. For review publishing, Yext recommends filtering to reviews with `flagStatus = NOT_FLAGGED`, as flagged reviews are being examined for inappropriate or irrelevant content. Note that only First Party and External First Party reviews can be flagged. ' - name: isYextResponseEligible in: query schema: type: boolean description: 'When specified, used to filter reviews based on whether they are eligible for response through Yext (based on their publisher and, for first party reviews, anonymization status). If set to `true`, only such reviews will be included in the response, and if set to `false` such reviews will be excluded in the response. Default (unset) means reviews will be included regardless of their eligibility for response through Yext. Note that this parameter does NOT filter reviews based on whether they already have a response; to do that use the **`awaitingResponse`** parameter. ' responses: '200': $ref: '#/components/responses/ReviewsResponse' default: $ref: '#/components/responses/ErrorResponse' post: operationId: createReview tags: - Reviews requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateReview' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' summary: 'Reviews: Create' description: 'Create a new External First Party Review. ' responses: '201': $ref: '#/components/responses/IdResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{accountId}/reviews/{reviewId}: parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/reviewId' get: operationId: getReview summary: 'Review: Get' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' - $ref: '#/components/parameters/reviewId' tags: - Reviews description: Retrieve a specific Review. responses: '200': $ref: '#/components/responses/ReviewResponse' default: $ref: '#/components/responses/ErrorResponse' put: requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateReview' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' - $ref: '#/components/parameters/reviewId' operationId: updateReview tags: - Reviews summary: 'Review: Update' description: 'Updates an External First Party Review or a First Party Review.

**NOTE:** Despite using the `PUT` method, Reviews: Update only updates supplied fields. Omitted fields are not modified.

' responses: '200': $ref: '#/components/responses/IdResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{accountId}/reviews/{reviewId}/comments: parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/reviewId' post: operationId: createComment summary: 'Comment: Create' tags: - Reviews description: "Creates a new Comment on a Review.\n\n**NOTE:** When the **Compliant Review Response** setting is enabled for your account and you are providing an `attestation`, you must include your Yext user ID in the **`Yext-User-Id`** header. The comment will be processed asynchronously for compliance review, and a **202 Accepted** response will be returned.\n

\n ## Required fields\n* **`content`**\n

\n ## Optional fields\n* **`parentId`**\n* **`visibility`**\n* **`date`**\n* **`suppressReviewerContact`**\n* **`attestation`** (only required when Compliant Review Response is enabled)\n

\n ## Response Behavior\n* When `attestation` is provided (Compliant Review Response enabled): Returns **202 Accepted** - comment will be published after compliance review\n* When `attestation` is not provided (Compliant Review Response disabled): Returns **201 Created** with comment ID, or **202 Accepted** if asynchronous processing is needed\n

\n" requestBody: $ref: '#/components/requestBodies/commentRequest' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' - $ref: '#/components/parameters/reviewId' responses: '201': $ref: '#/components/responses/CreateReviewCommentResponse' '202': $ref: '#/components/responses/ReviewCommentTimeoutResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{accountId}/reviews/{reviewId}/generateComment: parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/reviewId' post: operationId: generateComment summary: 'Comment: Generate' tags: - Reviews description: 'Gets a content generated response for a particular review ' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' - $ref: '#/components/parameters/reviewId' responses: '200': $ref: '#/components/responses/GenerateReviewCommentResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{accountId}/reviews/{reviewId}/comments/{commentId}: parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/reviewId' - $ref: '#/components/parameters/commentId' put: operationId: updateComment summary: 'Comment: Update' tags: - Reviews description: "Updates a Comment on a Review.\n

\n ## Optional fields\n* **`content`**\n* **`visibility`**\n

\n" requestBody: $ref: '#/components/requestBodies/commentUpdateRequest' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' - $ref: '#/components/parameters/reviewId' - $ref: '#/components/parameters/commentId' responses: '200': $ref: '#/components/responses/EmptyResponse' '202': $ref: '#/components/responses/ReviewCommentTimeoutResponse' default: $ref: '#/components/responses/ErrorResponse' delete: operationId: deleteComment summary: 'Comment: Delete' tags: - Reviews description: 'Deletes a Comment on a Review.

' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' - $ref: '#/components/parameters/reviewId' - $ref: '#/components/parameters/commentId' responses: '200': $ref: '#/components/responses/EmptyResponse' '202': $ref: '#/components/responses/ReviewCommentTimeoutResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{accountId}/reviewinvites: parameters: - $ref: '#/components/parameters/accountId' get: operationId: listReviewInvitations summary: 'Review Invitations: List' tags: - Reviews description: Retrieves all review invitations for an account parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' - name: limit in: query schema: type: integer default: 10 maximum: 100 description: Number of results to return - name: offset in: query required: false schema: type: integer default: 0 maximum: 9900 description: ' Number of results to skip. Used to page through results. Cannot be used together with **`pageToken`**. If the **`v`** parameter is before `20240626`, the maximum offset is not enforced. However, users are still encouraged to migrate to **`pageToken`** for queries requiring large offsets, as these may result in errors. ' - name: pageToken in: query schema: type: string description: 'If a response to a previous request contained the **`nextPageToken`** field, pass that field''s value as the **`pageToken`** parameter to retrieve the next page of data. The **`pageToken`** parameter will only be respected with the inclusion of a **`v`** parameter of `20240626` or later. ' - name: locationIds in: query schema: type: array items: type: string description: 'When provided, only invitations for the requested locations will be returned. **Example:** loc123,loc456,loc789 ' style: simple - name: folderIds in: query schema: type: array items: type: string description: 'When provided, only invitations for locations in the given folders and their subfolders will be included in the results. ' - name: locationLabels in: query schema: type: array items: type: string description: 'When present, only invitations for locations with the provided labels will be returned. ' - name: templateIds in: query schema: type: array items: type: string description: When provided, only invitations using the provided templateIds will be returned. - name: status in: query schema: type: string enum: - ACCEPTED - REJECTED - PENDING description: When provided, only invitations of the chosen status will be returned. - name: type in: query schema: type: string enum: - EMAIL - SMS description: When provided, only invitations of the selected type will be returned. responses: '200': $ref: '#/components/responses/ReviewInvitationsResponse' default: $ref: '#/components/responses/ErrorResponse' post: operationId: createReviewInvites tags: - Reviews summary: 'Review Invitations: Create' description: "Sends review invitations to one or more consumers.\n

\n ## Optional fields\n* **`templateId`**\n* **`transactionId`**\n

\n" requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/CreateReviewInvitationRequest' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' responses: '201': $ref: '#/components/responses/CreateReviewInvitationsResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{accountId}/reviewinvites/{invitationUid}: parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/invitationId' - $ref: '#/components/parameters/v' get: operationId: getReviewInvitation summary: 'Review Invitation: Get' tags: - Reviews description: Retrieve a specific review invitation. responses: '200': $ref: '#/components/responses/ReviewInvitationResponse' default: $ref: '#/components/responses/ErrorResponse' put: requestBody: $ref: '#/components/requestBodies/updateReviewInvitationRequest' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' - $ref: '#/components/parameters/invitationId' operationId: updateReviewInvitation summary: 'Review Invitation: Update' tags: - Reviews description: '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. ' responses: '200': $ref: '#/components/responses/UpdateReviewInvitationResponse' default: $ref: '#/components/responses/ErrorResponse' delete: operationId: deleteInvitation summary: 'Review Invitation: Delete' tags: - Reviews description: Delete a specific review invitation. responses: '200': $ref: '#/components/responses/EmptyResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{accountId}/reviews/{reviewId}/labels: parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/reviewId' put: operationId: updateReviewLabels summary: 'Review Labels: Update' tags: - Reviews description: Assigns the specified review labels to the specified review, replacing existing labels on the review. requestBody: $ref: '#/components/requestBodies/updateReviewLabelsRequest' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' - $ref: '#/components/parameters/reviewId' responses: '200': $ref: '#/components/responses/UpdateReviewLabelsResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{accountId}/reviews/settings/generation: parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' get: operationId: getReviewGenerationSettings tags: - Reviews summary: 'Review Generation Settings: Get' description: Returns all current generation settings for a specified account. responses: '200': $ref: '#/components/responses/ReviewGenerationSettingsResponse' default: $ref: '#/components/responses/ErrorResponse' post: operationId: updateReviewGenerationSettings tags: - Reviews summary: 'Review Generation Settings: Update' description: '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. ' requestBody: $ref: '#/components/requestBodies/reviewGenerationSettingsRequest' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' responses: '200': $ref: '#/components/responses/UpdateReviewGenerationSettingsResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{accountId}/workflowRules: parameters: - $ref: '#/components/parameters/accountId' get: operationId: listReviewWorkflowRules summary: 'Review Workflow Rules: List' tags: - Reviews parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' - name: pageSize in: query schema: type: integer default: 25 maximum: 25 description: The maximum number of workflow rules to return. Defaults to 25. - name: pageToken in: query schema: type: string description: 'If a response to a previous request contained the **`nextPageToken`** field, pass that field''s value as the **`pageToken`** parameter to retrieve the next page of data. ' - name: filter in: query schema: type: string description: 'CEL expression used to filter workflow rules. Filters can only be applied to **`assignee`**, **`type`**, and **`enabled`**. ' description: 'Retrieve the Review Workflow Rules configured for the account. ' responses: '200': $ref: '#/components/responses/workflowRulesResponse' default: $ref: '#/components/responses/ErrorResponse' post: operationId: createReviewWorkflowRule summary: 'Review Workflow Rules: Create' tags: - Reviews parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWorkflowRule' description: 'Creates a Review Workflow Rule. ' responses: '200': $ref: '#/components/responses/workflowRuleResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{accountId}/workflowRules/{workflowRuleId}: parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/workflowRuleId' - $ref: '#/components/parameters/v' get: operationId: getReviewWorkflowRule summary: 'Review Workflow Rules: Get' tags: - Reviews description: Retrieve a specific Review Workflow Rule. responses: '200': $ref: '#/components/responses/workflowRuleResponse' default: $ref: '#/components/responses/ErrorResponse' patch: operationId: updateReviewWorkflowRule summary: 'Review Workflow Rules: Update' tags: - Reviews parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/v' - $ref: '#/components/parameters/workflowRuleId' - name: updateMask in: query required: true schema: type: string description: 'Comma-separated list of fields to update on the workflow rule. Supported values: `assignee`, `assignee_user_group`, `display_name`, `enabled`, `domain_configuration`, `rule_type`, `due_date` Example: `display_name,enabled` ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateWorkflowRule' description: 'Updates a single Review Workflow Rule. **NOTE:** Review Workflow Rules: Update only updates supplied fields. Omitted fields are not modified. ' responses: '200': $ref: '#/components/responses/workflowRuleResponse' default: $ref: '#/components/responses/ErrorResponse' delete: operationId: deleteReviewWorkflowRule summary: 'Review Workflow Rules: Delete' tags: - Reviews description: Deletes a Review Workflow Rule. responses: '200': $ref: '#/components/responses/EmptyResponse' default: $ref: '#/components/responses/ErrorResponse' /listings/reviews: parameters: - $ref: '#/components/parameters/listingId' - $ref: '#/components/parameters/num' - $ref: '#/components/parameters/before' get: operationId: getReviewList tags: - Reviews summary: Review List description: "Yext uses REVIEWS to retrieve review data for business owners. You should provide access to all organic reviews displayed on your properties (i.e., no third-party reviews).\n\n## **Requirements**\nWhen Yext customers sign in to their Listings dashboard, Yext shows them all their reviews from across the Yext Knowledge Network. In order to support this, we have the following requirements for any publisher that supports customer reviews on their listings.\n\n* Publisher must provide access to all review data.\n* Publisher’s system must notify Yext when new reviews are added, updated, or deleted from Yext-powered listings.\n* Publisher must provide a direct link to each individual review.\n* If the publisher allows users to respond to reviews, the publisher must allow Yext to do so (on behalf of the business owner).\n* If the publisher allows users to flag reviews as abuse, the publisher must allow Yext to do so (on behalf of the business owner). \n" responses: '200': $ref: '#/components/responses/GetReviewsSuccess' '400': $ref: '#/components/responses/ErrorResponseNew' '404': $ref: '#/components/responses/404NotFoundResponse' '500': $ref: '#/components/responses/ServerError' /listings/reviews/{reviewId}: parameters: - $ref: '#/components/parameters/reviewId' get: operationId: getReview tags: - Reviews summary: Get Review description: 'Get the review object for a specific review ID. ' responses: '200': $ref: '#/components/responses/GetSingleReviewSuccess' '400': $ref: '#/components/responses/ErrorResponseNew' '404': $ref: '#/components/responses/404NotFoundResponse' '500': $ref: '#/components/responses/ServerError' post: operationId: reviewRespond tags: - Reviews requestBody: content: application/json: schema: $ref: '#/components/schemas/PartnerReviewResponse' summary: Create Comment description: "Yext uses RESPOND to allow business owners to interact with reviews left by consumers.\nThe endpoint supports review response by a business owner and the capability to flag reviews for inappropriate content. You should support any capabilities you already have on your site.\n\n# **Requirements**\n Yext's customers would like to be able to manage all their reviews from one platform. To that end, they should be able to use the Yext platform to take advantage of the review-management features you have on your site.\n## Specifically:\n* Publishers who support review response from business owners must provide that capability via this endpoint.\n* Publishers who support flagging reviews for inappropriate content must provide that capability via this endpoint.\n" responses: '200': $ref: '#/components/responses/NewCommentSuccess' '400': $ref: '#/components/responses/ErrorResponseNew' '404': $ref: '#/components/responses/404NotFoundResponse' '500': $ref: '#/components/responses/ServerError' /listings/reviews/{reviewId}/comment/{commentId}: parameters: - $ref: '#/components/parameters/reviewId' - $ref: '#/components/parameters/commentId_2' put: requestBody: content: application/json: schema: $ref: '#/components/schemas/PartnerReviewResponseUpdate' operationId: updateReviewComment tags: - Reviews summary: Update Comment description: 'Yext uses the PUT operation to update a review comment from the business owner on a specific review. ' responses: '200': $ref: '#/components/responses/EmptyResponseNew' '400': $ref: '#/components/responses/ErrorResponseNew' '404': $ref: '#/components/responses/404NotFoundResponse' '500': $ref: '#/components/responses/ServerError' delete: operationId: deleteReviewComment tags: - Reviews summary: Delete Comment description: 'Yext uses the DELETE operation to remove a review comment from the business owner on a specific review. ' responses: '200': $ref: '#/components/responses/EmptyResponseNew' '400': $ref: '#/components/responses/ErrorResponseNew' '404': $ref: '#/components/responses/404NotFoundResponse' '500': $ref: '#/components/responses/ServerError' components: responses: 404NotFoundResponse: description: Not Found content: application/json: schema: title: 404NotFoundResponse type: object properties: error: properties: message: type: string description: Not Found example: Not Found ReviewInvitationsResponse: description: Review Invitations Response content: application/json: schema: title: ReviewInvitationsResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: type: object properties: countEmail: type: integer description: Total number of Email Invitations that meet filter criteria (ignores limit/offset) countSMS: type: integer description: Total number of SMS Invitations that meet filter criteria (ignores limit/offset) sent: type: integer description: Total number of Invitations that had a sent time opened: type: integer description: Total number of Invitations that had an open time clicked: type: integer description: Total number of Invitations that had a clicked time responded: type: integer description: Total number of Invitations that had a responded time invitations: type: array items: $ref: '#/components/schemas/GetReviewInvitation' GetReviewsSuccess: description: OK content: application/json: schema: title: GetReviewsSuccess $ref: '#/components/schemas/PartnerReviewList' ReviewInvitationResponse: description: Review Invitation Response content: application/json: schema: title: ReviewInvitationResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: $ref: '#/components/schemas/GetReviewInvitation' workflowRulesResponse: description: Workflow Rules Response content: application/json: schema: title: WorkflowRulesResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: type: object properties: workflowRules: type: array items: $ref: '#/components/schemas/WorkflowRule' nextPageToken: $ref: '#/components/schemas/NextPageToken' workflowRuleResponse: description: Workflow Rule Response content: application/json: schema: title: WorkflowRuleResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: $ref: '#/components/schemas/WorkflowRule' CreateReviewCommentResponse: description: Create Review Comment Response content: application/json: schema: title: CreateReviewCommentResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: type: object properties: id: type: integer description: 'If the **`v`** parameter is before `20210616`, **`id`** will be returned as a type string instead of an integer. ' ServerError: description: Server Error content: application/json: schema: title: ServerError type: object properties: error: $ref: '#/components/schemas/ResponseErrorNew' EmptyResponseNew: description: OK UpdateReviewGenerationSettingsResponse: description: Update Review Generation Settings Response content: application/json: schema: title: UpdateReviewGenerationSettingsResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: $ref: '#/components/schemas/ReviewGenerationSettings' CreateReviewInvitationsResponse: description: Create Review Invitations Response content: application/json: schema: title: CreateReviewInvitationsResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: type: array items: allOf: - $ref: '#/components/schemas/ReviewInvitationOptional' ReviewResponse: description: Review Response content: application/json: schema: title: ReviewResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: $ref: '#/components/schemas/Review' IdResponse: description: ID Response. content: application/json: schema: title: IdResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: type: object properties: id: type: string UpdateReviewLabelsResponse: description: Review Labels Update Response content: application/json: schema: title: UpdateReviewLabelsResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: type: object properties: id: type: integer description: The review id. labelIds: type: array items: type: integer description: The label ids assigned to the review. EmptyResponse: description: Empty Response. content: application/json: schema: title: EmptyResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: type: object UpdateReviewInvitationResponse: description: Update Review Invitation Response content: application/json: schema: title: UpdateReviewInvitationResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: $ref: '#/components/schemas/UpdatedReviewInvitation' GenerateReviewCommentResponse: description: Generate Review Comment Response content: application/json: schema: title: GenerateReviewCommentResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: type: object properties: content: type: string ReviewGenerationSettingsResponse: description: Review Generation Settings Response content: application/json: schema: title: ReviewGenerationSettingsResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: $ref: '#/components/schemas/ReviewGenerationSettings' GetSingleReviewSuccess: description: OK content: application/json: schema: title: GetSingleReviewSuccess type: object $ref: '#/components/schemas/PartnerReview' NewCommentSuccess: description: OK content: application/json: schema: title: NewCommentSuccess type: object properties: commentId: type: string description: The ID of the comment that was successfully created example: f3j94g8h3 ErrorResponse: description: Error Response content: application/json: schema: title: ErrorResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMetaWithError' response: type: object ReviewCommentTimeoutResponse: description: Review Comment Timeout Response content: application/json: schema: title: ReviewCommentTimeoutResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: type: object ErrorResponseNew: description: Bad Request content: application/json: schema: title: ErrorResponseNew type: object properties: error: $ref: '#/components/schemas/ResponseErrorNew' ReviewsResponse: description: Reviews Response content: application/json: schema: title: ReviewsResponse type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' response: type: object properties: count: type: integer description: Total number of Reviews that meet filter criteria (ignores limit/offset) averageRating: type: number format: double description: Average rating of Reviews that matched the query parameters. reviews: type: array items: $ref: '#/components/schemas/Review' nextPageToken: type: string description: 'This field is only included if there is an additional page of data to display. To retrieve the next page of data, pass this field''s value as the **`pageToken`** parameter in a subsequent request nextPageToken is only returned with the inclusion of a **`v`** parameter of `20170901` or later. ' readOnly: true parameters: listingsPublisherIds: name: publisherIds in: query schema: type: array items: type: string description: 'List of publisher IDs. If no IDs are specified, defaults to all publishers subscribed by the account. **Example:** MAPQUEST,FACEBOOK ' style: simple reviewId: name: reviewId in: path required: true schema: type: integer description: ID of this Review. workflowRuleId: name: workflowRuleId in: path required: true schema: type: string description: ID of this Workflow Rule. commentId: name: commentId in: path required: true schema: type: string accountId: name: accountId in: path required: true schema: type: string num: name: num in: query required: true schema: type: string description: 'The number of reviews to return ' listingId: name: listingId in: query required: true schema: type: string description: 'The unique identifier of a listing on your site is known as the listingId. ' invitationId: name: invitationUid in: path required: true schema: type: string description: 'The UID of this Review Invitation. This UID can be included as part of Review Creation requests for attribution. ' v: name: v in: query required: true schema: type: string description: A date in `YYYYMMDD` format. commentId_2: name: commentId in: path required: true schema: type: string description: 'The review comment’s ID on your site ' before: name: before in: query required: false schema: type: string description: 'An ISO-8601 date-time that filters results to those reviews posted before this time (exclusive). If not specified, no filter should be applied. NOTE: This parameter is used to page through results. For example, Yext may fetch the newest 10 reviews and make a subsequent request with before set to the last review''s timestamp in order to fetch the second page. ' schemas: Attestation: type: object description: 'Attestation certifying SEC compliance requirements for review responses. This is only relevant when the Compliant Review Response setting is enabled for the account. ' required: - reviewerWasPaid - reviewerIsClient - isConflictOfInterest properties: reviewerWasPaid: type: boolean description: 'Indicates whether the reviewer was paid or otherwise compensated for the review. ' reviewerIsClient: type: boolean description: 'Indicates whether the reviewer is a client of the business. ' isConflictOfInterest: type: boolean description: 'Indicates whether there is a conflict of interest between the reviewer and the business. ' conflictOfInterestDetails: type: string description: 'Details about the conflict of interest. This field is required when `isConflictOfInterest` is `true`. ' UpdatedReviewInvitation: allOf: - type: object properties: invitationUid: type: string readOnly: true description: 'The UID of this Review Invitation. This UID can be included as part of Review Creation requests for attribution. If the **`v`** parameter is before `20210728`, please refer to **`id`** as the parameter name instead of **`invitationUid`**. ' entity: type: object properties: id: type: string description: 'ID of the entity associated with this review. If the **`v`** parameter is before `20210728`, please refer to **`locationId`** as the parameter name instead of **`entity`**. ' firstName: type: string description: '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: type: string description: '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: type: string description: '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: type: string description: 'The email address or phone number of the person from whom a review is being requested. Phone numbers will be formatted in the E.164 standard international format, with a leading "+". The **`contact`** parameter will only be respected for **`v`** parameters of `20210728` or later. ' transactionId: type: string description: '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: type: string description: '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: type: string enum: - SENT - PENDING - CANCELED - ATTEMPTED - NOT_DELIVERED - FAILED - DISABLED errorCode: type: string description: 'The error code of the invitation if applicable. The **`errorCode`** parameter will only be respected for **`v`** parameters of `20210727` or earlier. ' errorReason: type: string description: 'The error reason text of the invitation if applicable. The **`errorReason`** parameter will only be respected for **`v`** parameters of `20210727` or earlier. ' - $ref: '#/components/schemas/ReviewInvitationDates' ResponseMetaWithError: allOf: - $ref: '#/components/schemas/ResponseMeta' - type: object properties: errors: type: array description: List of errors and warnings. items: $ref: '#/components/schemas/ResponseError' UpdateReviewLabelsRequest: type: object properties: labelIds: type: array items: type: integer description: The IDs of the review labels added to the review. PartnerReviewResponseUpdate: type: object properties: reviewId: type: string description: 'The review''s ID on your site ' flagReason: type: string enum: - INAPPROPRIATE_CONTENT - SPAM - NOT_LOCATION_RELATED description: 'If present, the business owner is flaggint the review for the specified reason. ' commentId: type: string description: 'The review comment''s Id on your site ' comment: type: string description: 'If present, the business owner''s response to the review ' PartnerReviewResponse: type: object properties: reviewId: type: string description: 'The review''s ID on your site ' flagReason: type: string enum: - INAPPROPRIATE_CONTENT - SPAM - NOT_LOCATION_RELATED description: 'If present, the business owner is flagging the review for the specified reason. ' comment: type: string description: 'If present, the business owner''s response to the review ' NextPageToken: type: string description: "This field is only included if there is an additional page of data to display. To retrieve the next page of data, pass this field's value as the **``pageToken``** parameter in a subsequent request. \n" WorkflowRuleInput: type: object properties: assignee: type: string description: 'Resource name or email address of the user assigned to tasks created by this workflow rule. Set only one of **`assignee`** or **`assigneeUserGroup`**. External email addresses that don''t correspond to a user are only supported when **`ruleType`** is `GENERATIVE_REVIEW_RESPONSE` and **`autoPublishGenerativeResponse`** is false. Format: `accounts/{accountId}/users/{userId}` ' assigneeUserGroup: type: string description: 'Resource name of the user group assigned to tasks created by this workflow rule. When this is set, tasks are assigned to the user in the group with the fewest open tasks. Set only one of **`assignee`** or **`assigneeUserGroup`**. Format: `accounts/{accountId}/userGroups/{userGroup}` ' displayName: type: string description: The name of the workflow rule. enabled: type: boolean description: Whether the workflow rule is enabled. domainConfiguration: type: object description: 'Domain-specific configuration for the workflow rule. The supported keys depend on **`ruleType`**. Supported keys: - `filterCriteria` - `ruleApplication` - `automaticResponseAssetIds` - `autoPublishGenerativeResponse` ' properties: filterCriteria: type: string description: 'CEL expression used to filter which reviews match the workflow rule. ' ruleApplication: type: string description: 'Specifies when the workflow rule should be applied. ' enum: - NEW_REVIEWS - NEW_AND_UPDATED_REVIEWS - LABEL_APPLICATION automaticResponseAssetIds: type: array description: 'IDs of response assets used when **`ruleType`** is `AUTOMATIC_REVIEW_RESPONSE`. ' items: type: integer autoPublishGenerativeResponse: type: boolean description: 'Whether generative responses can be published without human approval. This is only used when **`ruleType`** is `GENERATIVE_REVIEW_RESPONSE`. ' ruleType: type: string description: The type of workflow rule. enum: - REVIEW_RESPONSE - AUTOMATIC_REVIEW_RESPONSE - GENERATIVE_REVIEW_RESPONSE dueDate: type: object description: 'Relative due date applied to tasks created by the workflow rule. ' properties: value: type: integer description: Positive numeric value of the due date. unit: type: string description: Unit of time for the due date. enum: - HOUR - DAY - WEEK ReviewLabel: type: object properties: id: type: integer description: The ID of this review label. readOnly: true name: type: string description: The name of this review label. readOnly: true UpdateReview: type: object properties: locationId: type: string description: ID of the location associated with this review rating: type: number format: double description: 'Normalized rating out of 5. Can only be specified for External First Party Reviews. ' content: type: string description: 'Content of the review. Can only be specified for External First Party Reviews. ' authorName: type: string description: 'The name of the person who wrote the review. Can only be specified for External First Party Reviews. ' authorEmail: type: string description: 'The email address of the person who wrote the review. Can only be specified for External First Party Reviews. ' status: type: string enum: - LIVE - QUARANTINED - REMOVED description: 'The current status of the review. ' WorkflowRule: allOf: - $ref: '#/components/schemas/WorkflowRuleInput' - type: object properties: name: type: string description: 'Resource name of the workflow rule. Format: `accounts/{accountId}/workflowRules/{workflowRuleId}` ' createTime: type: string description: Timestamp when the workflow rule was created. UpdateReviewInvitationRequest: allOf: - $ref: '#/components/schemas/ReviewInvitationDates' - type: object properties: firstName: type: string description: '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: type: string description: '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: type: string description: '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: type: string description: '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: type: string description: '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: type: string description: '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: type: string enum: - CANCELED description: '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: type: string description: '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: type: string description: '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. ' PartnerReview: type: object required: - reviewId - status - timestamp - authorName - url properties: reviewId: type: string description: A unique ID for each review, as assinged by you example: '5382' status: type: string description: The status of the review enum: - ACTIVE - SUPPRESSED timestamp: type: string description: Date and time that the review was posted in ISO-9601 format example: '2020-01-01T13:15:53Z' authorName: type: string description: The name of the user who posted the review example: Dana Smith title: type: string description: The title of the review example: Great falafel content: type: string description: The full text of the review example: Went there for lunch and had the best sandwich of my life. url: type: string description: The URL where consumers can read the review example: http://www.partner.com/listings/382384/reviews/5382 rating: type: string description: The rating given by the review example: '4.5' maxRating: type: string description: The maximum possible rating of a review on your site flagReason: type: string description: If present, the business owner has flagged the review a specific reason enum: - INAPPROPRIATE_CONTENT - SPAM - NOT_LOCATION_RELATED comments: $ref: '#/components/schemas/PartnerReviewComments' generated: type: boolean description: Indicates whether the review was written in response to a request from a review_generation program CreateReview: type: object required: - entityId - authorName - rating properties: entityId: type: string description: ID of the entity associated with this review. authorName: type: string description: The name of the person who wrote the review. rating: type: number format: double description: 'Normalized rating out of 5. ' content: type: string description: 'Content of the review. ' authorEmail: type: string description: The email address of the person who wrote the review. status: type: string enum: - LIVE - QUARANTINED - REMOVED description: 'The current status of the review; only returned for First Party and External First Party reviews. Defaults to `QUARANTINED` when creating. ' date: type: string format: date description: 'If the v parameter is before 20240515: (YYYY-MM-DD format) If provided, the date you received the review from the customer. Defaults to the date the review was uploaded to Yext. Time defaults to midnight ET. If the v parameter is 20240515 or later: ISO-8601 format (YYYY-MM-DDThh:mm:ssTZD) if provided, the date you received the review from the customer. Date defaults to the date the review was uploaded to Yext. Time defaults to midnight and timezone defaults to UTC. Examples: 2024-05-15, 2024-05-15T04:44:50, 2024-05-15T04:44:50-05:00 ' publisherId: type: string description: 'The ID of the publisher associated with the review. If v parameter is after 20240515, defaults to `FIRSTPARTY`. If v parameter is before 20240515, defaults to `EXTERNALFIRSTPARTY`. ' externalId: type: string description: 'The External ID of the review, typically assigned by the Publisher. Created External IDs must be unique per entity and publisher pair. ' invitationUid: type: string description: 'The ID of the invitation which should be associated with this review. ' ReviewInvitation: type: object required: - locationId - entity - firstName - lastName - contact properties: invitationUid: type: string readOnly: true description: 'The UID of this Review Invitation. This UID can be included as part of Review Creation requests for attribution. If the **`v`** parameter is before `20210728`, please refer to **`id`** as the parameter name instead of **`invitationUid`**. ' entity: type: object properties: id: type: string description: 'ID of the entity associated with this review. If the **`v`** parameter is before `20210728`, please refer to **`locationId`** as the parameter name instead of **`entity`**. ' firstName: type: string description: The first name of the person from whom a review is being requested. lastName: type: string description: The last name of the person from whom a review is being requested. contact: type: string description: '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 ' title: type: string description: 'The title of the person from whom a review is being requested (e.g., Mr., Mrs., Miss, etc.). ' includeImage: type: boolean description: '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: type: string description: '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: type: string description: 'The ID of the transaction being reviewed in response to this invitation. ' status: type: string enum: - ACCEPTED - REJECTED - PENDING readOnly: true details: type: string description: If status is REJECTED, describes why the invitation could not be processed. readOnly: true language: type: string description: "The ISO 639-1 code of the review invitation's language. Only valid for invitations created\nfrom built-in templates. Defaults to `en`.\n\nSupported languages:\n * `en`\n * `de`\n * `fr`\n * `es`\n * `it`\n * `nl`\n * `ja`\n" additionalURLParameters: type: string description: '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: type: boolean description: '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. ' feedbackURL: type: string readOnly: true description: 'The created Feedback URL unique to this invitation. The **`feedbackURL`** parameter will only be respected with the inclusion of a **`v`** parameter of `20210728` or later. ' reviewLabels: type: array readOnly: true items: type: object description: 'Review Labels associated with the review. The **`reviewLabels`** parameter will only be respected with the inclusion of a **`v`** parameter of `20210728` or later. ' CreateWorkflowRule: allOf: - $ref: '#/components/schemas/WorkflowRuleInput' - type: object required: - displayName - domainConfiguration - ruleType ReviewGenerationSettings: type: object properties: maxEmailsPerDay: type: integer minimum: 0 maximum: 200 description: '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: type: integer minimum: 1 description: 'Indicates the maximum number of text invites our system will send on a per-location, per-month basis. ' maxTextsPerDay: type: integer minimum: 1 maximum: 20 description: '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: type: integer enum: - 1 description: '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: type: integer enum: - 7 - 30 - 60 - 90 description: '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: type: integer minimum: 0 maximum: 7 description: '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: type: string description: '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`**. ' balancingOptimization: type: string enum: - DISTRIBUTION - MORE_REVIEWS - MUST_BE_LOGGED_IN description: 'Defaults to **`DISTRIBUTION`**. Optionally configure the algorithm to prioritize sites where you have fewer reviews to generate more reviews (**`MORE_REVIEWS`**), or prioritize sites where a user is already logged in on their device (**`MUST_BE_LOGGED_IN`**). ' algorithmConfiguration: type: array description: 'Optionally prioritize the following issues to determine where to send review invites: **`WEBSITE`**: generate more first-party reviews if one of the last 5 reviews has 1 star, **`RATING`**: prioritize sites that have the lower rating, **`RECENCY`**: prioritize sites that haven’t received a review in the last month. ' items: type: string enum: - WEBSITE - RECENCY - RATING uniqueItems: true maxItems: 3 siteDistribution: type: object description: '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. **`GOOGLEMYBUSINESS: 1`** and **`FIRSTPARTY: 1`**, would send half of the review invites to Google and half to your First Party site. ' additionalProperties: type: integer minimum: 1 minProperties: 0 example: FACEBOOK: 3 GOOGLEMYBUSINESS: 5 FIRSTPARTY: 1 ResponseErrorNew: type: object properties: code: type: integer description: 'Code that uniquely identifies the error or warning. ' message: type: string description: Message explaining the problem. ReviewInvitationOptional: type: object properties: invitationUid: type: string readOnly: true description: 'The UID of this Review Invitation. This UID can be included as part of Review Creation requests for attribution. If the **`v`** parameter is before `20210728`, please refer to **`id`** as the parameter name instead of **`invitationUid`**. ' entity: type: object properties: id: type: string description: 'ID of the entity associated with this review. If the **`v`** parameter is before `20210728`, please refer to **`locationId`** as the parameter name instead of **`entity`**. ' firstName: type: string description: The first name of the person from whom a review is being requested. lastName: type: string description: The last name of the person from whom a review is being requested. title: type: string description: 'The title of the person from whom a review is being requested (e.g., Mr., Mrs., Miss, etc.). ' contact: type: string description: '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: type: boolean description: '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: type: string description: '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: type: string description: 'The ID of the transaction being reviewed in response to this invitation. ' status: type: string enum: - ACCEPTED - REJECTED - PENDING readOnly: true details: type: string description: If status is REJECTED, describes why the invitation could not be processed. readOnly: true language: type: string description: "The ISO 639-1 code of the review invitation's language. Only valid for invitations created\nfrom built-in templates. Defaults to `en`.\n\nSupported languages:\n * `en`\n * `de`\n * `fr`\n * `es`\n * `it`\n * `nl`\n * `ja`\n" additionalURLParameters: type: string description: '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: type: boolean description: '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. ' feedbackURL: type: string readOnly: true description: 'The created Feedback URL unique to this invitation. The **`feedbackURL`** parameter will only be respected with the inclusion of a **`v`** parameter of `20210728` or later. ' reviewLabels: type: array readOnly: true items: type: object description: 'Review Labels associated with the review. The **`reviewLabels`** parameter will only be respected with the inclusion of a **`v`** parameter of `20210728` or later. ' PartnerReviewList: type: object required: - total - rating - maxRating properties: total: type: integer description: Total number of reviews on the listing rating: type: number description: The average rating across all reviews for this listing maxRating: type: integer description: The maximum possible rating (e.g., 5) reviews: type: array description: A list of num Review objects, respecting the filter specified in before and sorted in reverse chronological order items: $ref: '#/components/schemas/PartnerReview' PartnerReviewComments: type: array description: List of comments on the review items: required: - commentId - timestamp - authorName - content properties: commentId: type: string description: Id of the review comment example: '832813382' timestamp: type: string description: Date and time that the review comment was posted in ISO-9601 format example: '2020-01-04T13:15:53Z' authorName: type: string description: The name of the user who posted the review comment example: Gomez Adams content: type: string description: The full text of the review comment example: The hummus is good too! ownerResponse: type: boolean description: Indicates whether the comment was made by the business owner UpdateWorkflowRule: allOf: - $ref: '#/components/schemas/WorkflowRuleInput' - type: object description: 'Fields that may be supplied when updating a workflow rule. Updatable fields are `assignee`, `assigneeUserGroup`, `displayName`, `enabled`, `domainConfiguration`, `ruleType`, and `dueDate`. Output-only fields such as `createTime` are not part of this update schema. ' properties: name: type: string description: 'Resource name of the workflow rule to update. Format: `accounts/{accountId}/workflowRules/{workflowRuleId}` ' ReviewInvitationDates: type: object properties: sent: type: integer format: int64 description: 'The timestamp the invitation was sent (seconds since epoch), if the invitation was sent. ' opened: type: integer format: int64 description: '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: type: integer format: int64 description: The timestamp the invitation was clicked (seconds since epoch). reviewed: type: integer format: int64 description: '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`**. ' GetReviewInvitation: allOf: - $ref: '#/components/schemas/ReviewInvitationOptional' - type: object properties: partnerId: type: string description: 'The determined sender of the invitation. For invitations directed towards App Directory Partners, the ID of partner, otherwise this will be FIRSTPARTY. ' type: type: string enum: - EMAIL - SMS requested: type: integer format: int64 description: The timestamp the invitation was requested. - $ref: '#/components/schemas/ReviewInvitationDates' - type: object properties: reviewId: type: string description: ID of the review if this invitation resulted in a review ResponseMeta: type: object properties: uuid: type: string example: 4f72b877-e2d0-4de4-9324-b9cf2c03e1a0 description: Unique ID for this request / response. CreateReviewInvitationRequest: allOf: - $ref: '#/components/schemas/ReviewInvitation' - type: object properties: reviewLabelNames: type: array items: type: string description: '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. ' delayTime: type: integer description: 'The amount of time to wait before sending the invitation after creation. The **`delayTime`** parameter will only be respected with the inclusion of a **`v`** parameter of `20241211` or later. ' delayTimeUnit: type: string description: 'If **`delayTime`** is set, specify the unit of time. Accepted values: `hours`, `days` The **`delayTimeUnit`** parameter will only be respected with the inclusion of a **`v`** parameter of `20241211` or later. ' sendTime: type: string description: 'To send invites at a later time, provide an ISO formatted date/time value, e.g. `2024-09-04T12:00:00`. **`delayTime`** and **`sendTime`** cannot both be set on the same invite. The **`sendTime`** parameter will only be respected with the inclusion of a **`v`** parameter of `20241211` or later. ' ResponseError: type: object properties: name: type: string code: type: integer description: 'Code that uniquely identifies the error or warning. ' type: type: string enum: - FATAL_ERROR - NON_FATAL_ERROR - WARNING message: type: string description: Message explaining the problem. ReviewCommentUpdate: type: object properties: content: type: string description: Content of the comment. visibility: type: string enum: - PUBLIC - PRIVATE Review: type: object properties: id: type: integer description: ID of this review readOnly: true locationId: type: string description: ID of the location associated with this review accountId: type: string description: ID of the account associated with this review publisherId: type: string description: 'For third-party reviews, the ID of publisher associated with this listing. For first-party reviews, this will be FIRSTPARTY. ' readOnly: true rating: type: number format: double description: 'Normalized rating out of 5. This value is omitted if the review does not include a rating. ' title: type: string description: 'Title of the review. This value is omitted if reviews on the publisher''s site do not have titles. ' readOnly: true content: type: string description: 'Content of the review. ' authorName: type: string description: The name of the person who wrote the review (if we have it). authorEmail: type: string description: The email address of the person who wrote the review (if we have it). url: type: string description: The URL of the review, or the URL of the listing where the review can be found if there is no specific URL for the review. readOnly: true publisherDate: type: integer format: int64 description: The timestamp of the review as reported by the publisher. If edits impact the review date on the publisher, then this date may change. This date always comes from the publisher and we respect whatever they have. readOnly: true lastYextUpdateTime: type: integer format: int64 description: 'If the **`v`** parameter is before `20170512`: the timestamp of the review (including listing updates). If the **`v`** parameter is `20170512` or later: the timestamp of the review (excluding listing updates), or the timestamp of the latest comment on the review. ' readOnly: true status: type: string enum: - LIVE - QUARANTINED - REMOVED description: The current status of the review; only returned for First Party and External First Party reviews. Defaults to `QUARANTINED` when creating. flagStatus: type: string enum: - FLAGGED - NOT_FLAGGED description: Indicates whether the review has been flagged for inappropriate or irrelevant content. Note that only First Party and External First Party reviews can be flagged. reviewLanguage: type: string description: The language of the review, if identified. comments: type: array description: 'An ordered array of Comments on the review. **NOTE:** The order is a flattened tree with depth ties broken by publisher date. ' readOnly: true items: $ref: '#/components/schemas/ReviewComment' labelIds: type: array description: 'If the **`v`** parameter is before `20180710`: The IDs of the review labels added to the review. If the **`v`** parameter is `20180710` or later: Not present. **NOTE:** You can only add labels that have already been created via our web interface. Currently, it is not possible to create new labels via the API. ' readOnly: true items: type: integer format: int64 reviewLabels: type: array description: 'If the **`v`** parameter is before `20180710`: Not present. If the **`v`** parameter is `20180710` or later: The names and IDs of the review labels added to the review. **NOTE:** You can only add labels that have already been created via our web interface. Currently, it is not possible to create new labels via the API. ' readOnly: true items: $ref: '#/components/schemas/ReviewLabel' reviewType: type: string enum: - Rating - Recommendation description: 'If the **`v`** parameter is before `20181002`: Not present. If the **`v`** parameter is `20181002` or later: Indicates whether the review is a rating or a recommendation. **NOTE:** Only applicable to Facebook reviews. ' readOnly: true recommendation: type: string enum: - Recommended - Not Recommended description: 'If the **`v`** parameter is before `20181002`: Not present. If the **`v`** parameter is `20181002` or later: Indicates whether the consumer recommends the entity being reviewed. **NOTE:** Only applicable to Facebook reviews. ' readOnly: true transactionId: type: string description: 'If present, the transaction ID associated with the invitation that resulted in this review. ' invitationId: type: string description: 'If present, the ID associated with the invitation that resulted in this review. ' apiIdentifier: type: string description: 'The unique identifier which will need to be included in any further requests to update or delete this review via the Review Submission API. Only supported for reviews created via Yext invitations or the Review Submission API. One of: * A UUID generated at the time the Review Creation request is accepted. * The invitationUid, if the review is associated with an invitation. ' ReviewComment: type: object properties: id: type: integer description: ID of this comment (assigned by Yext). readOnly: true parentId: type: integer description: If this comment is in response to another comment, this is the ID of the parent comment. publisherDate: type: integer format: int64 description: The timestamp of the comment as reported by the publisher. If edits impact the comment timestamp on the publisher, then this timestamp may change. This timestamp always comes from the publisher and we respect whatever they have. readOnly: true authorName: type: string description: The name of the person who wrote the comment (if we have it). readOnly: true authorEmail: type: string description: The email address of the person who wrote the comment (if we have it). readOnly: true authorRole: type: string enum: - BUSINESS_OWNER - CONSUMER readOnly: true content: type: string description: Content of the comment. visibility: type: string enum: - PUBLIC - PRIVATE description: Defaults to `PUBLIC` when creating a comment date: type: string format: date description: 'If the v parameter is before 20240515: (YYYY-MM-DD format) If provided, the date the comment was posted. Date defaults to the date the comment was uploaded to Yext. Time defaults to midnight ET. If the v parameter is 20240515 or later: ISO-8601 format (YYYY-MM-DDThh:mm:ssTZD) if provided, the date the comment was posted. Date defaults to the date the comment was uploaded to Yext. Time defaults to midnight and timezone defaults to UTC. Examples: 2024-05-15, 2024-05-15T04:44:50, 2024-05-15T04:44:50-05:00 ' suppressReviewerContact: type: boolean description: 'Indicates whether or not the reviewer receives an email notification when a comment is posted. Defaults to `false`. ' attestation: $ref: '#/components/schemas/Attestation' description: 'SEC compliance attestation for the review response. This field is only relevant when the **Compliant Review Response** setting is enabled for the account. When the Compliant Review Response setting is enabled: * The `attestation` field is **required** * The `Yext-User-Id` header is **required** (must be the user ID of the person submitting the attestation) * The response code for successful requests is **202 Accepted** When the Compliant Review Response setting is disabled: * The `attestation` field is ignored ' requestBodies: commentUpdateRequest: required: true content: application/json: schema: $ref: '#/components/schemas/ReviewCommentUpdate' commentRequest: required: true content: application/json: schema: $ref: '#/components/schemas/ReviewComment' updateReviewInvitationRequest: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateReviewInvitationRequest' updateReviewLabelsRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateReviewLabelsRequest' reviewGenerationSettingsRequest: required: true content: application/json: schema: $ref: '#/components/schemas/ReviewGenerationSettings' securitySchemes: api_key: type: apiKey name: api_key in: query api-key: type: apiKey name: api-key in: header