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

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.

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.