Retrieve Reviews

This feature is available only for businesses subscribed to Review Management.

Partoo centralizes all business reviews from Google, Facebook, and TripAdvisor platforms, providing a unified API to retrieve and manage them efficiently. It also hosts the reviews you collect outside those platforms, on your own app, a marketplace, or a delivery service, through a custom review partner you can push yourself.

Prerequisites

Before retrieving reviews, ensure you have:

Active subscription to the Review Management
API key with Business Manager role or higher
Platform Integrations: Ensure your platforms are integrated properly
- Google My Business
- Facebook
- TripAdvisor
- Custom partners
- Valid Google My Business location ID (google_location_id)
- Active OAuth account with proper scopes
- GMB location must be linked to the business
- Valid Facebook page ID (facebook_page_id)
- Active OAuth account with review permissions
- Facebook page must be linked to the business
- Valid TripAdvisor location ID (tripadvisor_location_id)
- Active API credentials
- Rate Limit: Maximum 50 reviews per request, 50 requests per second
- A custom partner created for your organization, and its partner_slug
- The partner listed by GET /review-partners with is_custom: true

If you need help with any of these prerequisites, please contact your Account Manager who can guide you through the process.

How the Reviews Mechanism Works

Partoo automatically collects reviews from Google, Facebook, and TripAdvisor platforms and makes them available through a unified API.

Review Collection

Scheduled fetching: Reviews are collected daily at different times for each platform:
- Google My Business: 8:15 PM UTC
- Facebook: 7:00 PM UTC
- TripAdvisor: 8:00 PM UTC
24-hour delay: New reviews may take up to 24 hours to appear in the API
Live fetch: Google My Business reviews are fetched when Google sends webhook notifications
Platform integration: Only reviews from connected platforms are available
Custom partners: nothing is collected, you push the reviews, and they are available immediately

Review States

Each review has one of these states:

treated: Has a reply or was marked as treated
not_treated: No reply yet and not marked as treated
deleted: Was removed by the user on the original platform
pending_auto_reply: Queued for automatic response
treated_auto_reply: Has a reply via automatic response

Important: Unless they are from custom partners you handle on your side, you can only reply to reviews via the API, not modify or delete the original review content.

Reply Templates

Reply templates help you respond quickly to reviews with predefined messages. They’re designed for use within the Partoo application. You cannot access a formatted template with prefilled placeholders from the API. However, you can manage these templates through the API:

Browse through existing reply templates
Create new reply templates
Delete reply templates

Custom Review Partners

A custom review partner is a source of reviews Partoo does not synchronize itself: your own app, a marketplace, a delivery platform. You push those reviews through the API, and they then behave like any other reviews: searchable, repliable, and carried by the review_created and review_updated webhooks. Replies written in Partoo travel the other way: they are sent back to you so you can publish them on your platform.

What you need

Get your custom partner created

Custom partners are set up by Partoo. Contact your Account Manager with the platform you want to bring in, and you get back a partner slug, for example my_partner, that identifies it in every call.

Check that it is enabled on your organization

GET /review-partners

Your custom partners are the entries flagged is_custom: true. A partner missing from that list is not enabled for your organization yet, and pushing reviews to it is refused.

Use an API key with the right rights

Pushing and deleting reviews requires an API key whose user is an ORG_ADMIN and carries the review_edit permission. You can only push for businesses of your own organization.

Push your reviews

POST /reviews

{
  "partner_slug": "my_partner",
  "external_id": "mp-review-8f21c0",
  "business_id": "5409c35a97bbc544d8e26737",
  "rating": 4,
  "content": "Commande livrée en avance, tout était chaud. Merci !",
  "author": { "display_name": "Camille D." },
  "date": "2026-09-15T18:32:11+02:00",
  "link": "https://www.my_partner.com/reviews/8f21c0",
  "reply": {
    "content": "Merci pour votre retour, à très bientôt !",
    "date": "2026-09-16T09:04:55+02:00"
  }
}

The pair (partner_slug, external_id) identifies the review: the first call creates it, and every later call with the same pair updates it in place.

Dates must carry their UTC offset (+02:00, Z). Partoo stores them in UTC and displays them in the timezone of the business.

Correct and delete

