Getting Started

Build with Shout About Us

Shout About Us provides the APIs and infrastructure to build first-party and third-party review experiences directly into your marketplace, SaaS platform, or application.

Collect and manage first-party reviews, connect reviews from 80+ third-party sites, respond and publish replies, request new reviews, verify authenticity, run moderation and dispute workflows that fit your policies, and turn review data into insights, without building and maintaining the infrastructure yourself.

Start with review data. Add the capabilities your product needs.

Your product. Your customer experience. Our review infrastructure.

What are you building?

One integration. Modular capabilities.

You build the interface and decide how review management works for your customers. Shout About Us handles what's underneath: site integrations, one normalized data model, authentication, review collection, verification and moderation workflows, posting, and ongoing maintenance.

Works with 80+ review sites

Google, Facebook, Yelp, BBB, Trustpilot, TripAdvisor, OpenTable, Angi, Houzz, Zillow, Airbnb, Expedia, Healthgrades, DealerRater, CarGurus — and 80+ more. Every location connects its own review sites; the API normalizes them so you work with one shape.

How the platform is organized

Everything in Shout About Us sits in a simple hierarchy. Understanding it makes every endpoint predictable.

• Partner: you. Your partner account is created by Shout About Us when you sign your agreement; you don't create it and you can't create additional top-level partners. If you manage other agencies or resellers, you can set up sub-partners under your own account from the dashboard.
• Account: a business, brand, or any grouping of locations that share a plan. You create these. Every location belongs to one.
• Plan: assigned to an account by you, from the plans Shout About Us has configured for your partner. A plan defines which review sites a location gets, how often reviews are collected from each, which capabilities are enabled, and the price. Every location under the account inherits all of it. You can't create or edit plans through the API; you can see what's in them and assign them.
• Location: a store, office, branch, or service area. This is where reviews attach.
• Review sites: the sources a location's reviews come from (its Google profile, Yelp page, and so on). Which sites and how often they're checked come from the plan; you supply the location's URL on each.
• Review data: the normalized reviews collected from those sites. Everything else runs on this.
• Capabilities: what you do with the data. Respond, draft with AI, flag, request more reviews, verify, moderate, analyze, embed. Which ones are on comes from the plan.

Your token decides your reach. A partner token can act on everything beneath it; an account token is limited to its own account and locations.

Use your own IDs. When you create an account or location, you can attach your own identifier (client_account_id, client_location_id). Most endpoints accept it in place of ours, so you never have to store our IDs in your system.

Only need part of it? Start with Setup and Review Data. Everything after that is optional.

Get started in 5 minutes

Five steps take you from a new token to reading real reviews. You'll need a partner token and a terminal with curl.

Before you start: use the right server. A token only works on the environment that issued it. A production token goes to https://production-api.shoutaboutus.com, a development token to https://development-api.shoutaboutus.com. Send it to the other one and every call returns 401. See Environments. The example below sets both once, so you only change them in one place.

1. Check your token. GET /api/v1/verify-token returns your user and company. If you get 401, the token is wrong or you're on the wrong server.

2. Look up the IDs you'll need. Creating an account takes IDs, not names:

• plan_id — List your plans
• companyindustry_id — List industries
• city_id — List countries, then List states with country_code, then List cities with country_code and state_code

3. Create an account and its first location. POST /api/v1/partner/account/create with with_location: 1. One call creates the account, a first location on your chosen plan, and a login for the business owner, who gets a welcome email at owner_email. The response gives you the account's id (accountId.value). To get the new location's store_id for the next step, call List all locations under your partner with that account_id.

4. Connect a review site. POST /api/v1/store-review-site/update with the store_id, a review_site_id (44 is Google; List supported review sites has the rest), and the url of the location's public page on that site. This switches review collection on. Collection runs on your plan's schedule, so the first reviews take a little while to arrive.

5. Get your reviews. POST /api/v1/partner/report/review-response/feed with the store_id. It returns 10 reviews per page, each with its response status. If it's empty, collection hasn't finished its first run yet; try again later.

# Set these once
BASE_URL="https://production-api.shoutaboutus.com"   # or https://development-api.shoutaboutus.com
TOKEN="YOUR_TOKEN"

# 1. Check your token
curl -s "$BASE_URL/api/v1/verify-token" \
  -H "Authorization: Bearer $TOKEN"

# 2. Look up the IDs you need
curl -s "$BASE_URL/api/v1/partner/plans/list" -H "Authorization: Bearer $TOKEN"
curl -s "$BASE_URL/api/v1/partner/account/industries" -H "Authorization: Bearer $TOKEN"
curl -s "$BASE_URL/api/v1/address/states?country_code=US" -H "Authorization: Bearer $TOKEN"
curl -s "$BASE_URL/api/v1/address/cities?country_code=US&state_code=CA" -H "Authorization: Bearer $TOKEN"

# 3. Create an account and its first location
curl -s -X POST "$BASE_URL/api/v1/partner/account/create" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Brand",
    "address": "123 Brand Street",
    "city_id": 123,
    "postal_code": "10001",
    "companyindustry_id": 123,
    "first_name": "John",
    "owner_email": "[email protected]",
    "password": "<your-password>",
    "plan_id": 123,
    "with_location": 1
  }'

#    ...then find the new location's store_id
curl -s "$BASE_URL/api/v1/partner/store/list?account_id=456" \
  -H "Authorization: Bearer $TOKEN"

# 4. Connect a review site (44 = Google)
curl -s -X POST "$BASE_URL/api/v1/store-review-site/update" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "store_id": 619,
    "review_site_id": 44,
    "url": "https://www.google.com/maps/place/Demo"
  }'

# 5. Get your reviews
curl -s -X POST "$BASE_URL/api/v1/partner/report/review-response/feed" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"store_id": 619}'

Same token, same data envelope, everywhere. Use your own IDs if you prefer: pass client_account_id or client_location_id in place of ours on most calls (see Find your IDs).

Pagination

List endpoints take a page size as limit or per_page, plus page. The same rules apply everywhere:

• Range 10–100. A value above 100 returns 422 with "The limit field must not be greater than 100." (or per page). A value below 10 is raised to 10.
• Leave it out for the default. Each endpoint's default is listed on its page, and a few are below 10 (for example 5).
• Some endpoints allow less than 100. Their pages say so. Most reject a larger value with 422; the review feed lowers it for eligible partners instead.
• Check what you got. Paginated responses include per_page, the page size actually used.

Explore the API

The sidebar is organized by what you're doing, in the order you'll do it. Open any page for its endpoints, each with a ready-to-run example.

Where to go next

The path most integrations follow, in order:

1. Find your IDs
2. Connect review sites
3. Get reviews
4. Respond to reviews
5. Solicit Reviews
6. Insights

Prefer to explore hands-on? Open the API Reference in the sidebar for an interactive "Try It" console, or import the Postman collection:

• ⬇ Postman collection
• ⬇ Matching environment

_{Questions? Reach the team, or explore the full API in the sidebar.}