How It Works

🔄 System Flow

Complete step-by-step guide to using the ReviewData Lite API

This guide walks you through the complete flow of using the ReviewData Lite API, from getting your API key to receiving and processing review data.

📋 Overview

The ReviewData Lite API follows a 5-step process:

🔑 Get Your API Key - Request and receive your authentication credentials
🔔 Setup Webhooks - Configure notifications for when your requests complete
📤 Submit Review Request - Send business data to start review collection
🔔 Receive Webhook Notifications - When your request completes, you'll receive a webhook notification
📥 Retrieve Review Data - Download the collected review data

Step 1: Get Your API Key 🔑

Request API Key

Visit our API key request page to get started:

🔑 Request API Key →

What Happens Next

You'll receive an onboarding email containing your unique API key
This API key will be used for all subsequent API requests
Keep your API key secure and don't share it publicly

Step 2: Setup Webhooks 🔔

Why Webhooks?

Webhooks notify you when your review collection requests are completed, so you don't need to constantly poll the API for status updates.

Configure Webhook Endpoint

Endpoint: POST https://data.reviewdata.ai/webhooks/create-webhook/

Request Payload:

{
  "api_key": "YOUR_API_KEY_HERE",
  "webhook": "https://webhook.site/28facfba-ae3f-40a1-8730-f69ea2ad2c4a"
}

Parameters:

api_key: Your API key received in the onboarding email
webhook: The URL where you want to receive notifications (must be accessible from the internet)

Response:

{
    "webhook": "https://webhook.site/28facfba-ae3f-40a1-8730-f69ea2ad2c4a",
    "status": "success"
}

Webhook Implementation Tips

Ensure your webhook endpoint can handle POST requests
Return a 200 status code to acknowledge receipt
Implement proper error handling for webhook failures
Consider implementing webhook signature verification for security

Step 3: Submit Review Request 📤

Endpoint

POST https://data.reviewdata.ai/submit/request-reviews/

Request Payload Structure

{
  "job": "App\\Jobs\\RequestReviews",
  "data": {
    "lazy": true,
    "api_key": "YOUR_API_KEY_HERE",
    "business": {
      "id": "unique_business_id",
      "name": "Business Name",
      "tags": ["tag1", "tag2"],
      "phone": "+1234567890",
      "address": {
        "zip": "12345",
        "city": "City Name",
        "state": "State",
        "street": "Street Address",
        "country": "Country"
      },
      "description": "Business description"
    },
    "publishers": {
      "maps.google.com": {
        "profile_key": "https://maps.google.com/...",
        "first_page_only": false,
        "last_review_hashes": []
      }
    },
    "foreign_key": "your_unique_identifier"
  }
}

Important Request Limitations

Each API request can only target ONE review platform at a time.

This means:

✅ Single request: Get reviews from Google Maps for McDonald's
❌ NOT allowed: Get reviews from Google Maps + Yelp + TripAdvisor for McDonald's in one request

For multiple platforms, submit separate requests:

Request 1: McDonald's reviews from Google Maps
Request 2: McDonald's reviews from Yelp
Request 3: McDonald's reviews from TripAdvisor

Example: If you want review data from 5 different platforms (Google Maps, Yelp, TripAdvisor, Facebook, etc.) for the same business location, you must submit 5 separate API requests.

Profile Key Cost Information

What is a Profile Key? The profile_key is the direct URL to your business on a review platform (e.g., your Google Maps listing URL, Yelp business page URL).

Cost Impact:

🟢 Provide the profile_key = Standard pricing (you pay only for review data extraction)
🔴 Don't provide profile_key = Standard pricing + extra business search fee

How it works:

✅ With profile_key: You give us the exact business URL → We extract reviews → You pay standard rate
❌ Without profile_key: You give us business name/address → We find your business URL → We extract reviews → You pay standard rate + search fee

💰 Save Money: Always include the profile_key in your requests and save it for future use to avoid the additional search costs.

Key Parameters Explained

Business Object

id: Unique identifier for the business in your system
name: Business name
tags: Optional array of business categories
phone: Business phone number
address: Complete address information
description: Optional business description

Publishers Object

Configure which review sites to collect from:

Google Maps Example:

"maps.google.com": {
  "profile_key": "https://www.google.com/maps/place/...",
  "first_page_only": false,
  "last_review_hashes": []
}

Yelp Example:

"yelp.com": {
  "profile_key": "https://www.yelp.com/biz/...",
  "first_page_only": true,
  "last_review_hashes": []
}

