Reviewflowz API Get an API key

Build a testimonial feed for every page

You end up with, for each page of your site, a set number of reviews that fit that page: its product or use case, its city, its language, the thing it sells. Your build or your server pulls them from the API; the layout is yours.

Run calls

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

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) and sources:read (cities and products). Add organize:write if 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:

Call Gives you
GET /v3/tags Every tag, with how many reviews carry it and whether the AI applies it (auto_check)
GET /v3/topics The topics and subtopics found in the reviews (Staff, Delivery, Price...)
GET /v3/sources Each review page, with its location, product and custom dimensions
GET /v3/dimensions/city/values The values of one custom dimension, here city
GET /v3/owners Your staff, as reviews get credited to them
curl https://api.reviewflowz.com/v3/tags \-H "Authorization: Bearer rfz_live_..."
Edit the request

GET /v3/tags in the reference

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.

Page Filters
Homepage rating_min=5&has_text=true&text_length_min=25
A product or use case tag=tag_12 (a tag you or the AI put on reviews)
A city or branch dimension[city]=Chicago, or location=loc_3
A product sold on several pages product=prd_5 (the product of each source)
A team member owner=own_4: reviews credited to that person
A feature or promise topic=Delivery&sentiment=positive: reviews that praise delivery
A narrower promise subtopic=Speed&sentiment=positive
A word that must appear q=sofa (every word), keywords=sofa,couch (any word)
A language version of the site language=fr
A country version country=FR: the reviewer's country, when the platform gives it
A platform badge platform=trustpilot

Add these to almost every page:

  • rating_min=4 or rating_min=5.
  • has_text=true and text_length_min=20: a testimonial needs words. text_length_min counts 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: tags By AI: tags with auto_check Topics
You decide Each review The tag's name Nothing
New reviews Wait for someone Tagged as they arrive Get topics as they arrive
Best for "Featured" picks, reviews to hide Use cases, products, services Features and promises: speed, price, staff
Filter tag= tag= topic=, subtopic=, sentiment=

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

POST /v3/tags in the reference

Example answer
{"id": "tag_21","name": "Featured","auto_check": false,"review_count": 0,"created_at": "2026-11-01T09:00:00Z"}​

Anyone on the team can then put the tag on a review, wherever they read it:

Where How
Reviewflowz app Add tag… on any review
Slack Update Tags on a review notification
Microsoft Teams Tag on a review card
Claude, or any AI assistant connected to Reviewflowz Ask it: "tag the last three 5-star reviews that mention installation as Featured"
The API PUT /v3/reviews/rev_7310021/tags/tag_21. Sending it again changes nothing
curl -X PUT https://api.reviewflowz.com/v3/reviews/rev_7310021/tags/tag_21 \-H "Authorization: Bearer rfz_live_..."
Edit the request

PUT /v3/reviews/{review_id}/tags/{tag_id} in the reference

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

PATCH /v3/tags/{id} in the reference

  • It sees only the tag's name. Name it the way customers talk: Furniture delivery, not SKU-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
Edit the request

GET /v3/excerpts in the reference

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=fr on the French site.
  • Fallback: language=fr,en returns 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=CA and language=fr together 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
Edit the request

GET /v3/reviews in the reference

Example answer
{"data": [{"id": "rev_7310021","source": "src_5102","platform": "google_maps","rating": 5.0,"title": null,"text": "Two movers carried a sectional up four flights without a scratch on the walls. Booked at noon, done by three.","pros": null,"cons": null,"reviewer": {"name": "Dana R.","company": null,"avatar_url": null},"url": "https://www.google.com/maps/reviews/data=!4m8!14m7","date": "2026-11-08T19:12:00Z","tags": [{"id": "tag_12","name": "Furniture delivery"},{"id": "tag_21","name": "Featured"}]},{"id": "rev_7298457","source": "src_5201","platform": "trustpilot","rating": 5.0,"title": null,"text": "Bought a dresser on a marketplace and had it at my door the same afternoon. The driver sent photos at pickup.","pros": null,"cons": null,"reviewer": {"name": "Marcus T.","company": null,"avatar_url": null},"url": "https://www.trustpilot.com/reviews/6727a1c4e9b0d2f3a1b4c5d6","date": "2026-11-03T15:47:00Z","tags": [{"id": "tag_12","name": "Furniture delivery"}]}],"next_cursor": null,"has_more": false}​

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:

  1. Reviews tagged Featured first. Drop the ones tagged Hide from website.
  2. Then by length: 25 to 70 words reads best in a card.
  3. Then newest first.
  4. No more than two from the same source, so one listing doesn't fill the page.
  5. 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 it​export 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):

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-Match when 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

Field Use it for
title, text, pros, cons The words. Show pros and cons when text is empty
reviewer.name The name the platform shows. Keep the first name and an initial if you prefer
reviewer.avatar_url The platform's own image link: copy the image at build time rather than depend on it
url A "Read on Google" link, so a visitor can check the review is real
platform, date Where and when it was posted
rating Can be a half star, like 4.5

Don't change a review's words. To shorten one, use an excerpt from step 3.

For AI agents adding testimonials

  1. Read the vocabulary first (step 1). Reuse an existing tag; don't create a near-duplicate.
  2. Write down, for each page, the filters you'll use and the number of reviews it shows.
  3. Ask before you create tags or tag reviews: the whole team sees them in the app.
  4. Always set language, removed=false and has_text=true. text_length_min is in words.
  5. Pull a pool of about 100, rank it (step 5), and try looser filters when too few match (step 6).
  6. Fetch at build time or on the server. Never put the key in browser code.
  7. 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 304 still 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.