List Reviews

GET/api/v1/reviews

Retrieve a paginated list of reviews for your organization. Supports filtering by platform, rating range, and date.

Authentication

Bearer API Key — requires a Growth plan or higher.


curl "https://app.prooflio.io/api/v1/reviews?limit=10&platform=GOOGLE" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Name	Type	Default	Description
`limit`	`number`	`20`	Number of reviews to return (max 100).
`offset`	`number`	`0`	Pagination offset.
`platform`	`string`	—	Filter by platform (e.g., `GOOGLE`, `YELP`, `TRUSTPILOT`, `G2`, `CAPTERRA`, `FACEBOOK`).
`minRating`	`number`	—	Minimum rating filter (1–5).
`maxRating`	`number`	—	Maximum rating filter (1–5).
`since`	`string`	—	ISO 8601 date — only return reviews after this date.

Response

200 OK


{
  "data": [
    {
      "id": "clx...",
      "platform": "GOOGLE",
      "authorName": "Jane D.",
      "authorAvatar": "https://lh3.googleusercontent.com/...",
      "rating": 5,
      "content": "Excellent service! The team was incredibly responsive.",
      "date": "2026-02-15T10:30:00.000Z",
      "url": "https://maps.google.com/...",
      "language": "en",
      "isVerified": true,
      "sentiment": 0.92,
      "sentimentLabel": "POSITIVE",
      "aiSummary": "Customer praised fast and friendly service.",
      "aiThemes": ["service", "speed", "responsiveness"],
      "createdAt": "2026-02-15T11:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 142,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Response Fields

Field	Type	Description
`id`	`string`	Unique review identifier.
`platform`	`string`	Source platform (e.g., `GOOGLE`, `YELP`, `TRUSTPILOT`).
`authorName`	`string`	Name of the review author.
`authorAvatar`	`string \| null`	URL of the author’s avatar image.
`rating`	`number \| null`	Star rating (1–5). Null if the platform doesn’t use star ratings.
`content`	`string`	Full review text.
`date`	`string`	ISO 8601 date when the review was originally posted.
`url`	`string \| null`	Direct link to the review on the source platform.
`language`	`string`	Detected language code (e.g., `en`, `es`, `fr`).
`isVerified`	`boolean`	Whether the review is from a verified customer.
`sentiment`	`number \| null`	AI sentiment score from 0 (negative) to 1 (positive).
`sentimentLabel`	`string \| null`	Sentiment category: `POSITIVE`, `NEUTRAL`, or `NEGATIVE`.
`aiSummary`	`string \| null`	AI-generated one-line summary of the review.
`aiThemes`	`string[]`	AI-extracted themes (e.g., `["service", "pricing"]`).
`createdAt`	`string`	ISO 8601 timestamp when the review was imported into Prooflio.

Pagination

Field	Type	Description
`total`	`number`	Total number of reviews matching the filters.
`limit`	`number`	Number of reviews per page.
`offset`	`number`	Current pagination offset.
`hasMore`	`boolean`	Whether there are more results beyond the current page.

Error Responses

Status	Description
`401 Unauthorized`	Missing or invalid API key.
`403 Forbidden`	Plan does not include API access.
`429 Too Many Requests`	Rate limit exceeded.

Pagination Example


// Fetch all reviews in batches of 100
let offset = 0;
let allReviews = [];
 
while (true) {
  const response = await fetch(
    `https://app.prooflio.io/api/v1/reviews?limit=100&offset=${offset}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const { data, pagination } = await response.json();
 
  allReviews = allReviews.concat(data);
 
  if (!pagination.hasMore) break;
  offset += 100;
}
 
console.log(`Fetched ${allReviews.length} reviews total`);