> ## 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 platforms

<Warning>
  This feature is available only for businesses subscribed to Review Management.
</Warning>

Partoo centralizes all business reviews from Google, Facebook, and TripAdvisor platforms, providing a unified API to retrieve and manage them efficiently.

## 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

  <Tabs>
    <Tab title="Google My Business">
      * Valid Google My Business location ID (`google_location_id`)
      * Active OAuth account with proper scopes
      * GMB location must be linked to the business
    </Tab>

    <Tab title="Facebook">
      * Valid Facebook page ID (`facebook_page_id`)
      * Active OAuth account with review permissions
      * Facebook page must be linked to the business
    </Tab>

    <Tab title="TripAdvisor">
      * Valid TripAdvisor location ID (`tripadvisor_location_id`)
      * Active API credentials
      * **Rate Limit**: Maximum 50 reviews per request, 50 requests per second
    </Tab>
  </Tabs>

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

## 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

### 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

<Info>
  **Important**: You can only reply to reviews via the API, not **modify** or **delete** the original review content.
</Info>

### 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

## Tips to Retrieve Reviews Effectively

<Steps>
  <Step title="Use the Search Endpoint">
    Start with the main search endpoint to retrieve reviews:

    ```
    GET /reviews
    ```

    <Tip>
      You can find the complete endpoint documentation in the [API Reference](/api-reference/reviews/search-for-reviews).
    </Tip>
  </Step>

  <Step title="Apply Smart Filtering">
    Use the available filters to narrow down your results:

    <Tabs>
      <Tab title="Business Filtering">
        ```bash theme={null}
        # Get reviews for specific businesses
        GET /reviews?business__in=5409c35a97bbc544d8e26737,60b2645fb12ff60643ef8344
        ```
      </Tab>

      <Tab title="Status Filtering">
        ```bash theme={null}
        # Get only untreated reviews
        GET /reviews?state__in=not_treated

        # Get treated reviews
        GET /reviews?state__in=treated
        ```
      </Tab>

      <Tab title="Platform Filtering">
        ```bash theme={null}
        # Get reviews from specific platforms
        GET /reviews?partner=google_my_business
        GET /reviews?partner=facebook
        GET /reviews?partner=tripadvisor
        ```
      </Tab>

      <Tab title="Date Range Filtering">
        ```bash theme={null}
        # Get reviews from a specific date range
        GET /reviews?update_date__gte=2024-01-01&update_date__lte=2024-01-31
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Implement Pagination">
    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==
    ```

    <Info>
      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.
    </Info>
  </Step>

  <Step title="Use Keywords Search">
    Search for specific content within reviews:

    ```bash theme={null}
    # Search for reviews containing specific keywords
    GET /reviews?keywords=excellent,amazing,great
    ```

    <Tip>
      Keywords are searched across review content, author names, and platform-specific fields. Maximum 12 keywords allowed.
    </Tip>
  </Step>

  <Step title="Sort Results Effectively">
    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
    ```

    <Info>
      Available ordering fields: `id`, `author_name`, `date`, `update_date`, `rating`, `state`, `title`, `partner`. Prefix with `-` for descending order.
    </Info>
  </Step>
</Steps>