TripAdvisor Example:

"tripadvisor.com": {
  "profile_key": "https://www.tripadvisor.com/...",
  "first_page_only": true,
  "last_review_hashes": []
}

Publisher Parameters

profile_key: Direct URL to the business profile (optional - system can find it)
first_page_only: true for first page only, false for all reviews
last_review_hashes: Array of review hashes to avoid duplicates

Other Parameters

lazy: Set to true for large review collections (longer processing time)
foreign_key: Your unique identifier to track this request
api_key: Your authentication key

Response

{
    "status": "success",
    "tasks_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
    "request_id": "9f9d2b5a-085c-4df3-bcca-20928f086925",
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "publisher_key": "maps.google.com",
}

Response Fields:

status: Request submission status
request_id: Unique identifier for tracking
tasks_id: Unique task identifier
foreign_key: Your original request identifier
publisher_key: Review site that was processed

Step 4: Receive Webhook Notifications 🔔

Webhook Payload Structure

When your request completes, you'll receive a webhook notification:

{
    "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
    "publisher_key": "maps.google.com",
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "profile_key": "https://www.google.com/maps/place/@40.7094789,-74.0126167,886m/data=!3m2!1e3!5s0x89c2592f4977ef97:0xf78d57398ac93494!4m7!3m6!1s0x89c25a177d4bf5db:0x84e51f23e8c0a75c!8m2!3d40.7094789!4d-74.0100364!10e1!16s%2Fg%2F1thtf190!5m1!1e1?entry=ttu&g_ep=EgoyMDI1MDY",
    "task_status": 200,
    "reviews_urls": [
        "https://prod-data-only-client.s3.amazonaws.com/Review_URLs/9f9d2b5a-085c-4df3-bcca-20928f086925/900e2ff4-2d25-4576-ab18-b9b8e73c0bd6_0.jl"
    ]
}

Webhook Fields Explained

task_id: Unique task identifier
publisher: Review site that was processed
foreign_key: Your original request identifier
profile_key: Business profile URL used
task_status: HTTP status code (200 = success)
reviews_urls: URLs where review data is stored

Step 5: Retrieve Review Data 📥

Endpoint

POST https://data.reviewdata.ai/retrieve-task/

Request Payload

{
  "api_key": "YOUR_API_KEY_HERE",
  "page": 1,
  "page_size": 10,
  "task_id": "your_task_id",
  "foreign_key": "your_unique_identifier",
  "publisher_key": "publisher_name"
}

Parameters

api_key: Your authentication key
foreign_key: The identifier you used in the original request
publisher_key: The review site (e.g., "maps.google.com")
page: Page number for pagination
page_size: Number of reviews per page
task_id: You will get this task_id on submitting the request for reviews

Response Structure

