Guides

Build third-party review management

Give your customers one place to see, respond to, and grow their reviews across Google, Facebook, Yelp, and 80+ other sites, inside your product.

This guide walks the whole path from a blank partner account to a working integration: set up a customer, connect their review sites, get their reviews, post a reply. Then it shows where each optional capability plugs in. Every step links to the page that documents it in full.

Time to a working integration: an afternoon. Time to your first review collected: under an hour.

Before you start

  • A partner account. Shout About Us creates this for you when you sign; you can't create it yourself. Your dashboard login arrived by email.
  • A personal access token. In the dashboard, open API Keys and generate one. Send it on every call as Authorization: Bearer YOUR_TOKEN. It keeps working even if your dashboard login is ever locked. → Authentication
  • A plan. Shout About Us configures plans for your partner; you assign them. Each plan defines which review sites a location gets, how often reviews are collected, and which capabilities are on. You'll see yours in step 1. → Plans and entitlements

Two ideas that make everything below predictable:

  • The hierarchy: Partner (you) → Account (a business) → Locations (its stores or branches) → Review sites → Review data → Capabilities. Plans attach at the account level and every location inherits them.
  • Your own IDs: when you create an account or location, pass your identifier as client_account_id or client_location_id. Most endpoints accept it in place of ours, so you never have to store our IDs.

Step 1: See your available plans

Before creating anything, look at what you can assign.

GET /api/v1/partner/plans/list

Each plan lists its review sites, collection cadence, capabilities, and price. Pick the plan_id you'll use for this customer. If nothing fits, contact your account team; plans aren't created through the API. → Plans and entitlements

Step 2: Create the customer's account and first location

One call creates the account, its owner, its first location, and assigns the plan. The owner gets a set-password welcome email.

POST /api/v1/partner/account/create
{ "name": "Acme Plumbing", "owner_email": "[email protected]", "first_name": "Jane",
  "password": "<temporary>", "plan_id": 3, "address": "12 Main St", "city_id": 4821, "postal_code": "92008",
  "companyindustry_id": 7, "client_account_id": "ACME-001", "with_location": 1 }

The response includes the new account id. The location is created on the plan with an empty connection slot for each of the plan's review sites.

Adding more locations later: → Add and manage locations. Onboarding dozens or hundreds of customers at once: → Create and manage accounts, "Import accounts and locations from a spreadsheet."

Step 3: Connect the location's review sites

A location collects reviews from a site once it has that site's URL. Set the URL for each site the customer cares about, starting with Google.

POST /api/v1/store-review-site/update
{ "client_location_id": "ACME-001-MAIN", "review_site_id": 44,
  "url": "https://www.google.com/maps/place/..." }

Collection starts on the plan's schedule and a first collection is queued immediately. Repeat for Yelp, Facebook, and any other site on the plan. Don't know a location's URL? → Connect review sites, "Find sites missing a review URL" and the Review profile finder.

Important: this call replaces the whole connection. Always include url, even when you're only changing something else, or the URL is cleared and collection stops.

You don't need anything else for review data. Posting replies needs one more step; that's step 5.

Step 4: Get the reviews

Once the first collection has run (usually within minutes for Google), read them.

POST /api/v1/partner/report/review-response/feed
{ "client_location_id": "ACME-001-MAIN", "limit": 25, "sort_by": "desc" }

Each review comes back with the reviewer, rating, text, date, the site and location it belongs to, any existing response, its flag status, and response_capabilities, which tells you whether a manual or AI reply is possible right now and, if not, why. Build your feed from this. Filter by site, rating, date range, response status, or keyword. → Get reviews

Want to be told when a new review arrives instead of polling? → Webhooks, and see Keeping your copy in sync below.

Step 5: Let the business owner authorize replies

Reading reviews needs only a URL. Posting a reply needs the business owner's permission on each site. You don't do this for them; you send them a link and they do it.

POST /api/v1/store-review-site/send/request
{ "client_location_id": "ACME-001-MAIN", "email": "[email protected]", "name": "Jane" }

The owner gets an email with a link to your branded connection page. There they sign in to Google or Facebook, follow the manager-invite steps for Yelp and similar sites, or enter credentials for sites that use them. The link is also in the response, so you can show it in your own app instead. One invite covers every site on the location.

When they finish, each site's posting status changes to connected. Check it any time: → Connect review sites, "List a location's review sites."

Step 6: Post a reply

POST /api/v1/response/save
{ "review_id": 13383822, "response": "Thanks, Jane. We're glad the team got it sorted quickly." }

The reply is saved and queued for posting to the live site, usually within minutes. Call the same endpoint again with new text to edit it. → Respond to reviews

If the site isn't authorized yet you'll get a 422 naming connection or posting. If the plan's response allowance is used up you'll get a 402 with the details in the headers. If the text is identical to the current reply, a 400. These are the three things that stop a post, and each error says which one.

Want AI to draft it first?

POST /api/v1/account/generate-ai-response
{ "store_id": 8748, "review_id": 13383822, "tone": "grateful" }

