API Documentation

Access your review data programmatically. All endpoints return JSON.

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys in your account settings.

Authorization: Bearer ff_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

Keep your API key secret. Do not expose it in client-side code, public repositories, or browser requests. Use it only from your server.

Base URL

https://api.feedbackfountain.com/v1

The API is served from a dedicated subdomain. The main site at feedbackfountain.com redirects to www.feedbackfountain.com and does not serve API requests.

Errors

The API returns standard HTTP status codes. Error responses include a JSON body with an error field.

Status	Meaning
200	Success
400	Bad request — missing or invalid parameters
401	Unauthorized — invalid or missing API key
404	Not found — resource doesn't exist or doesn't belong to your account
500	Server error — try again or contact support

HTTP 401
{ "error": "Invalid or missing API key" }

Pagination

List endpoints support pagination with page and per_page parameters. Responses include metadata to help you navigate:

{
  "reviews": [...],
  "total": 9743,    // total matching results
  "page": 1,       // current page
  "per_page": 25,   // results per page
  "total_pages": 390 // total pages
}

Endpoints

GET /v1/locations

List Locations

Returns all active locations for your account with review statistics.

Example Request

curl -H "Authorization: Bearer ff_live_YOUR_KEY" \
  https://api.feedbackfountain.com/v1/locations

Example Response

[
  {
    "id": "loc_abc123",
    "name": "Ocoee, FL",
    "city": "Ocoee",
    "state": "FL",
    "review_count": 532,
    "avg_rating": 4.61
  },
  {
    "id": "loc_def456",
    "name": "Winter Park, FL",
    "city": "Winter Park",
    "state": "FL",
    "review_count": 379,
    "avg_rating": 4.70
  }
]

GET /v1/locations/:id

Get Location

Returns detailed information for a single location including platform IDs, AI summary, and per-source review counts.

Parameters

Name	In	Type		Description
`id`	path	string	required	The location ID

Example Request

curl -H "Authorization: Bearer ff_live_YOUR_KEY" \
  https://api.feedbackfountain.com/v1/locations/loc_abc123

Example Response

{
  "id": "loc_abc123",
  "name": "Ocoee, FL",
  "city": "Ocoee",
  "state": "FL",
  "lat": 28.5692,
  "lng": -81.5437,
  "google_place_id": "ChIJ49N6GeCH54gRjAGZRWLwMTo",
  "yelp_slug": "jeffs-bagel-run-ocoee-3",
  "yelp_biz_id": "FMy8frQo3k-11fSKnmU6SA",
  "doordash_store_id": "23137575",
  "ubereats_store_id": "UrmhsM3WWXygt0pZ8_4v6A",
  "tripadvisor_id": "d28145157",
  "ai_blurb": "Crowd favorite, staff gets rave reviews",
  "ai_summary": "Jeff's Bagel Run Ocoee is the flagship location with consistently high ratings across all platforms...",
  "review_count": 532,
  "avg_rating": 4.61,
  "google_count": 340,
  "yelp_count": 120,
  "doordash_count": 39,
  "ubereats_count": 33,
  "tripadvisor_count": 7,
  "created_at": "2026-03-31 00:00:00"
}

GET /v1/reviews

List Reviews

Returns a paginated list of reviews with filtering and sorting options.

Parameters

Name	In	Type	Description
`location`	query	string	Filter by location ID
`source`	query	string	Filter by platform: google, yelp, doordash, ubereats, or tripadvisor
`rating`	query	integer	Filter by exact star rating (1-5)
`since`	query	string	Only reviews on or after this date (ISO 8601, e.g. 2026-03-01)
`page`	query	integer	Page number (default: 1)
`per_page`	query	integer	Results per page (default: 25, max: 100)

Example Request

# All reviews
curl -H "Authorization: Bearer ff_live_YOUR_KEY" \
  https://api.feedbackfountain.com/v1/reviews

# 5-star Google reviews from the last month
curl -H "Authorization: Bearer ff_live_YOUR_KEY" \
  "https://api.feedbackfountain.com/v1/reviews?source=google&rating=5&since=2026-03-01"

# All reviews for a specific location, page 2
curl -H "Authorization: Bearer ff_live_YOUR_KEY" \
  "https://api.feedbackfountain.com/v1/reviews?location=loc_abc123&page=2"

Example Response

{
  "reviews": [
    {
      "id": "rev_xyz789",
      "location_id": "loc_abc123",
      "source": "google",
      "rating": 5,
      "reviewer_name": "Sarah M.",
      "review_text": "Best bagels in Orlando! Always fresh and the staff is incredibly friendly. Jeff's Bagel Run is our new Sunday morning tradition.",
      "review_date": "2026-03-28",
      "sentiment": null,
      "has_merchant_response": 1,
      "merchant_response_text": "Thanks Sarah! We love being part of your Sunday routine.",
      "ai_suggested_response": null,
      "location_name": "Ocoee, FL"
    }
  ],
  "total": 9743,
  "page": 1,
  "per_page": 25,
  "total_pages": 390
}

GET /v1/reviews/:id

Get Review

Returns the full details of a single review including merchant response, AI suggestion, and date precision metadata.

Parameters

Name	In	Type		Description
`id`	path	string	required	The review ID

Example Request

curl -H "Authorization: Bearer ff_live_YOUR_KEY" \
  https://api.feedbackfountain.com/v1/reviews/rev_xyz789

Example Response

{
  "id": "rev_xyz789",
  "location_id": "loc_abc123",
  "source": "yelp",
  "source_review_id": null,
  "rating": 5,
  "reviewer_name": "Kristy A.",
  "review_text": "I have never had a bad bagel from Jeff's Bagel Run! If you snag a warm salt and rosemary first thing in the morning then you are genuinely lucky!",
  "review_date": "2026-03-28",
  "review_date_raw": null,
  "review_date_precision": "exact",
  "sentiment": null,
  "has_merchant_response": 1,
  "merchant_response_text": "Thanks Kristy! The salt and rosemary is one of our favorites too.",
  "ai_suggested_response": null,
  "needs_attention": 0,
  "scraped_at": "2026-04-01 12:30:00",
  "created_at": "2026-04-01 12:30:00",
  "location_name": "Ocoee, FL",
  "location_city": "Ocoee",
  "location_state": "FL"
}

Rate Limits

There are currently no rate limits enforced on the API. We reserve the right to introduce rate limits in the future if needed. Please be reasonable with your request volume.