{
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "batch_id": "TEST_1751004113518_i6yxcl",
    "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
    "related_task_ids": [],
    "task_status": 200,
    "business": {
        "publisher": "maps.google.com",
        "profile_key": "https://www.google.com/maps/place/@40.7094789,-74.0126167,886m/data=!3m2!1e3!5s0x89c2592f4977ef97:0xf78d57398ac93494!4m7!3m6!1s0x89c25a177d4bf5db:0x84e51f23e8c0a75c!8m2!3d40.7094789!4d-74.0100364!10e1!16s%2Fg%2F1thtf190!5m1!1e1?entry=ttu&g_ep=EgoyMDI1MDY",
        "reviews_urls": [
            "https://prod-data-only-client.s3.amazonaws.com/Review_URLs/9f9d2b5a-085c-4df3-bcca-20928f086925/900e2ff4-2d25-4576-ab18-b9b8e73c0bd6_0.jl"
        ],
        "id": "restaurant_001",
        "name": "McDonald's",
        "tags": [
            "restaurant",
            "pizza",
            "italian",
            "casual"
        ],
        "phone": "+12123852066",
        "address": {
            "zip": "10038",
            "city": "New York",
            "state": "NY",
            "street": "160 Broadway",
            "country": "USA"
        },
        "description": "Classic, long-running fast-food chain known for its burgers & fries."
    },
    "reviews": [
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT25wVFEzWkxPR1ZJYkdWS04zWjNlWEo2ZW01UVZGRRAB",
            "author_name": "Regimorais Raab",
            "author_id": null,
            "rating": 5,
            "text": "Rapidez incrível",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT25wVFEzWkxPR1ZJYkdWS04zWjNlWEo2ZW01UVZGRRAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOnpTQ3ZLOGVIbGVKN3Z3eXJ6em5QVFE%7C0cLUo1-b2qC%7C?hl=en",
            "posted_at": 1750727938010,
            "review_hash": "f2601fda3fb2e249204ff97d9710acd7",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2pFeFEzSXpjVW8zZUdkalFYQkRiR2hSV2xWdVIzYxAB",
            "author_name": "gloria schuweiler",
            "author_id": null,
            "rating": 3,
            "text": "Some  how they  been getting  my order wrong.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2pFeFEzSXpjVW8zZUdkalFYQkRiR2hSV2xWdVIzYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOjExQ3IzcUo3eGdjQXBDbGhRWlVuR3c%7C0cLP3KjBeBa%7C?hl=en",
            "posted_at": 1750704405791,
            "review_hash": "3de49930bb5221fce5bb352146649726",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2t0bVYyODNNRUo2VWxCMVVGcGhRVGxtYzBKNUxXYxAB",
            "author_name": "Zadran Akram khan",
            "author_id": null,
            "rating": 2,
            "text": "Happy Wellcomen New And Last Chef Akram Zadran",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2t0bVYyODNNRUo2VWxCMVVGcGhRVGxtYzBKNUxXYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOktmV283MEJ6UlB1UFphQTlmc0J5LWc%7C0cKzlVRIta5%7C?hl=en",
            "posted_at": 1750596704474,
            "review_hash": "c11d5ca37c28d429beb161013fdd2c3d",
            "language": "en"
        },
        {
            "review_id": "ChZDSUhNMG9nS0VLUHNodGJuc18ycFR3EAE",
            "author_name": "Ivana Donev",
            "author_id": null,
            "rating": 4,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VLUHNodGJuc18ycFR3EAE!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEKPshtbns_2pTw%7CCgwI8oq2wgYQsPr9wQE%7C?hl=en",
            "posted_at": 1749910898406,
            "review_hash": "d7f32bfcdd9e46b23f04b2d69e1fe373",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT214TVVHTjNWMkZzVjFSMlQzQmhSMVoyYWtKZmRuYxAB",
            "author_name": "Ludovic Pagès",
            "author_id": null,
            "rating": 2,
            "text": "C'est déjà le bas du panier en France, ben ce n'est pas mieux sur Broadway à Wall Street. Je ne comprends pas pour quoi ça existe encore. Pour le reste ce resto a un service rapide et des toilettes propres.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT214TVVHTjNWMkZzVjFSMlQzQmhSMVoyYWtKZmRuYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOmxMUGN3V2FsV1R2T3BhR1Z2akJfdnc%7C0cI7yCrlChX%7C?hl=en",
            "posted_at": 1749847949935,
            "review_hash": "56848456ebc3393b5aa98a3134242221",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT20xS1UyWjRNR2hLTUdRd2RERmlVVXd4VDFOblgyYxAB",
            "author_name": "Aaron Moore",
            "author_id": null,
            "rating": 5,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT20xS1UyWjRNR2hLTUdRd2RERmlVVXd4VDFOblgyYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOm1KU2Z4MGhKMGQwdDFiUUwxT1NnX2c%7C0cI4FOfmJHX%7C?hl=en",
            "posted_at": 1749832729734,
            "review_hash": "ce4e8f08dbe2fda5d996cf906b553450",
            "language": "en"
        },
        {
            "review_id": "ChZDSUhNMG9nS0VQX3FpdmVkMHBhSlNREAE",
            "author_name": "Cevdet S A",
            "author_id": null,
            "rating": 5,
            "text": "Like it.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VQX3FpdmVkMHBhSlNREAE!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEP_qived0paJSQ%7CCgsI5p2pwgYQqMTXfA%7C?hl=en",
            "posted_at": 1749700326261,
            "review_hash": "433aa5e69074d92921cdac0b848ec3fd",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2pZelVUQTVVRkp3YVhGa1lUTlBVVk42VWxGcE9GRRAB",
            "author_name": "Vinod Sukhadia",
            "author_id": null,
            "rating": 5,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2pZelVUQTVVRkp3YVhGa1lUTlBVVk42VWxGcE9GRRAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOjYzUTA5UFJwaXFkYTNPUVN6UlFpOFE%7C0cHNU251Vof%7C?hl=en",
            "posted_at": 1749649347101,
            "review_hash": "aa0b25c137f7b386a6d392f91b54b5e0",
            "language": "en"
        },
        {
            "review_id": "ChZDSUhNMG9nS0VPM0E4N2k4a2V6SEJ3EAE",
            "author_name": "Husnain Ali",
            "author_id": null,
            "rating": 4,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VPM0E4N2k4a2V6SEJ3EAE!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEO3A87i8kezHBw%7CCgwI4c2jwgYQ2Mjj1wE%7C?hl=en",
            "posted_at": 1749608161452,
            "review_hash": "b7e33c65de9262919ad22741f0554832",
            "language": "en"
        },
        {
            "review_id": "ChdDSUhNMG9nS0VJQ0FnSURwX3QtdHJBRRAB",
            "author_name": "Fred Alluso",
            "author_id": null,
            "rating": 4,
            "text": "Clean, noisy, crowded. Most importantly they didn't mess up my coffee order.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChdDSUhNMG9nS0VJQ0FnSURwX3QtdHJBRRAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEICAgIDp_t-trAE%7C0cMTWPpdFWz%7C?hl=en",
            "posted_at": 1692756313115,
            "review_hash": "924067883b209b62d4ffd556179d9634",
            "language": "en"
        }
    ],
    "pagination": {
        "total_reviews": 11820,
        "page": 1,
        "page_size": 10,
        "total_pages": 1182,
        "has_next": true,
        "has_previous": false
    }
}

