A live example: Lugg
Lugg, a moving and delivery company, built lugg.com/reviews with this API. A visitor picks a use case and a city and sees the reviews that match, chosen by AI tags (step 3). About 6 to 9% of Lugg's new users land on a lugg.com/reviews page first.
Before you start
- A key with
reviews:read,organize:read(tags, owners, dimensions) andsources:read(cities and products). Addorganize:writeif your code tags reviews. - 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. Topics and owners are part of the same plan.
1. Learn the account's vocabulary
Before you write a filter, read what this account has. These calls are cheap and change rarely:
curl https://api.reviewflowz.com/v3/tags \-H "Authorization: Bearer rfz_live_..."
const res = await fetch("https://api.reviewflowz.com/v3/tags", {method: "GET",headers: {"Authorization": "Bearer rfz_live_...",},});console.log(await res.json());
import requestsres = requests.get("https://api.reviewflowz.com/v3/tags",headers={"Authorization": "Bearer rfz_live_...",},)print(res.json())
Edit the request
- q
2. Turn each page into filters
Every page is one call to GET /v3/reviews. Filters you add all apply together. Commas inside one filter mean any of them: tag=tag_12,tag_13 is reviews with either tag.
Add these to almost every page:
rating_min=4orrating_min=5.has_text=trueandtext_length_min=20: a testimonial needs words.text_length_mincounts words, title included, not characters.removed=false: leaves out reviews the platform took down.date_after=2025-01-01: nothing older than you want to show.
An edited review comes back once, as its latest version, with a new id. Tags you put on by hand stay on the old version: on review.updated, put them back on the new one (the old id is its previous_version). AI tags are added to the new version on their own.
There is no "not" filter. To leave reviews out, tag them (step 3) and drop the ones carrying that tag on your side: each review lists its tags. The same goes for "both tags": ask for one, keep the reviews whose tags also have the other.
3. Choose which reviews: by hand, by AI, or by topic
Three ways to say which reviews belong on a page. Most sites mix them.
By hand
Create a tag per purpose: Featured, Homepage, Hide from website.
curl https://api.reviewflowz.com/v3/tags \-H "Authorization: Bearer rfz_live_..." \-H "Content-Type: application/json" \-d '{"name": "Featured"}'
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": "Featured"}),});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": "Featured"},)print(res.json())
Edit the request
POST /v3/tags in the reference
Example answer
Anyone on the team can then put the tag on a review, wherever they read it:
curl -X PUT https://api.reviewflowz.com/v3/reviews/rev_7310021/tags/tag_21 \-H "Authorization: Bearer rfz_live_..."
const res = await fetch("https://api.reviewflowz.com/v3/reviews/rev_7310021/tags/tag_21", {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_21",headers={"Authorization": "Bearer rfz_live_...",},)print(res.json())
Edit the request
By AI
Give a tag auto_check: true and the AI reads every new review and adds the tag when it fits.
curl -X PATCH https://api.reviewflowz.com/v3/tags/tag_12 \-H "Authorization: Bearer rfz_live_..." \-H "Content-Type: application/json" \-d '{"auto_check": true}'
const res = await fetch("https://api.reviewflowz.com/v3/tags/tag_12", {method: "PATCH",headers: {"Authorization": "Bearer rfz_live_...","Content-Type": "application/json",},body: JSON.stringify({"auto_check": true}),});console.log(await res.json());
import requestsres = requests.patch("https://api.reviewflowz.com/v3/tags/tag_12",headers={"Authorization": "Bearer rfz_live_...","Content-Type": "application/json",},json={"auto_check": True},)print(res.json())
Edit the request
- It sees only the tag's name. Name it the way customers talk:
Furniture delivery, notSKU-FD. - With 4 or more AI tags, a review that matches every one of them gets none, since the AI is then over-tagging.
It tags new reviews only. For the reviews you already have, open Reports → Tags in the app, click Manage tags, then Tag past reviews.
By topic
Topics need no tagging: once sentiment analysis is turned on in the app under Reports → Sentiment, every review gets what it talks about and how. topic=Staff&sentiment=positive keeps reviews where staff is praised, even if the same review complains about parking.
For a short pull quote instead of a whole review, GET /v3/excerpts gives the sentence itself, with the review it comes from:
curl -G https://api.reviewflowz.com/v3/excerpts \-H "Authorization: Bearer rfz_live_..." \-d topic=Delivery \-d sentiment=positive \-d rating_min=5 \-d language=en
const res = await fetch("https://api.reviewflowz.com/v3/excerpts?topic=Delivery&sentiment=positive&rating_min=5&language=en", {method: "GET",headers: {"Authorization": "Bearer rfz_live_...",},});console.log(await res.json());
import requestsres = requests.get("https://api.reviewflowz.com/v3/excerpts",headers={"Authorization": "Bearer rfz_live_...",},params={"topic": "Delivery", "sentiment": "positive", "rating_min": "5", "language": "en"},)print(res.json())
Edit the request
- subtopic · Comma-separated subtopic names.
- id · Comma-separated review ids, up to 500.
- source · Comma-separated source ids.
- platform · Comma-separated platform ids.
- 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...
- source_created_after · Reviews of sources added at or after.
- rating · Star ratings of the review, comma-separated: rating=1,2 (4 includes...
- rating_max · Reviews scored at most this: rating_max=3 (3.5 is out).
- date_after · Reviews posted on the platform at or after.
- date_before · Reviews posted on the platform before.
- created_after · Reviews found by Reviewflowz at or after.
- created_before · Reviews found by Reviewflowz before.
- updated_after · Reviews found, edited, removed, reinstated, replied to, tagged or...
- country · The reviewer's country, where the platform gives one:...
- tag · Comma-separated tag ids: reviews with any of them.
- owner · Comma-separated owner ids (confirmed assignments).
- has_reply · Reviews with a live reply (true) or with none (false). A draft...
- removed · Reviews the platform took down (true), or the ones still up (false).
- q · Full-text search of the review (title, text, pros, cons, reviewer);...
- keywords · Like q, but any of the words: keywords=refund,late.
- has_text · Reviews with written text (true) or a rating alone (false).
- text_length_min · At least this many words, title, text, pros and cons together.
- versions · latest reads only the current version of an edited review; all...
- limit · Rows per page: 1 to 500 (default 50).
- cursor · The next_cursor from the previous page. Leave it out for the first...
4. Get the right language
Each review's language is an ISO 639-1 code like en or fr. Where the platform says which language a review is in (Tripadvisor, Yelp, the Play Store and others), that's the one you get, whatever its length. Otherwise it's detected from the text, which takes 31 characters or more: a shorter review whose platform gives no language has none, so language= leaves it out. Detection never sets Chinese, so language=zh finds only reviews whose platform said they're in Chinese.
A review gets its word count, and a detected language, shortly after it's found. Until then, text_length_min= leaves it out, so a feed built right after a review.created may not show it yet.
- One language per page:
language=fron the French site. - Fallback:
language=fr,enreturns both. Put the French ones first on your side. - Translations: the API gives each review as it was written, not translated. If you translate one yourself, say so on the page: "Translated from German".
- Language and country are different:
country=CAandlanguage=frtogether are French-speaking reviewers from Canada.
5. Pull a pool, then rank it yourself
The API sorts by newest only: newest found (the default) or newest posted (sort=date). There is no "best first". Ask for more than you show, up to 500 a call, and pick on your side.
curl -G https://api.reviewflowz.com/v3/reviews \-H "Authorization: Bearer rfz_live_..." \-d tag=tag_12 \-d rating_min=5 \-d has_text=true \-d text_length_min=20 \-d language=en \-d removed=false \-d sort=date \-d limit=100 \-d fields=source,platform,rating,title,text,pros,cons,reviewer,url,date,tags
const res = await fetch("https://api.reviewflowz.com/v3/reviews?tag=tag_12&rating_min=5&has_text=true&text_length_min=20&language=en&removed=false&sort=date&limit=100&fields=source,platform,rating,title,text,pros,cons,reviewer,url,date,tags", {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", "rating_min": "5", "has_text": "true", "text_length_min": "20", "language": "en", "removed": "false", "sort": "date", "limit": "100", "fields": "source,platform,rating,title,text,pros,cons,reviewer,url,date,tags"},)print(res.json())
Edit the request
- id · Comma-separated review ids, up to 500: id=rev_1 reads one review. A...
- source · Comma-separated source ids.
- platform · Comma-separated platform ids.
- 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...
- source_created_after · Reviews of sources added at or after (bulk imports).
- rating · Star ratings, comma-separated: rating=1,2 (4 includes 4.5).
- rating_max · Scores of at most this: rating_max=3 (3.5 is out).
- date_after · Posted on the platform at or after.
- date_before · Posted on the platform before.
- created_after · Found by Reviewflowz at or after.
- created_before · Found by Reviewflowz before.
- updated_after · Catch up after downtime: reviews found, edited, removed,...
- country · The reviewer's country, where the platform gives one:...
- 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 · Reviews with a live reply (true), posted from Reviewflowz or found...
- q · Full-text search (title, text, pros, cons, reviewer). Every word...
- keywords · Like q, but any of the words: keywords=refund,late.
- include · Parts to add to each review, comma-separated: `media` (the...
- columns · Comma-separated export columns (rating, date, reviewer,...
- versions · latest lists only the current version of an edited review; all...
- cursor · The next_cursor from the previous page. Leave it out for the first...
GET /v3/reviews in the reference
Example answer
Ask for title, pros and cons too: on G2, TrustRadius and other software sites, the words are in pros and cons and text can be null.
A ranking that works on most pages:
- Reviews tagged
Featuredfirst. Drop the ones taggedHide from website. - Then by length: 25 to 70 words reads best in a card.
- Then newest first.
- No more than two from the same source, so one listing doesn't fill the page.
- Across the page, show a review once: keep the
ids you've used.
6. When too few reviews match
A new product or a small city may have two reviews where you need six. Try your filters from strict to loose, and stop as soon as you have enough:
const tries = [{ tag: "tag_12", "dimension[city]": "Chicago", rating_min: 5, text_length_min: 20 },{ tag: "tag_12", rating_min: 5, text_length_min: 20 }, // drop the city{ tag: "tag_12", rating_min: 4, text_length_min: 10 }, // loosen rating and length{ rating_min: 5, text_length_min: 20 }, // any use case];
Keep language and removed=false in every try: a review in the wrong language is worse than one fewer review. If the last try still comes up short, show fewer cards rather than an empty section.
7. Pull at build time
On a static site (Astro, Next.js, Hugo, Eleventy...), fetch the reviews while the site builds. The key stays in the build's environment and never reaches the page.
// src/lib/reviews.js: Astro, Next.js or any Node buildconst API = "https://api.reviewflowz.com/v3/reviews";// Astro reads .env through import.meta.env; Next.js and plain Node through process.env.const KEY = import.meta.env?.REVIEWFLOWZ_KEY ?? process.env.REVIEWFLOWZ_KEY;const answers = new Map(); // one call per filter set, shared by every page that uses itexport function reviewsFor(filters, count = 6) {const query = new URLSearchParams({language: "en", removed: "false", has_text: "true", sort: "date", limit: "100",fields: "source,platform,rating,title,text,pros,cons,reviewer,url,date,tags",...filters,}).toString();if (!answers.has(query)) answers.set(query, get(query));return answers.get(query).then((data) => rank(data).slice(0, count));}async function get(query) {for (;;) {const res = await fetch(`${API}?${query}`, { headers: { Authorization: `Bearer ${KEY}` } });if (res.status === 429) { // 300 calls a minute: wait as told, then retryawait new Promise((r) => setTimeout(r, Number(res.headers.get("Retry-After") || 5) * 1000));continue;}if (!res.ok) throw new Error(`Reviewflowz ${res.status}: ${await res.text()}`);return (await res.json()).data;}}// Step 5's ranking. Featured first, hidden out, then length, then newest.function rank(reviews) {const words = (r) => [r.title, r.text, r.pros, r.cons].join(" ").split(/\s+/).filter(Boolean).length;const fits = (r) => words(r) >= 25 && words(r) <= 70;const has = (r, name) => r.tags.some((t) => t.name === name);const perSource = {};return reviews.filter((r) => !has(r, "Hide from website")).sort((a, b) => has(b, "Featured") - has(a, "Featured") || fits(b) - fits(a) || b.date.localeCompare(a.date)).filter((r) => (perSource[r.source] = (perSource[r.source] || 0) + 1) <= 2);}
reviewsFor makes one call per filter set, not per page: pages that share filters share the answer. Every key on the account shares 300 calls a minute; past that, the API answers 429 with Retry-After, and get waits and retries. Any other error fails the build, rather than publish a page with no reviews.
To rebuild when reviews change, send these webhooks to a small endpoint of yours that starts your host's build hook (Netlify, Vercel and Cloudflare Pages all give you one URL that starts a build):
review.taggedandreview.untagged: a review joined or left a tag, by hand or by the AI.review.created: a new review, if your pages show the newest.review.removedandreview.updated: a review you show was taken down or edited.
Each event is its own call: a new review with two AI tags is one review.created and two review.tagged. So don't forward each one to the build hook. Have your endpoint start at most one build an hour, or skip webhooks and rebuild every night.
8. Or serve them live, with your own cache
Every answer carries a weak ETag and Cache-Control: max-age=0, private, must-revalidate. Send the ETag back as If-None-Match: an answer that hasn't changed comes back 304 with no body. That saves the download, not the call: it still counts toward the 300 a minute. So cache on your server:
- Keep each filter set's answer for 15 to 60 minutes, keyed by its query string. Revalidate it with
If-None-Matchwhen it expires. - Clear it when one of the webhooks in step 7 arrives.
- Call the API from your server only, never from the visitor's browser: the key would be in the page for anyone to copy.
9. Show each review honestly
Don't change a review's words. To shorten one, use an excerpt from step 3.
For AI agents adding testimonials
- Read the vocabulary first (step 1). Reuse an existing tag; don't create a near-duplicate.
- Write down, for each page, the filters you'll use and the number of reviews it shows.
- Ask before you create tags or tag reviews: the whole team sees them in the app.
- Always set
language,removed=falseandhas_text=true.text_length_minis in words. - Pull a pool of about 100, rank it (step 5), and try looser filters when too few match (step 6).
- Fetch at build time or on the server. Never put the key in browser code.
- Print, at the end, which filters each page used and how many reviews each one got.
What it costs and where it stops
- Up to 500 reviews a call, sorted newest first only.
- No "not" filter and no translations: both are done on your side.
- A
304still counts as a call: cache on your server. - An edited review loses the tags you put on by hand.
- AI tags go on new reviews; past reviews are tagged from the app.
- A short review has a language only when its platform gives one.
- Rate limits.
When something else fits better
- A ready-made layout with no code: the widget in Show reviews on your website.
- Your rating on each platform next to the reviews: step 2 of the same guide.