> ## Documentation Index > Fetch the complete documentation index at: https://developers.partoo.co/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve Reviews > Learn how to effectively retrieve and manage reviews from Google, Facebook and TripAdvisor, and how to bring in your own reviews through a custom partner 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](#custom-review-partners) 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](/guides/api/resources/settings/security_and_api_key_usage) * Platform Integrations: Ensure your platforms are integrated properly * 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](#get-the-replies-back) so you can publish them on your platform. ### What you need 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. ```bash theme={null} 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. 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 ```bash theme={null} POST /reviews ``` ```json theme={null} { "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 ```bash theme={null} # 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](/api-reference/reviews/push-a-review-from-a-custom-partner). ### 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 | ```json theme={null} { "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](/guides/api/resources/settings/webhooks/index). ## Tips to Retrieve Reviews Effectively Start with the main search endpoint to retrieve reviews: ``` GET /reviews ``` You can find the complete endpoint documentation in the [API Reference](/api-reference/reviews/search-for-reviews). Use the available filters to narrow down your results: ```bash theme={null} # Get reviews for specific businesses GET /reviews?business__in=5409c35a97bbc544d8e26737,60b2645fb12ff60643ef8344 ``` ```bash theme={null} # 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 ``` ```bash theme={null} # 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. ```bash theme={null} # Get reviews from a specific date range GET /reviews?update_date__gte=2024-01-01&update_date__lte=2024-01-31 ``` Handle large datasets efficiently with cursor-based pagination: ```bash theme={null} # 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. Search for specific content within reviews: ```bash theme={null} # 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. Order your results for better management: ```bash theme={null} # 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.