Returns draft text and an ai_response_id. Show it to the owner, let them edit, then save it with the call above, passing the ai_response_id so they're linked. → Respond to reviews

You're integrated

That's the whole loop: a customer, a location, its sites, its reviews, a reply. Everything else is optional and plugs into this same data.

Adding capabilities

Each of these runs on the reviews you're already collecting. Turn on what your product needs; each one is available only if the location's plan includes it.

  • Flag a review for removal. Report a fake or abusive review to the site it's on, with one of that site's accepted reasons, and track the outcome. Check is_flaggable on the review first. → Flag a review for removal
  • Request more reviews. Send email, SMS, or QR review requests that drop the customer straight onto the site's review form. Requires a landing page URL per site, set in step 3. → Solicit Reviews
  • Show reviews on the customer's website. Embed a widget fed by the same data. → Widgets and display
  • Reports and insights. Ratings over time, response rates, sentiment, rankings, competitive benchmarks. → Insights
  • Know when things break. Error notifications tell you when a site's connection stops working, so you can resend the authorization link from step 5. → Error notifications

Building for many customers

  • Use your own IDs everywhere (client_account_id, client_location_id) so your system stays the source of truth.
  • Bulk onboarding: the spreadsheet import creates up to 100,000 accounts and locations in one upload and is safe to re-run. → Create and manage accounts
  • Scope: a partner token reaches every account and location under you. Users at your partner can be limited to specific accounts or locations; two users can see different lists. → Users and roles
  • Sub-partners: if you resell to other agencies, create their accounts under them with parent_company_id. Sub-partners themselves are created in the dashboard.

Keeping your copy in sync

Don't call the review feed every time a page loads. Keep the reviews in your own database and refresh them when we tell you something changed:

  1. Store reviews on your side. Load each location's reviews once with Get reviews (store_id or client_location_id, up to 100 per page) and save them.
  2. Subscribe to batch webhooks. Create a webhook with delivery_kind: batch and a batch_interval_hours that suits you (1 to 12 hours). After each window you get one cache_invalidation for every location that had new or changed reviews.
  3. Refresh only those locations. On each cache_invalidation, fetch that location's reviews again with Get reviews and update your copy. Each review comes with its response and flag status, so these refresh too. To fetch only what changed, send store_id with updated_since set to the event's window.start (as Y-m-d H:i:s, UTC) and include_removed: true.
  4. Use an immediate subscription for what you act on. Replies posted directly on a review site (response_received), failed posts, removals and disconnected sites arrive as they happen. → Webhook event catalogue
  5. Catch up with updated_since. On a schedule that suits you, for example hourly, call Get reviews with updated_since set to when your last sync started and include_removed: true, and page through with limit: 100. You get the reviews collected, edited, moderated or removed since then: update each one by its id, and delete the ones with deleted_at set. Sort with sort_field: updated_at and sort_by: asc, and start each sync a few minutes before the last one started so clock differences can't skip a change. This catches review changes a missed webhook didn't tell you. A new reply, or a change to a removal request, doesn't change updated_at: those come from step 4's webhooks, and the weekly refetch below catches any you missed.
  6. Call the KPI endpoints directly. Ratings, review counts and response rates are calculated for you, so call Headline numbers (partner) or Headline numbers (account) when you need them rather than working them out from your copy. Cache the results for a period that suits your product.

This keeps you well inside the rate limits, which matter most when one server calls the API for many customers.

What webhooks don't cover

Webhooks tell you about what we collect, so your copy can drift from what's on the review sites. Plan for it:

  • Reviews arrive when we collect them. We collect each location's reviews from its sites on the plan's schedule, not the moment they appear. A reply the business posts directly on a site also arrives with the next collection.
  • Some removals aren't detected. If a review is taken down on Google or Facebook without a removal request (flag) from you, we may not detect it, so it can stay in your copy. Most other sites are checked about once a week.
  • We can only collect what a site shows. Some sites don't publish responses at all, and some hide or filter reviews, including negative ones. What a site doesn't show publicly, we can't collect or send you.
  • Missed deliveries aren't sent again. Each event is tried up to 6 times over about 8.6 hours. If every attempt fails, the event is dropped. See recent deliveries with status=dropped lists those events, and step 5 above picks up the changes they carried.
  • Edits are reported for content changes only: a change to the rating, text, reviewer name or date.

To catch any drift, refetch every location in full on a regular schedule, for example once a week, and replace your copy. For the full refetch, page through each location with limit: 100 and no date range, following meta.last_page. A date range without limit returns everything in one response, which can be very large for a busy location, and leaves out reviews with no review date.

Where to go next

  • Build a first-party review platform [coming soon: available to approved partners]
  • Build unified first- and third-party reviews [coming soon]
  • Add review functionality to an existing product: start with Setup and Review data, then pick from Adding capabilities above.

Full endpoint reference: API Reference tab.

Updated 2 days ago

Did this page help you?