Kiosk review request

Overview

Submit an in-store kiosk review request. This endpoint looks up a campaign by unique_code and creates a kiosk audience row. It queues an email and/or SMS review-request send based on which channels are supplied and enabled within service limits.

Prerequisites

A bearer token. Callable with Account tokens.

Base URL

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

Endpoint

POST /api/v1/campaign/kiosk-review-request

Authentication

Requires a bearer token in the Authorization: Bearer <bearer-token> header.
Who can call it: Account tokens.
Authentication; the request validation's authorize requires the authenticated user's company to be an Account.
unique_code resolves the campaign (a mismatch returns a 404 "Campaign not found").
An account can only fire kiosk requests for its own campaigns.

Rate limit

This endpoint has no request rate limit. Individual email and SMS sends remain subject to the applicable channel service limits. If neither channel can be sent, the endpoint returns 400 with "No valid channel to send review request".

Request body

Body:

Field	Type	Required	Description
`unique_code`	string	yes	Campaign's unique code; must resolve to a campaign owned by the caller's account company.
`customer_name`	string (max 255)	yes	Customer name; validated by `NameNoAngleBrackets` (no `<`/`>`). Trimmed before save.
`email`	string, email (`rfc,dns`), max 255, nullable	required_without `phone`	Triggers the email channel. At least one of `email`/`phone` must be present.
`phone`	string, min 7, max 20, nullable	required_without `email`	Triggers the SMS channel. At least one of `email`/`phone` must be present.
`requester_name`	string (max 255), nullable	no	Kiosk operator/requestor name; `NameNoAngleBrackets`. Stored as `requester_name` on the audience row.
`is_test`	boolean, nullable	no	When true, marks audience/requests as test and does NOT increment `campaign.total_audience` or schedule email follow-ups. Defaults false.
`keywords`	object/map, nullable	no	Key/value personalization pairs; each key max 100 chars. Empty and null values do not count.
`keywords.*`	string, nullable	no	Value for each keyword key.

{
  "unique_code": "CMP-7F3A9K2",
  "customer_name": "Jane Doe",
  "email": "[email protected]",
  "phone": "+15551234567",
  "requester_name": "Front Desk Kiosk",
  "is_test": false,
  "keywords": {
    "visit_reason": "Routine checkup",
    "staff_member": "Dr. Smith"
  }
}

Response

data.status (string) — "success".
data.message (string) — one of "Email and SMS review requests sent successfully", "Email review request sent successfully", or "SMS review request sent successfully" depending on which channel(s) were queued.

Error paths (not wrapped as success): 404 "Campaign not found" (missing or not owned by caller); 400 "Store does not have an active plan"; 400 "Some review site URLs are missing for this location." (with the per-site error list); 400 "No valid channel to send review request" (with channel/limit errors); 400 "Review Solicitation is not enabled for this store."; 400 "Failed to send review request".

200 Success · `200`

{
  "data": {
    "status": "success",
    "message": "Email and SMS review requests sent successfully"
  }
}

Errors

Status	Meaning
`400`	The store has no active plan, or no valid channel could be sent (the response explains why)
`401`	The bearer token is missing, expired or invalid
`403`	The caller's company is not an account (only account users can send kiosk requests)
`404`	The campaign was not found or is not owned by the caller's account
`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/campaign/kiosk-review-request" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"unique_code": "CMP-7F3A9K2", "customer_name": "Jane Doe", "email": "[email protected]", "phone": "+15551234567", "requester_name": "Front Desk Kiosk", "is_test": false, "keywords": {"visit_reason": "Routine checkup", "staff_member": "Dr. Smith"}}'

Updated 11 days ago

Did this page help you?