Post or edit a response

Overview

Write a reply to a review and queue it for posting to the live review site. Call it again with new text to edit a reply you've already posted.

Use this whenever you're answering a review, whether you wrote the text yourself or took it from an AI draft.

You'll need the review_id and the response text. If the text came from an AI draft, include its ai_response_id so it's linked. Text can be at most 4,000 characters; a couple of sites have tighter limits, and the error will tell you.

Returns confirmation that the response is queued for posting. It won't post if the site isn't authorized (422 naming connection or posting), if the text is identical to the current reply (400), or if your plan's response allowance is used up (402, with the limit details in X-Feature headers).

Prerequisites

A bearer token. See Authentication.
The review's id (review_id).
The review site must be connected for the location, with posting available for that site.
Optional: the id of the AI draft you used (ai_response_id, from Draft a response with AI).

Base URL

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

Endpoint

POST /api/v1/response/save

Authentication

Partner or Account token

The review must be inside your own account tree. A Partner token can respond to reviews of any location under the partner; an Account token only to its own locations' reviews.
A review outside your tree is rejected with 422. A review that isn't on one of your locations returns 403 Access denied.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Description
`review_id`	integer	Yes	The review to respond to. Must exist and be inside your account tree.
`response`	string	Yes	The response text. At most 4,000 characters. OpenTable allows at most 400 characters, not counting spaces; Optspot needs 80 to 160 characters. Must differ from the current reply (case and surrounding spaces are ignored).
`ai_response_id`	integer	No	The id of the AI draft the text is based on (`ai_review_response_id` from Draft a response with AI). Must exist. It's linked only when the draft belongs to the same review; otherwise it's ignored.
`ai_response`	string	No	Not used. The draft's text is read from `ai_response_id`.

Request payload

{
  "review_id": 279309,
  "response": "Thank you for the kind review! We are glad you enjoyed your visit and hope to see you again soon.",
  "ai_response_id": 39
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`response`	string	`Your response has been submitted and will be posted live`.

The response also carries your plan's allowance for responses in headers: X-Feature (response_posting, or response_to_past_reviews for a review older than the location), 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",
    "response": "Your response has been submitted and will be posted live"
  }
}

Examples

Success payload

See Response payload.

Error payload

400 Response too long

{
  "message": "Please reduce the number of characters in your response. Max allowed is 4000 characters.",
  "status": "error",
  "errors": "Response is too long"
}

400 Same as the current reply

{
  "message": "Please make minor edits to this response.",
  "status": "error",
  "errors": "The review sites do not allow you to submit the exact same response for the same review."
}

402 Response allowance used up

{
  "status": "error",
  "message": "Limit reached for 'Response Posting': 100 of 100 units consumed this period.",
  "feature": "response_posting",
  "remaining": 0,
  "hard_stop": true
}

403 Review not on your locations

{
  "message": "Forbidden",
  "status": "error",
  "errors": "Access denied"
}

403 Review predates your subscription

{
  "message": "Forbidden",
  "status": "error",
  "errors": "This review predates your subscription with this platform. Please respond directly on the review site."
}

422 Review site not connected

{
  "message": "This review site is not connected for this store. Please connect it before responding.",
  "status": "error",
  "errors": {
    "connection": [
      "This review site is not connected for this store. Please connect it before responding."
    ]
  }
}

422 Posting not available for the site

{
  "message": "Posting is not available for this review site.",
  "status": "error",
  "errors": {
    "posting": [
      "Posting is not available for this review site."
    ]
  }
}

422 Review outside your tree

{
  "message": "The selected review id does not belong to your company hierarchy.",
  "errors": {
    "review_id": [
      "The selected review id does not belong to your company hierarchy."
    ]
  }
}

422 Missing fields

{
  "message": "The review id field is required. (and 1 more error)",
  "errors": {
    "review_id": [
      "The review id field is required."
    ],
    "response": [
      "The response field is required."
    ]
  }
}

Status	Meaning
`200`	The response is saved and queued for posting.
`400`	The text is too long or too short for the site, or identical to the current reply.
`401`	The token is missing, expired or invalid.
`402`	Your plan's response allowance is used up, or responses 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 responses aren't available for it (for example, it predates your subscription with the site).
`422`	A field is missing or invalid, the review is outside your tree, the site isn't connected (or has an unresolved posting error), or posting isn't available for the site.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/response/save" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"review_id": 279309, "response": "Thank you for the kind review! We are glad you enjoyed your visit and hope to see you again soon.", "ai_response_id": 39}'