Send a review request to a customer

Overview

Send one customer a review request by email, text, or both, using a campaign's templates.

Use this for point-of-service requests, for example right after a job is finished, or to send from your own system one customer at a time.

You'll need the campaign_id, the customer's name, and their email and/or phone.

The message is queued and sent within minutes. Delivery and clicks show in Campaign reporting. Counts against your plan's email and SMS allowances; when an allowance is used up the call returns 402.

If one channel is usable and the other isn't, the call still returns 200 and sends only the usable channel; data.message tells you which went out, and the other channel's problem isn't reported.

Prerequisites

• A bearer token. See Authentication.
• A campaign (campaign_id) in your account whose Email and/or SMS channel is enabled and has a template.
• An active plan on the campaign's location.

Base URL

Endpoint

POST /api/v1/campaign/review-request

Authentication

Account token

• The campaign must belong to your own account; otherwise 403 (You are not authorized to send a review request for this campaign).
• The campaign's location must have an active plan; otherwise 400.

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.

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, so an SMS-only send needs no email template, and vice versa. Each channel you engage must exist, be enabled, and have a template. You get 400 only when no channel is usable, and then the causes are joined with ; :

Request payload

{
  "campaign_id": 4823,
  "customer_name": "Jane Smith",
  "email": "<customer-email>",
  "phone": "+15555550100",
  "is_test": false,
  "keywords": {
    "paragraph_1": "Thanks for visiting our store today!"
  }
}

Response body

The payload is inside data.

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": "Email review request sent successfully"
  }
}

Error payload

400 No usable channel

{
  "message": "Bad 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": "One or more review site URLs are missing in the landing page or email template.",
  "status": "error",
  "errors": {
    "review_site_not_found": [
      {
        "review_site_id": 1,
        "review_site_name": "Yelp"
      }
    ]
  }
}

402 Plan allowance used up

{
  "status": "error",
  "message": "Limit reached for 'Email Solicitations': 500 of 500 units consumed this period.",
  "feature": "review_solicitation_email",
  "remaining": 0,
  "hard_stop": true
}

403 Campaign outside your account

{
  "message": "You are not authorized to send a review request for this campaign",
  "status": "error",
  "errors": []
}

422 Fields missing

{
  "message": "The campaign id field is required. (and 3 more errors)",
  "errors": {
    "campaign_id": [
      "The campaign id field is required."
    ],
    "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."
    ]
  }
}

422 Email rejected

{
  "message": "The email field must be a valid email address.",
  "errors": {
    "email": [
      "The email field must be a valid email address."
    ]
  }
}

429 Too many requests

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

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/campaign/review-request" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"campaign_id": 4823, "customer_name": "Jane Smith", "email": "<customer-email>", "phone": "+15555550100", "is_test": false, "keywords": {"paragraph_1": "Thanks for visiting our store today!"}}'