Record private feedback from a customer

Overview

Save a customer's comment and star rating about their experience, tied to the review request they received, and notify the business. The comment is saved as a review on the location, under the review site you pass; it isn't posted to that site.

Called by the landing page when a customer chooses to leave feedback privately instead of a public review.

You'll need the request's unique code and the comment.

The feedback is saved and the business's configured recipients are emailed. A customer who already left feedback for that location and review site (same email or phone) gets 400.

🚧
Browser-only endpoint. This is a public form handler, not a server-to-server API. It requires a Google reCAPTCHA token that is verified server-side against Shout About Us's own reCAPTCHA key, so a token can only be produced by a real browser session on a Shout About Us-hosted page (the review landing page or the sign-up page). A token from your own reCAPTCHA key or your own page won't pass. That means this endpoint cannot be called from a backend, a script, or Postman: those requests fail validation with 422. No bearer token is used or accepted.

Prerequisites

No token. A reCAPTCHA token from a Shout About Us-hosted page, and the review request's unique code from the customer's link.

Base URL

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

Endpoint

POST /api/v1/campaign/direct-comment-feedback

Authentication

Public (no token)

No bearer token is used. The review request's unique_code decides which location the feedback is saved to.

Rate limit

30 requests per minute, counted per client IP address. See Rate limits.

Request parameters

None.

Request body

Field	Type	Required	Description
`unique_code`	string	Yes	The email or SMS review request's unique code, up to 50 characters.
`email`	string	Yes	The customer's email address, up to 100 characters. Checked with an RFC and DNS lookup, so the domain must accept mail.
`name`	string	Yes	The customer's name, up to 100 characters. Saved as the reviewer.
`phone`	string	No	The customer's phone number, 7–20 characters.
`comments`	string	Yes	The comment, up to 255 characters. Saved as the review text.
`star_rating`	integer	Yes	The rating, `1`–`5`.
`g_recaptcha_response`	string	Yes	The Google reCAPTCHA token from the Shout About Us-hosted page.
`review_site_id`	integer	Yes	The review site to save the feedback under. Must be an existing review site.

Request payload

{
  "unique_code": "4xwu8",
  "email": "<customer-email>",
  "name": "Jane Smith",
  "phone": "+15555550100",
  "comments": "Great service, thank you!",
  "star_rating": 5,
  "g_recaptcha_response": "<recaptcha-token>",
  "review_site_id": 44
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`message`	string	`Thank you for your comment. Your feedback helps us improve our service.`

Response payload

{
  "data": {
    "status": "success",
    "message": "Thank you for your comment. Your feedback helps us improve our service."
  }
}

Examples

Success payload

See Response payload.

Error payload

400 Already submitted

{
  "message": "Bad Request",
  "status": "error",
  "errors": "You have already submitted your feedback. Thank you!"
}

400 Review request not found

{
  "message": "Bad Request",
  "status": "error",
  "errors": "Email or SMS request not found"
}

422 reCAPTCHA or email rejected

{
  "message": "The email field must be a valid email address. (and 1 more error)",
  "errors": {
    "email": [
      "The email field must be a valid email address."
    ],
    "g_recaptcha_response": [
      "The google recaptcha is invalid. Please refresh the page and try again."
    ]
  }
}

422 Fields missing

{
  "message": "The unique code field is required. (and 6 more errors)",
  "errors": {
    "unique_code": [
      "The unique code field is required."
    ],
    "email": [
      "The email field is required."
    ],
    "name": [
      "The name field is required."
    ],
    "comments": [
      "The comments field is required."
    ],
    "star_rating": [
      "The star rating field is required."
    ],
    "g_recaptcha_response": [
      "The g recaptcha response field is required."
    ],
    "review_site_id": [
      "The review site id field is required."
    ]
  }
}

Status	Meaning
`200`	The feedback is saved.
`400`	Feedback was already left for this location and review site, the unique code matches no review request, or the review site doesn't exist.
`422`	A field is missing or invalid, including an invalid reCAPTCHA token.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/campaign/direct-comment-feedback" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"unique_code": "4xwu8", "email": "<customer-email>", "name": "Jane Smith", "phone": "+15555550100", "comments": "Great service, thank you!", "star_rating": 5, "g_recaptcha_response": "<recaptcha-token>", "review_site_id": 44}'