Send a review request from a kiosk

Overview

Send a review request entered on an in-store device or tablet.

Use this when customers give their email or phone at a counter or kiosk.

You'll need the campaign's unique_code and the customer's contact.

The message is queued and sent.

If one channel is usable and the other isn't, only the usable channel is sent.

Prerequisites

A bearer token. See Authentication.
The campaign's unique_code (unique_code in List campaigns or Get one campaign). Its Email and/or SMS channel must be enabled and have a template.
An active plan on the campaign's location.

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

Account token

Only an Account token is accepted; other tokens get 403.
The campaign must belong to your own account. If it doesn't, or the code matches no campaign, the call returns 404 Campaign not found.

Rate limit

60 requests per minute, counted per user (the token’s user). See Rate limits.

Request parameters

None.

Request body

Send email, phone, or both.

Field	Type	Required	Description
`unique_code`	string	Yes	The campaign's unique code. Must match a campaign in your own account; otherwise `404`.
`customer_name`	string	Yes	The customer's name, up to 255 characters, without `<` or `>`.
`email`	string	Without `phone`	The customer's email address, up to 255 characters. Sends by email. Checked with an RFC and DNS lookup, so the domain must accept mail: addresses like `@example.com` are rejected with `422`.
`phone`	string	Without `email`	The customer's phone number, 7–20 characters. Sends by text.
`requester_name`	string	No	Who entered the request, e.g. the kiosk or staff member, up to 255 characters, without `<` or `>`.
`is_test`	boolean	No	`true` marks the send as a test: it isn't added to the campaign's recipient count and schedules no follow-up email. Default `false`.
`keywords`	object	No	Values for your template's placeholders, as key/value pairs, e.g. `{"paragraph_1": "Thanks for visiting!"}`. Each key up to 100 characters; values are strings. Empty values are skipped.

This route picks its channels from the contact details you send: an email engages the Email channel, a phone engages the SMS channel. Each channel is only validated if you use it. Each channel you engage must exist, be enabled, have a template, and be within the plan's limit for the period. When no channel is usable the call returns 400 with message No valid channel to send review request and the individual causes listed in errors[] (a plan limit appears there as its own message). A location without review solicitation enabled returns 400.

Response	Cause
`Campaign does not have an active Email channel`	You sent an `email`, but there is no enabled `email` channel.
`Email channel does not have a valid template. Please add a template to the Email channel.`	The Email channel exists but has no usable template.
`Campaign does not have an active SMS channel`	You sent a `phone`, but there is no enabled `sms` channel.
`SMS channel does not have a valid template. Please add a template to the SMS channel.`	The SMS channel exists but has no usable template.

📘
A campaign built with Create or edit a campaign has no template on its channels until you attach one, so every send fails until you do. Get each channel's id from data.data.channels[].id in the step 2 or step 3 response, then attach a template to it:

Email: POST /api/v1/campaign/template/email/update with channel_id, email_template_id (the value of an entry from GET /api/v1/campaign/template/email/list, which returns {value, label} pairs), subject, html_content (or html_content_b64) and json_content ("{}" is fine). This sets the channel's template_id, or follow_up_template_id when the template's template_type is follow_up.

SMS: POST /api/v1/campaign/template/sms/update with channel_id, sms_template_id and content.
{
  "channel_id": 812,
  "email_template_id": 34,
  "subject": "How did we do?",
  "html_content": "<p>Hi [customerName], tell us how we did.</p>",
  "json_content": "{}"
}

Request payload

{
  "unique_code": "9445a2",
  "customer_name": "Jane Smith",
  "email": "<customer-email>",
  "phone": "+15555550100",
  "requester_name": "Front Desk Kiosk",
  "is_test": false,
  "keywords": {
    "visit_reason": "Routine checkup",
    "staff_member": "Dr. Smith"
  }
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`message`	string	Which channels went out: `Email and SMS review requests sent successfully`, `Email review request sent successfully` or `SMS review request sent successfully`.

Response payload

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

Examples

Success payload

Both channels sent: see Response payload. When only one channel is usable, only that one is sent:

{
  "data": {
    "status": "success",
    "message": "SMS review request sent successfully"
  }
}

Error payload

400 No usable channel

{
  "message": "No valid channel to send review request",
  "status": "error",
  "errors": [
    "Campaign does not have an active SMS channel"
  ]
}

400 No active plan

{
  "message": "Store does not have an active plan",
  "status": "error",
  "errors": []
}

400 Review site links missing

The landing page or email template links to a review site the location has no URL for. errors lists the sites, under review_site_not_found (no URL saved for the site) or landing_page_url_not_found (no landing page URL).

{
  "message": "Some review site URLs are missing for this location. Add them in Review Site URLs, then try again.",
  "status": "error",
  "errors": {
    "review_site_not_found": [
      {
        "review_site_id": 1,
        "review_site_name": "Yelp"
      }
    ]
  }
}

400 Review solicitation not enabled

{
  "message": "Review Solicitation is not enabled for this store. Please enable it in your plan or contact support for assistance.",
  "status": "error",
  "errors": []
}

403 Not an Account token

{
  "message": "This action is unauthorized."
}

404 Campaign not found

{
  "message": "Campaign not found",
  "status": "error",
  "errors": []
}

422 Fields missing

{
  "message": "The customer name field is required. (and 2 more errors)",
  "errors": {
    "customer_name": [
      "The customer name field is required."
    ],
    "email": [
      "The email field is required when phone is not present."
    ],
    "phone": [
      "The phone field is required when email is not present."
    ]
  }
}

429 Too many requests

{
  "message": "Too Many Attempts."
}

Status	Meaning
`200`	The request is queued on at least one channel.
`400`	No channel is usable (causes in `errors[]`), the location has no active plan or no review solicitation, or the template links to a review site the location has no URL for.
`401`	The token is missing, expired or invalid.
`403`	The token isn't an Account token.
`404`	The unique code matches no campaign in your account.
`422`	A field is missing or invalid.
`429`	More than 60 requests in a minute from this user.
`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": "9445a2", "customer_name": "Jane Smith", "email": "<customer-email>", "phone": "+15555550100", "requester_name": "Front Desk Kiosk", "is_test": false, "keywords": {"visit_reason": "Routine checkup", "staff_member": "Dr. Smith"}}'

Updated 17 days ago

Did this page help you?