Use a testimonial API to fetch and add reviews from your own code
Collecting reviews is only the first step.
If they remain inside a dashboard, moving them to a site, report or internal tool becomes manual work. A REST API solves that by returning published and pending testimonials as JSON, accepting new ones, and letting your own interface decide how they appear. The same approach also works for AI agents, because predictable endpoints and status codes are easier for automated tools to call than a visual dashboard.
Decide whether you need data or a finished display
A useful starting point is to separate three jobs: reading approved reviews for display, adding a review after a survey or purchase, and checking submissions that still need approval. Treating those as distinct workflows prevents a common mistake — publishing everything immediately or, at the other extreme, leaving new feedback stranded in a review queue. The endpoint map below keeps that distinction clear.
Decision checklist: choose the widget when you want a finished wall quickly; choose the API when markup, synchronisation, reporting or automation matters; choose a no-code route when you do not want to write request code. Before integrating, confirm your plan includes API access, store the key securely because it is shown once, and decide how you will handle 401 and 429 responses.
Endpoint and field map
List every wall in the account with GET /walls. Fetch approved items with GET /walls/{wall_url}/testimonials. Add an item with POST to that same wall path, supplying author, content and rating, with work_title where applicable. Use GET /walls/{wall_url}/collected-testimonials for submissions awaiting review. Responses are JSON, and list calls support limit and cursor pagination; the default limit is 20 and the maximum is 50. The illustrative fetch response shows author, work_title, rating, content, image and video_url, plus a next_cursor for paging.
Three-step setup and a worked example
First, generate a key in API settings and copy it somewhere safe. Second, call an endpoint with the key as a Bearer token in the Authorization header. Third, render the returned data in your own component, send it to a report, or pass it to another tool. A practical example is a headless section: fetch up to 20 published testimonials, render author, rating and content with your own markup, then follow next_cursor only if more are needed. For automation, post a testimonial after a five-star survey or checkout response, or poll collected submissions and notify Slack, a CRM or a queue.
What you can build, including for AI agents
Headless sections let React, Vue or server-side code own the presentation. Synchronisation can place survey and checkout feedback on a wall without dashboard edits. Reporting tools can combine ratings and text with other metrics. Agencies and multi-brand teams can serve different walls from one account. Video and audio URLs allow a custom player. Migration workflows can read from one account and write to another or to your own database. For AI use, an agent can retrieve relevant proof for a sales or support answer, create a testimonial after a five-star review, summarise sentiment for a weekly report, or keep a social-proof knowledge base current. Named compatible tools include Claude Code, Codex, Grok, Hermes and Openclaw, plus any other agent supporting tool use.
Failure distinctions and safe handling
A 401 means check the key and whether your plan includes API access. A 429 means you have exceeded the rate limit; wait about a minute and retry. Because the key is shown once, do not commit it to source control. Keep published and collected endpoints separate in your code so pending submissions are reviewed before display. If you do not want to code, use a widget or no-code integration rather than forcing a direct API integration.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /walls | List every testimonial wall in your account. |
| GET | /walls/{wall_url}/testimonials | Fetch published testimonials on a wall. |
| POST | /walls/{wall_url}/testimonials | Add a new testimonial to a wall. |
| GET | /walls/{wall_url}/collected-testimonials | Fetch collected submissions awaiting review. |
Endpoint purposes are taken from the source table; full schema is in the API reference.
Frequently asked questions
Which plans include the testimonial API?
Access is described as part of paid plans. Confirm the current plan name, price and whether API access is included with the owner before relying on it: {{OWNER_PLAN_NAME}}, {{OWNER_PLAN_PRICE}}, {{OWNER_API_PLAN_INCLUSION}}. A 401 response is described as indicating a wrong key or a plan without API access.
How do I get an API key?
Create a key in API settings in the app. It is shown only once, so store it securely and send it as a Bearer token in the Authorization header on each request.
What can I do with the testimonial API?
You can list walls, fetch published testimonials, add a new testimonial, and fetch collected submissions awaiting review. Those operations cover the main read and write workflows described.
Can I build a fully custom, headless testimonial display?
Yes. Retrieve the records as JSON and render them with your own components and styling. You do not need to use a ready-made widget if you want control over the markup.
Does the API return video testimonials?
Yes. Responses include video and audio URLs and playback identifiers alongside text, so video reviews can be played in your own player rather than a default embed.
Are there rate limits?
Rate limiting applies. Exceeding it returns 429; wait about a minute before retrying. List endpoints return up to 50 records per page and use a cursor for subsequent pages, with a default limit of 20.
How is the API different from the embed widget?
A widget places a finished wall on your site without code. The API returns the underlying data so you can choose any layout, synchronise records between systems, or feed them into other tools.
Can AI agents and LLMs use the testimonial API?
Yes. Plain REST, JSON responses and Bearer authentication match what LLM tool use and function calling expect. An agent can retrieve testimonials to support a reply or create one automatically, and clear 401 and 429 responses simplify retry handling.
Which AI agents and coding assistants does it work with?
Any agent supporting tool use or function calling is described as suitable, including Claude Code, Codex, Grok, Hermes and Openclaw. Provide the base URL, Bearer key and endpoints; no special SDK is described as necessary.
Do I need to be a developer to use it?
Direct API calls require some coding. If you prefer no code, use a widget or a no-code integration instead.
$ curl {{API_BASE_URL}}/v1/walls/acme/testimonials \
-H "Authorization: Bearer fw_live_••••"
200 OK
{
"data": [
{
"author": "Avery Smith",
"work_title": "Course Creator",
"rating": 5,
"content": "A short example update.",
"image": "{{CDN_BASE_URL}}/...",
"video_url": null
}
],
"next_cursor": "c2_8f3a"
}curl -X POST \
{{API_BASE_URL}}/v1/walls/acme/testimonials \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"author": "Jane Doe",
"content": "A short example update.",
"rating": 5,
"work_title": "Head of Marketing"
}'curl "{{API_BASE_URL}}/v1/walls/acme/testimonials\
?limit=50&cursor=c2_8f3a" \
-H "Authorization: Bearer YOUR_API_KEY"
# limit: default 20, max 50
# 401 invalid key or plan, 429 rate limited{
"type": "function",
"function": {
"name": "get_testimonials",
"description": "Fetch published testimonials from a Famewall wall",
"parameters": {
"type": "object",
"properties": {
"wall_url": { "type": "string", "description": "Wall identifier" },
"limit": { "type": "integer", "maximum": 50 },
"cursor": { "type": "string", "description": "Pagination cursor" }
},
"required": ["wall_url"]
}
}
}