Before you start
- A key with
widgets:writefor step 1,organize:writefor steps 3 and 4, andreviews:readandsources:readfor the page itself. - Your review pages added as sources: steps 1 and 2 of Find and monitor reviews for any business.
- 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. Widgets are part of the Pro plan, which Premium includes.
1. The quick way: a widget
If a ready-made layout is enough, a widget shows your reviews with nothing to build on your side.
curl https://api.reviewflowz.com/v3/widgets \-H "Authorization: Bearer rfz_live_..." \-H "Content-Type: application/json" \-d '{"name": "Reviews page","template": "masonry","sources": ["src_5101", "src_5102", "src_5201"],"count": 24,"min_rating": 5,"require_content": true,"require_reviewer": true,"tags": ["tag_12"]}'
const res = await fetch("https://api.reviewflowz.com/v3/widgets", {method: "POST",headers: {"Authorization": "Bearer rfz_live_...","Content-Type": "application/json",},body: JSON.stringify({"name": "Reviews page", "template": "masonry", "sources": ["src_5101", "src_5102", "src_5201"], "count": 24, "min_rating": 5, "require_content": true, "require_reviewer": true, "tags": ["tag_12"]}),});console.log(await res.json());
import requestsres = requests.post("https://api.reviewflowz.com/v3/widgets",headers={"Authorization": "Bearer rfz_live_...","Content-Type": "application/json",},json={"name": "Reviews page", "template": "masonry", "sources": ["src_5101", "src_5102", "src_5201"], "count": 24, "min_rating": 5, "require_content": True, "require_reviewer": True, "tags": ["tag_12"]},)print(res.json())
Edit the request
POST /v3/widgets in the reference
Example answer
Paste embed.script in your page, then embed.iframe where the reviews go. GET /v3/widgets/wdg_7 gives the same code later.
A widget shows its sources' newest reviews by date posted, up to count (1 to 100), rated min_rating or more. tags keeps the reviews with any of those tags, and require_content and require_reviewer keep the ones with text and a reviewer's name. custom_css styles it.
For a layout of your own, like Lugg's, build the page from the API: steps 2 to 7.
2. The ratings band
GET /v3/ratings gives each source's rating and review count, one row per source.
curl "https://api.reviewflowz.com/v3/ratings?source=src_5101,src_5102,src_5201,src_5301,src_5302" \-H "Authorization: Bearer rfz_live_..."
const res = await fetch("https://api.reviewflowz.com/v3/ratings?source=src_5101,src_5102,src_5201,src_5301,src_5302", {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={"source": "src_5101,src_5102,src_5201,src_5301,src_5302"},)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.
- platform
- location
- dimension[key]
- sort · score, count, new_ratings_7d, new_ratings_30d, score_change_7d,...
GET /v3/ratings in the reference
Example answer
Shortened: each row also has the change over 7 and 30 days. The app stores also rate per country: country=all lists those rows too. When a platform has several of your pages, like a listing per city here, add their counts and weight each score by its count to show one number for the platform.
3. Tag reviews by use case
Create one tag per use case. With auto_check: true, the tag is applied for you.
curl https://api.reviewflowz.com/v3/tags \-H "Authorization: Bearer rfz_live_..." \-H "Content-Type: application/json" \-d '{"name": "Furniture delivery", "auto_check": true}'
const res = await fetch("https://api.reviewflowz.com/v3/tags", {method: "POST",headers: {"Authorization": "Bearer rfz_live_...","Content-Type": "application/json",},body: JSON.stringify({"name": "Furniture delivery", "auto_check": true}),});console.log(await res.json());
import requestsres = requests.post("https://api.reviewflowz.com/v3/tags",headers={"Authorization": "Bearer rfz_live_...","Content-Type": "application/json",},json={"name": "Furniture delivery", "auto_check": True},)print(res.json())
Edit the request
POST /v3/tags in the reference
Example answer
Every new review is then read by the AI tagger, which adds the tags with auto_check that it matches. It only sees each tag's name, so name use cases the way your customers say them.
To tag the reviews you already have, open Reports → Tags in the app, click Manage tags, then Tag past reviews.
To tag a review yourself, PUT /v3/reviews/rev_7310021/tags/tag_12 the tag on it. Sending it again changes nothing, and DELETE /v3/reviews/rev_7310021/tags/tag_12 takes it off. The answer lists the review's tags.
curl -X PUT https://api.reviewflowz.com/v3/reviews/rev_7310021/tags/tag_12 \-H "Authorization: Bearer rfz_live_..."
const res = await fetch("https://api.reviewflowz.com/v3/reviews/rev_7310021/tags/tag_12", {method: "PUT",headers: {"Authorization": "Bearer rfz_live_...",},});console.log(await res.json());
import requestsres = requests.put("https://api.reviewflowz.com/v3/reviews/rev_7310021/tags/tag_12",headers={"Authorization": "Bearer rfz_live_...",},)print(res.json())
Edit the request
Reviews also carry topics: what each review talks about (topic Staff, subtopic Friendliness) and with what sentiment. These need sentiment analysis turned on once, in the app under Reports → Sentiment: it builds your topics from the reviews you have, and every new review gets them after that. GET /v3/topics lists them, and GET /v3/reviews filters on topic=, subtopic= and sentiment=positive.
4. Group by city
A city belongs to a source: give each local page its city with a custom dimension.
curl https://api.reviewflowz.com/v3/dimensions \-H "Authorization: Bearer rfz_live_..." \-H "Content-Type: application/json" \-d '{"label": "City"}'
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": "City"}),});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": "City"},)print(res.json())
Edit the request
POST /v3/dimensions in the reference
Example answer
Then set it on up to 100 sources per call. 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_5101", "city": "San Francisco"},{"source": "src_5102", "city": "Chicago"}]'
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_5101", "city": "San Francisco"}, {"source": "src_5102", "city": "Chicago"}]),});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_5101", "city": "San Francisco"}, {"source": "src_5102", "city": "Chicago"}],)print(res.json())
Edit the request
The answer lists the sources with their dimensions. A page added later takes its city in the same call that adds it: "dimensions": {"city": "Chicago"} in POST /v3/sources. GET /v3/dimensions/city/values lists the cities for your filter. If your sources already belong to locations in the app, location= filters the same way.
Reviews from a page that covers every city, like an app store's, have no city. Show them when no city is picked.
5. The wall
GET /v3/reviews takes each filter of the page. One at a time:
Together, for the Furniture delivery wall in Chicago:
curl -G https://api.reviewflowz.com/v3/reviews \-H "Authorization: Bearer rfz_live_..." \-d tag=tag_12 \-d "dimension[city]=Chicago" \-d rating_min=5 \-d has_text=true \-d text_length_min=80 \-d language=en \-d removed=false \-d sort=date \-d fields=source,rating,text,reviewer,date,tags,media \-d include=media
const res = await fetch("https://api.reviewflowz.com/v3/reviews?tag=tag_12&dimension[city]=Chicago&rating_min=5&has_text=true&text_length_min=80&language=en&removed=false&sort=date&fields=source,rating,text,reviewer,date,tags,media&include=media", {method: "GET",headers: {"Authorization": "Bearer rfz_live_...",},});console.log(await res.json());
import requestsres = requests.get("https://api.reviewflowz.com/v3/reviews",headers={"Authorization": "Bearer rfz_live_...",},params={"tag": "tag_12", "dimension[city]": "Chicago", "rating_min": "5", "has_text": "true", "text_length_min": "80", "language": "en", "removed": "false", "sort": "date", "fields": "source,rating,text,reviewer,date,tags,media", "include": "media"},)print(res.json())
Edit the request
- source · Comma-separated source ids.
- platform · Comma-separated platform ids.
- rating · Star ratings, comma-separated: rating=1,2 (4 includes 4.5).
- date_after · Posted on the platform at or after.
- updated_after · Catch up after downtime: reviews found, edited, removed,...
- limit · Rows per page (default 50).
- cursor · The next_cursor from the previous page. Leave it out for the first...
- id · Comma-separated review ids: id=rev_1 reads one review.
- location · Comma-separated location ids.
- product · Comma-separated product ids (accounts that group sources into...
- dimension[key] · Reviews of sources with this custom dimension value...
- rating_max · Scores of at most this: rating_max=3 (3.5 is out).
- date_before
- created_after · Found by Reviewflowz at or after.
- created_before
- source_created_after · Reviews of sources added at or after (bulk imports).
- owner · Comma-separated owner ids (confirmed assignments).
- topic · Comma-separated topic names.
- subtopic · Comma-separated subtopic names. With topic or sentiment, the same...
- sentiment · With topic, a mention of that topic with that sentiment.
- has_reply
- country · The reviewer's country, where the platform gives one:...
- q · Full-text search (title, text, pros, cons, reviewer); every word...
- keywords · Like q, but any of the words: keywords=refund,late.
- versions · latest lists only the current version of an edited review; all...
- columns · Comma-separated export columns (rating, date, reviewer,...
GET /v3/reviews in the reference
Example answer
Up to 500 reviews a call; next_cursor continues. reviewer.name is the name the platform shows: keep the first word for a first name. The city of each review is its source's dimensions.city, from GET /v3/sources.
6. Serve it from your server
Call the API from your server, never from the visitor's browser: the key would be in the page for anyone to copy. Give the key your server uses read permissions only. Keep the answers on your server and build the page from them, so a visit makes no API call. Step 7 tells you when to update them.
7. Keep it current
Subscribe your server to these events, as in step 4 of Find and monitor reviews:
review.tagged: a review got a tag, from you or from the AI tagger. It's how a new review joins a use-case wall: tags are added after a review is found, so itsreview.createdcan come before them.review.untagged: take it off that wall.review.updated: the reviewer edited it. Replace the review whose id is the event'sprevious_versionwith the new one.review.removed: take it off the page.review.reinstatedputs it back.rating.changed: update the band.
Back after downtime? GET /v3/reviews?updated_after= with your last check's time lists everything that changed.
What it costs and where it stops
- Automatic tags go on new reviews. The reviews you already have are tagged from the app (step 3).
- Topics and sentiment start once sentiment analysis is turned on in the app.
- A city is set per source, not per review.
- 500 reviews per call. Rate limits.
When something else fits better
If the widget's layout works for your page, step 1 is the whole job: no server, no code.