Review Data Fields

review_id: Unique review identifier
author_name: Reviewer's name
author_id: Reviewer's unique ID
rating: Review rating (1-5)
text: Review content
url: Direct link to the review
posted_at: Unix timestamp when review was posted (In UTC)
review_hash: Unique hash for deduplication
language: Review language code

🔄 Complete Flow Diagram

1. Request API Key
   ↓
2. Setup Webhook
   ↓
3. Submit Review Request
   ↓
4. System Processes Request
   ↓
5. Webhook Notification Sent
   ↓
6. Retrieve Review Data
   ↓
7. Process & Use Data

🎯 Best Practices

Performance Optimization

Use lazy: true for businesses with many reviews
Implement proper pagination to handle large datasets
Store review_hash values to avoid duplicate collection

Error Handling

Always check response status codes
Implement webhook retry logic
Handle API rate limits gracefully

Data Management

Store profile_key URLs to avoid business matching costs
Use meaningful foreign_key values for easy tracking
Implement proper data validation before submission

Security

Keep API keys secure and rotate regularly
Validate webhook signatures if implemented
Use HTTPS for all webhook endpoints

🚀 Next Steps

Now that you understand the complete flow:

Get Started → - Learn about authentication
API Endpoints → - Detailed endpoint documentation
Examples → - See real-world examples
Try Playground → - Test the API interactively

Need help? Check out our error codes or contact support.

🔄 System Flow

📋 Overview​

Step 1: Get Your API Key 🔑​

Request API Key​

What Happens Next​

Step 2: Setup Webhooks 🔔​

Why Webhooks?​

Configure Webhook Endpoint​

Webhook Implementation Tips​

Step 3: Submit Review Request 📤​

Endpoint​

Request Payload Structure​

Key Parameters Explained​

Business Object​

Publishers Object​

Publisher Parameters​

Other Parameters​

Response​

Step 4: Receive Webhook Notifications 🔔​

Webhook Payload Structure​

Webhook Fields Explained​

Step 5: Retrieve Review Data 📥​

Endpoint​

Request Payload​

Parameters​

Response Structure​

Review Data Fields​

🔄 Complete Flow Diagram​

🎯 Best Practices​

Performance Optimization​

Error Handling​

Data Management​

Security​

🚀 Next Steps​

📋 Overview

Step 1: Get Your API Key 🔑

Request API Key

What Happens Next

Step 2: Setup Webhooks 🔔

Why Webhooks?

Configure Webhook Endpoint

Webhook Implementation Tips

Step 3: Submit Review Request 📤

Endpoint

Request Payload Structure

Key Parameters Explained

Business Object

Publishers Object

Publisher Parameters

Other Parameters

Response

Step 4: Receive Webhook Notifications 🔔

Webhook Payload Structure

Webhook Fields Explained

Step 5: Retrieve Review Data 📥

Endpoint

Request Payload

Parameters

Response Structure

Review Data Fields

🔄 Complete Flow Diagram

🎯 Best Practices

Performance Optimization

Error Handling

Data Management

Security

🚀 Next Steps