Flag a review

Overview

Submit (or re-submit, while still pending) a flag against the review identified by the URL {id}. It persists a ReviewFlag row with status pending, writes an audit log and a per-review history event, and consumes the review_flag plan-feature quota.

Prerequisites

A bearer token. Callable with Partner and Account tokens.
The reviewId of the record you are targeting.

Base URL

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

Endpoint

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

Authentication

Requires a bearer token in the Authorization: Bearer <bearer-token> header.
Who can call it: Partner and Account tokens.
The review's store_id must be in the caller's resolvable reachable set of locations. A partner walks its whole tree. An account resolves its own location/store children.
A review outside that set returns 403 This review is outside your scope..
Additional gates apply. The existing flag must be tradie-editable (only pending). It must also return is_flaggable=true (Cat-A lock, tier rules, 90/14-day window, connect-gate).

Rate limit

No rate limit.

Path parameters

Parameter	Type	Required	Description
`reviewId`	integer	Required	Digits only.

Request body

Body:

Field	Type	Required	Description
`review_site`	string	yes	One of `yelp,glassdoor,google,indeed,tripadvisor,apartmentratings,facebook,hipages`.
`submit_type`	string	no	Nullable; only allowed value is `standalone`.
`user_id`	integer	no	Nullable; Must be an existing user. Stored on the flag as the flagging user.
`reason`	string	conditional	Required when `review_site` is any of the listed sites (effectively always). Long platform description matching `reason_identifier`.
`reason_identifier`	string	conditional	Required (same condition); `max:255`; must match a `review_site_flag_reasons` row for the review's `review_site_id`, else 422.
`flag_reason_detail`	string	conditional	Required (same condition); `max:500`. Legacy `description` field is mirrored into this if present.
`review_response`	string	no	Nullable. Stored only inside `json_data` for Indeed.
`first_name`	string	conditional	Required only when `review_site=indeed`.
`last_name`	string	conditional	Required only when `review_site=indeed`.
`company`	string	conditional	Required only when `review_site=indeed`.
`company_url`	string	conditional	Required only when `review_site=indeed`.
`phone`	string	conditional	Required only when `review_site=indeed`.
`country`	string	conditional	Required only when `review_site=indeed`.
`country_name`	string	conditional	Required only when `review_site=indeed`.
`number_of_employees`	string	conditional	Required only when `review_site=indeed` (stored as `numEmployees` in json_data).
`flag_email_address`	string	conditional	Required only when `review_site=indeed`; no email-format check is applied.

{
  "submit_type": "standalone",
  "review_site": "yelp",
  "reason": "It contains threats, lewdness or hate-speech.",
  "reason_identifier": "Inappropriate content",
  "flag_reason_detail": "This reviewer was never a customer and the claims are fabricated.",
  "user_id": 1
}

Response

data.status (string) — success.
data.message (string) — Review has been Flagged Successfully.

200 Success · `200`

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

400 Already flagged (non-pending) · `400`

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

402 Feature limit · `402`

{
  "status": "error",
  "message": "Review Flags limit reached for this period.",
  "feature": "review_flag",
  "remaining": 0,
  "hard_stop": true
}

Errors

Status	Meaning
`400`	Already flagged (non-pending)
`401`	The bearer token is missing, expired or invalid
`402`	Feature limit
`403`	The token is valid but the record sits outside your account
`404`	The review id does not exist
`422`	The request failed validation — the response names the fields
`500`	Unexpected server error

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/reviews/123/flag" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"submit_type": "standalone", "review_site": "yelp", "reason": "It contains threats, lewdness or hate-speech.", "reason_identifier": "Inappropriate content", "flag_reason_detail": "This reviewer was never a customer and the claims are fabricated.", "user_id": 1}'

Updated 11 days ago

Did this page help you?