Flag a review

Overview

Report a review to its site with one of that site's accepted reasons and a short explanation of why. If a flag is already pending on the review, this updates it.

Use this when a review is fake, abusive, about the wrong business, or otherwise breaks the site's rules. Check is_flaggable on the review first; some reviews can't be flagged: the review is more than 14 days old, its site doesn't accept flags, the flag was already decided, or the review site isn't connected.

You'll need the review_id, the site's name, a reason_identifier from that site's reason list, the matching reason text, and your explanation (up to 500 characters). Indeed requires several extra fields about your business; the parameter table lists them.

The flag is submitted with status pending and appears in the review's history. If the review was already flagged and decided, you get a 400 telling you to check the site. If the review is past its flagging window, you get a 403. If your plan's flagging allowance is used up, you get a 402 saying so.

Prerequisites

A bearer token. See Authentication.
The review's id (reviewId).
A reason for the review's site from Get the reasons a site accepts.
The review is on a site that accepts flags. Those are the sites Get the reasons a site accepts returns reasons for when you leave out review_site_id.
The review is no more than 14 days old, counted from its review date. Some partners have a partner-specific window.
For sites other than Google and Facebook, the review site must be connected for the location.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/reviews/{reviewId}/flag

Authentication

Partner or Account token

The review must be on one of the locations your token can reach. A Partner token reaches every location under the partner; an Account token its own locations.
A review outside that set returns 403 This review is outside your scope..

Rate limit

This endpoint has no rate limit.

Request parameters

Parameter	In	Type	Required	Description
`reviewId`	path	integer	Yes	The review to flag. Digits only. Must exist.

Request body

Field	Type	Required	Description
`review_site`	string	Yes	The review's site name in lowercase, for example `google`. Must be a site that accepts flags (one with reasons in Get the reasons a site accepts), otherwise `422`.
`reason`	string	Yes	The site's full description of the reason (`reason` from Get the reasons a site accepts).
`reason_identifier`	string	Yes	The reason's short name (`reason_identifier`). At most 255 characters. Must be one of the reasons for the review's site, otherwise `422`.
`flag_reason_detail`	string	Yes	Your explanation of why the review breaks the site's rules. At most 500 characters.
`user_id`	integer	No	The user to record as the flagger. Must exist.
`submit_type`	string	No	Not used here. Only `standalone` is accepted.
`review_response`	string	No	Indeed only: your response to the review, sent with the flag.
`first_name`	string	Indeed only	Your first name. Required when `review_site` is `indeed`.
`last_name`	string	Indeed only	Your last name. Required when `review_site` is `indeed`.
`company`	string	Indeed only	Your company's name. Required when `review_site` is `indeed`.
`company_url`	string	Indeed only	Your company's website. Required when `review_site` is `indeed`.
`phone`	string	Indeed only	Your phone number. Required when `review_site` is `indeed`.
`country`	string	Indeed only	Your country code. Required when `review_site` is `indeed`.
`country_name`	string	Indeed only	Your country's name. Required when `review_site` is `indeed`.
`number_of_employees`	string	Indeed only	Your company's size. Required when `review_site` is `indeed`.
`flag_email_address`	string	Indeed only	Your email address. Required when `review_site` is `indeed`; the format isn't checked.

Request payload

{
  "review_site": "google",
  "reason": "Review is off-topic, contains ads, or is gibberish or repetitive",
  "reason_identifier": "Low quality information",
  "flag_reason_detail": "This reviewer was never a customer and the claims are fabricated."
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`message`	string	`Review has been Flagged Successfully`.

The response also carries your plan's allowance for flags in headers: X-Feature (review_flag), X-Feature-Limit, X-Feature-Used, X-Feature-Remaining (unlimited when there's no cap) and X-Feature-Hard-Stop (1 or 0).

Response payload

{
  "data": {
    "status": "success",
    "message": "Review has been Flagged Successfully"
  }
}

Examples

Success payload

See Response payload.

Error payload

400 Already flagged and decided

{
  "message": "This review has already been flagged. Please check the review site for more details.",
  "status": "error",
  "errors": []
}

402 Flag allowance used up

{
  "status": "error",
  "message": "Limit reached for 'Review Flags': 10 of 10 units consumed this period.",
  "feature": "review_flag",
  "remaining": 0,
  "hard_stop": true
}

403 Review outside your scope

{
  "message": "This review is outside your scope.",
  "status": "error",
  "errors": []
}

403 Review site not connected

{
  "message": "Please connect Yelp before flagging.",
  "status": "error",
  "errors": {
    "flagging": {
      "is_flaggable": false,
      "window_days": 0,
      "expires_at": null,
      "reason": "site_not_connected",
      "message": "Please connect Yelp before flagging."
    }
  }
}

403 Review past its flagging window

expires_at is when the window closed: the review date plus window_days.

{
  "message": "This review is not eligible for flagging.",
  "status": "error",
  "errors": {
    "flagging": {
      "is_flaggable": false,
      "window_days": 14,
      "expires_at": "2026-09-29T09:15:00+00:00",
      "reason": "window_expired"
    }
  }
}

422 Site doesn't accept flags

{
  "message": "The selected review site is invalid.",
  "errors": {
    "review_site": [
      "The selected review site is invalid."
    ]
  }
}

422 Reason not valid for the site

{
  "message": "The selected reason_identifier is not a valid flag reason for this review site. Refresh the page to load the current dropdown.",
  "errors": {
    "reason_identifier": [
      "The selected reason_identifier is not a valid flag reason for this review site. Refresh the page to load the current dropdown."
    ]
  }
}

422 Review doesn't exist

{
  "message": "The selected review id is invalid. (and 3 more errors)",
  "errors": {
    "review_id": [
      "The selected review id is invalid."
    ],
    "reason": [
      "The reason field is required."
    ],
    "reason_identifier": [
      "The reason identifier field is required."
    ],
    "flag_reason_detail": [
      "The flag reason detail field is required."
    ]
  }
}

Status	Meaning
`200`	The review is flagged (or its pending flag is updated).
`400`	The review's flag was already decided by the site.
`401`	The token is missing, expired or invalid.
`402`	Your plan's flag allowance is used up, or flags aren't on the location's plan. The `X-Feature` headers give the details.
`403`	The review isn't on one of your locations, or it can't be flagged: it's past its flagging window, its review date is missing, or the review site isn't connected. `errors.flagging.reason` says which.
`422`	A field is missing or invalid, the review doesn't exist, `review_site` isn't a site that accepts flags, or `reason_identifier` isn't one of the site's reasons.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/reviews/279309/flag" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"review_site": "google", "reason": "Review is off-topic, contains ads, or is gibberish or repetitive", "reason_identifier": "Low quality information", "flag_reason_detail": "This reviewer was never a customer and the claims are fabricated."}'

Updated 7 days ago

Did this page help you?