Correct a review: push it again with the same partner_slug and external_id. Rating, content, author, dates, link and reply are all updated.
Delete a review: DELETE /reviews/{review_id}, using the Partoo id returned by the push.

Read them back

# The reviews of one of your custom partners
GET /reviews?partner=my_partner

The complete payload, and every error the push and delete endpoints can return, are documented in the API Reference.

Get the replies back

Your teams answer those reviews inside Partoo, from the app or through POST /comments. Partoo cannot publish that answer on your platform, it is yours, so it hands it back to you: every reply written, edited or deleted on one of your custom-partner reviews calls the endpoint you gave us, and you publish it on your side.

Event	Sent when	Payload
`custom_reply_created`	A reply is added to one of your reviews	The review and the reply
`custom_reply_updated`	An existing reply is edited	The review and the new reply
`custom_reply_deleted`	A reply is removed	The review only

{
  "type": "custom_reply_created",
  "payload": {
    "business_id": "5409c35a97bbc544d8e26737",
    "partner_slug": "my_partner",
    "review_external_id": "mp-review-8f21c0",
    "reply": {
      "content": "Merci pour votre retour, à très bientôt !",
      "date": "2026-09-16T09:04:55+02:00",
      "update_date": null,
      "author_name": "Camille Durand"
    }
  }
}

These three events can be setup from Settings > Integrations > Webhooks or by API as explained on the Webhooks documentation.

Tips to Retrieve Reviews Effectively

Use the Search Endpoint

Start with the main search endpoint to retrieve reviews:

GET /reviews

You can find the complete endpoint documentation in the API Reference.

Apply Smart Filtering

Use the available filters to narrow down your results:

Business Filtering
Status Filtering
Platform Filtering
Date Range Filtering

# Get reviews for specific businesses
GET /reviews?business__in=5409c35a97bbc544d8e26737,60b2645fb12ff60643ef8344

# Get only untreated reviews
GET /reviews?state__in=not_treated

# Get treated reviews
GET /reviews?state__in=treated

# Exclude deleted reviews (by default deleted reviews are returned)
GET /reviews?state__notin=deleted

# Get reviews from specific platforms
GET /reviews?partner=google_my_business
GET /reviews?partner=facebook
GET /reviews?partner=tripadvisor

# Get reviews from one of your custom partners
GET /reviews?partner=my_partner

GET /review-partners returns every slug you can filter on, yours included.

# Get reviews from a specific date range
GET /reviews?update_date__gte=2024-01-01&update_date__lte=2024-01-31

Implement Pagination

Handle large datasets efficiently with cursor-based pagination:

# Enables cursor-based pagination mode
GET /reviews?cursor=1

# Subsequent pages using cursor
GET /reviews?next_cursor=eyJ1cGRhdGVfZGF0ZSI6IjIwMjQtMDEtMDEiLCJpZCI6MTIzfQ==

The default page size is 30 reviews per page, with a maximum of 100 reviews per page. Use cursor-based pagination for better performance with large datasets.

Use Keywords Search

Search for specific content within reviews:

# Search for reviews containing specific keywords
GET /reviews?keywords=excellent,amazing,great

Keywords are searched across review content, author names, and platform-specific fields. Maximum 12 keywords allowed.

Sort Results Effectively

Order your results for better management:

# Sort by creation date (newest first)
GET /reviews?ordering=-date

# Sort by rating (highest first)
GET /reviews?ordering=-rating

# Sort by status
GET /reviews?ordering=state

Available ordering fields: id, author_name, date, update_date, rating, state, title, partner. Prefix with - for descending order.

First Steps

Guides

Resources

Misc

Prerequisites

How the Reviews Mechanism Works

Review Collection

Review States

Reply Templates

Custom Review Partners

What you need

Push your reviews

Correct and delete

Read them back

Get the replies back

Tips to Retrieve Reviews Effectively

​Prerequisites

​How the Reviews Mechanism Works

​Review Collection

​Review States

​Reply Templates

​Custom Review Partners

​What you need

​Push your reviews

​Correct and delete

​Read them back

​Get the replies back

​Tips to Retrieve Reviews Effectively

Prerequisites

How the Reviews Mechanism Works

Review Collection

Review States

Reply Templates

Custom Review Partners

What you need

Push your reviews

Correct and delete

Read them back

Get the replies back

Tips to Retrieve Reviews Effectively