Reviewflowz API Get an API key

Track ratings across locations and competitors

You end up with the rating of each of your locations next to your competitors' on the same platform, their history month by month, a message to your server when one of them moves, and the number of reviews it takes to pass a rival.

Run calls

Sign in to run every call on this page on your account's data. No key needed.

Before you start

  • A key with sources:write, organize:write, reviews:read, analytics:read and webhooks: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:

Source Page
src_6101 Juniper Ridge Dental, Boulder
src_6102 Juniper Ridge Dental, Denver
src_6201 Flatirons Family Dental, Boulder
src_6202 Cherry Creek Smiles, Denver

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"}'
Edit the request

POST /v3/dimensions in the reference

Example answer
{"key": "brand","label": "Brand","source_count": 0,"created_at": "2026-11-01T09:00:00Z"}​

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"}]'
Edit the request

PATCH /v3/sources/dimensions in the reference

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_..."
Edit the request

GET /v3/ratings in the reference

Example answer
{"data": [{"source": "src_6201","platform": "google_maps","score": 4.74,"count": 388,"new_ratings_7d": 3,"new_ratings_30d": 17,"score_change_7d": 0.0,"score_change_30d": 0.01,"as_of": "2026-11-10"},{"source": "src_6101","platform": "google_maps","score": 4.61,"count": 212,"new_ratings_7d": 3,"new_ratings_30d": 9,"score_change_7d": 0.01,"score_change_30d": 0.03,"as_of": "2026-11-10"}],"next_cursor": null,"has_more": false}​

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
Edit the request

GET /v3/ratings/history in the reference

Example answer
{"data": [{"source": "src_6201","platform": "google_maps","country": "worldwide","local": true,"points": [{"period": "2026-08-01","as_of": "2026-08-31","score": 4.71,"count": 340},{"period": "2026-09-01","as_of": "2026-09-30","score": 4.72,"count": 356,"new_ratings": 16},{"period": "2026-10-01","as_of": "2026-10-31","score": 4.73,"count": 383,"new_ratings": 27},{"period": "2026-11-01","as_of": "2026-11-10","score": 4.74,"count": 388,"new_ratings": 5}]},{"source": "src_6101","platform": "google_maps","country": "worldwide","local": true,"points": [{"period": "2026-08-01","as_of": "2026-08-31","score": 4.55,"count": 182},{"period": "2026-09-01","as_of": "2026-09-30","score": 4.57,"count": 194,"new_ratings": 12},{"period": "2026-10-01","as_of": "2026-10-31","score": 4.6,"count": 209,"new_ratings": 15},{"period": "2026-11-01","as_of": "2026-11-10","score": 4.61,"count": 212,"new_ratings": 3}]}],"interval": "month","from": "2026-08-01","to": "2026-11-10","next_cursor": null,"has_more": false}​

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"]}'
Edit the request

POST /v3/webhook-endpoints in the reference

Example answer
{"id": "we_12","url": "https://hooks.yourcompany.com/reviewflowz","events": ["rating.changed"],"status": "active","secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"}​

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_..."
Edit the request

GET /v3/sources/{id}/forecast in the reference

Example answer
{"id": null,"status": "ready","source": "src_6101","name": "Juniper Ridge Dental Boulder","platform": "google_maps","current": {"rating": 4.612,"displayed_rating": 4.6,"review_count": 212},"last_30_days": {"review_count": 9,"average_rating": 4.89,"capped": false},"inputs": {"target_rating": 4.7,"reviews_per_month": 9,"new_reviews_rating": 4.9,"days": 90},"projection": {"rating": 4.645,"displayed_rating": 4.6,"outcome": "gap","reviews_needed": 33,"months_needed": 3.7}}​

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

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.