Before you start
- A key with
sources:write,organize:write,reviews:read,analytics:readandwebhooks:write. - The API is part of the Premium plan (see pricing). API-only plans start at $300 a month: book a 30-minute call for a custom quote.
The example follows a made-up dental group, Juniper Ridge Dental, with a clinic in Boulder and one in Denver, and a rival clinic in each city.
1. Add your pages and your competitors'
Add your own review pages and your competitors' the same way: steps 1 and 2 of Find and monitor reviews for any business. Keep each source's id. Here:
2. Group them
Create a custom dimension for each way you want to compare: here, the brand and the city.
curl https://api.reviewflowz.com/v3/dimensions \-H "Authorization: Bearer rfz_live_..." \-H "Content-Type: application/json" \-d '{"label": "Brand"}'
const res = await fetch("https://api.reviewflowz.com/v3/dimensions", {method: "POST",headers: {"Authorization": "Bearer rfz_live_...","Content-Type": "application/json",},body: JSON.stringify({"label": "Brand"}),});console.log(await res.json());
import requestsres = requests.post("https://api.reviewflowz.com/v3/dimensions",headers={"Authorization": "Bearer rfz_live_...","Content-Type": "application/json",},json={"label": "Brand"},)print(res.json())
Edit the request
POST /v3/dimensions in the reference
Example answer
Do the same with {"label": "City"}, whose key is city.
Then set both on every source in one call, up to 100 sources at a time. A string sets the value, null clears it, and nothing is written unless every row is valid.
curl -X PATCH https://api.reviewflowz.com/v3/sources/dimensions \-H "Authorization: Bearer rfz_live_..." \-H "Content-Type: application/json" \-d '[{"source": "src_6101", "brand": "Juniper Ridge Dental", "city": "Boulder"},{"source": "src_6102", "brand": "Juniper Ridge Dental", "city": "Denver"},{"source": "src_6201", "brand": "Flatirons Family Dental", "city": "Boulder"},{"source": "src_6202", "brand": "Cherry Creek Smiles", "city": "Denver"}]'
const res = await fetch("https://api.reviewflowz.com/v3/sources/dimensions", {method: "PATCH",headers: {"Authorization": "Bearer rfz_live_...","Content-Type": "application/json",},body: JSON.stringify([{"source": "src_6101", "brand": "Juniper Ridge Dental", "city": "Boulder"}, {"source": "src_6102", "brand": "Juniper Ridge Dental", "city": "Denver"}, {"source": "src_6201", "brand": "Flatirons Family Dental", "city": "Boulder"}, {"source": "src_6202", "brand": "Cherry Creek Smiles", "city": "Denver"}]),});console.log(await res.json());
import requestsres = requests.patch("https://api.reviewflowz.com/v3/sources/dimensions",headers={"Authorization": "Bearer rfz_live_...","Content-Type": "application/json",},json=[{"source": "src_6101", "brand": "Juniper Ridge Dental", "city": "Boulder"}, {"source": "src_6102", "brand": "Juniper Ridge Dental", "city": "Denver"}, {"source": "src_6201", "brand": "Flatirons Family Dental", "city": "Boulder"}, {"source": "src_6202", "brand": "Cherry Creek Smiles", "city": "Denver"}],)print(res.json())
Edit the request
The answer lists the four sources with their dimensions. A page you add later takes its groups in the same call that adds it: "dimensions": {"brand": "Juniper Ridge Dental", "city": "Aurora"} in POST /v3/sources. GET /v3/dimensions/brand/values lists each brand with its number of sources.
3. Compare the ratings
GET /v3/ratings gives each source's rating and review count today, and how they moved over 7 and 30 days. Filter it with the groups from step 2. Everyone in Boulder, best rating first:
curl "https://api.reviewflowz.com/v3/ratings?dimension[city]=Boulder&sort=-score" \-H "Authorization: Bearer rfz_live_..."
const res = await fetch("https://api.reviewflowz.com/v3/ratings?dimension[city]=Boulder&sort=-score", {method: "GET",headers: {"Authorization": "Bearer rfz_live_...",},});console.log(await res.json());
import requestsres = requests.get("https://api.reviewflowz.com/v3/ratings",headers={"Authorization": "Bearer rfz_live_...",},params={"dimension[city]": "Boulder", "sort": "-score"},)print(res.json())
Edit the request
- limit · Rows per page (default 50).
- cursor · The next_cursor from the previous page. Leave it out for the first...
- country · worldwide, all, or ISO codes: US,DE.
- source
- platform
- location
- dimension[key]
GET /v3/ratings in the reference
Example answer
Shortened: each row also has country, local, origin, and stars on platforms that have star counts. new_ratings_30d is the number of ratings added in the 30 days before as_of, and score_change_30d how far the score moved. Scores have two decimals. On Google Maps and Tripadvisor, the score is computed from the reviews.
Every location of yours, the one that dropped most over 30 days first: dimension[brand]=Juniper Ridge Dental&sort=score_change_30d. sort also takes count, new_ratings_7d, new_ratings_30d and score_change_7d, with - for descending.
GET /v3/ratings/history gives the same numbers over time: one series per source, a point per day, week or month. Each point is the last rating of that period, and new_ratings counts the ratings added since the point before.
curl -G https://api.reviewflowz.com/v3/ratings/history \-H "Authorization: Bearer rfz_live_..." \-d source=src_6101,src_6201 \-d interval=month \-d from=2026-08-01 \-d to=2026-11-10
const res = await fetch("https://api.reviewflowz.com/v3/ratings/history?source=src_6101,src_6201&interval=month&from=2026-08-01&to=2026-11-10", {method: "GET",headers: {"Authorization": "Bearer rfz_live_...",},});console.log(await res.json());
import requestsres = requests.get("https://api.reviewflowz.com/v3/ratings/history",headers={"Authorization": "Bearer rfz_live_...",},params={"source": "src_6101,src_6201", "interval": "month", "from": "2026-08-01", "to": "2026-11-10"},)print(res.json())
Edit the request
- limit · Sources per page.
- cursor · The next_cursor from the previous page. Leave it out for the first...
- country
- platform
- location
- dimension[key]
GET /v3/ratings/history in the reference
Example answer
Without from and to, you get the last 90 days. One call covers up to 731 days and up to 50 sources: pass next_cursor back as cursor for the next ones.
4. Be told when a rating moves
Subscribe a URL of yours to rating.changed:
curl https://api.reviewflowz.com/v3/webhook-endpoints \-H "Authorization: Bearer rfz_live_..." \-H "Content-Type: application/json" \-d '{"url": "https://hooks.yourcompany.com/reviewflowz","events": ["rating.changed"]}'
const res = await fetch("https://api.reviewflowz.com/v3/webhook-endpoints", {method: "POST",headers: {"Authorization": "Bearer rfz_live_...","Content-Type": "application/json",},body: JSON.stringify({"url": "https://hooks.yourcompany.com/reviewflowz", "events": ["rating.changed"]}),});console.log(await res.json());
import requestsres = requests.post("https://api.reviewflowz.com/v3/webhook-endpoints",headers={"Authorization": "Bearer rfz_live_...","Content-Type": "application/json",},json={"url": "https://hooks.yourcompany.com/reviewflowz", "events": ["rating.changed"]},)print(res.json())
Edit the request
POST /v3/webhook-endpoints in the reference
Example answer
Keep the secret: it signs every event (Webhooks shows how to check it).
Each time a source's rating or review count changes, your URL gets an event. Its data.object is the source, with its dimensions. Beside it, rating, review_count and date are the new values, and previous holds the ones before. Your competitors' sources send it too.
5. See what it takes to pass them
GET /v3/sources/src_6101/forecast works out how many reviews a Google Maps or Tripadvisor source needs to show a target rating, and where its rating lands after days at a given pace. Flatirons shows 4.7 in Boulder. What does Juniper Ridge need to show 4.7 too?
curl "https://api.reviewflowz.com/v3/sources/src_6101/forecast?target_rating=4.7" \-H "Authorization: Bearer rfz_live_..."
const res = await fetch("https://api.reviewflowz.com/v3/sources/src_6101/forecast?target_rating=4.7", {method: "GET",headers: {"Authorization": "Bearer rfz_live_...",},});console.log(await res.json());
import requestsres = requests.get("https://api.reviewflowz.com/v3/sources/src_6101/forecast",headers={"Authorization": "Bearer rfz_live_...",},params={"target_rating": "4.7"},)print(res.json())
Edit the request
- reviews_per_month · New reviews a month. Default: the last 30 days' count.
- new_reviews_rating · The new reviews' average. Default: the last 30 days' average.
- days · How far ahead. Default: 90.
GET /v3/sources/{id}/forecast in the reference
Example answer
Shortened: the answer also has the source's url. The inputs you leave out take the pace of the last 30 days: 9 reviews a month, averaging 4.9. At that pace, Boulder still shows 4.6 after 90 days (outcome: gap). It needs 33 more reviews to show 4.7: about 3.7 months.
outcome is on_track when the rating reaches the target within days, gap when it gets there later, and unreachable when new reviews don't come in, or average below the target. Change reviews_per_month, new_reviews_rating or days to try another pace. Run it on a rival's source to see where their rating is heading.
For a business you haven't added, POST /v3/forecasts takes its Google Maps link. Each call counts toward a daily allowance, which GET /v3/usage shows.
What it costs and where it stops
- A competitor's page is a source like yours. On a plan billed per source, each source past the paid number upgrades the plan at once (step 2 of the monitoring guide).
- 500 rows per
GET /v3/ratingspage.GET /v3/ratings/history: 50 sources per page, 731 days per call. - Forecasts work on Google Maps and Tripadvisor sources: another source answers
422not_forecastable, and one with no reviews yet422no_reviews.POST /v3/forecastscounts toward a daily allowance. - Rate limits.
When something else fits better
To check one location's forecast now and then, you need no code: open Reports → Forecast in the app and pick the review profile. It shows the same numbers.