Request Reviews

Submit a request to scrape reviews from multiple review sites for a business.

Endpoint

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

Description

This endpoint validates the API key, creates a scraping request record, and queues scraping tasks for each publisher. The request is processed asynchronously, and you can retrieve results using the /retrieve-task/ endpoint.

Try It Out

Test this endpoint directly in your browser:

Request Reviews

POST

Test this endpoint directly in your browser. Enter your API key and modify the request body as needed.

API Key

API Key

Your API key is required for authentication

Request Body (JSON)

Modify the request parameters below. A unique foreign_key is auto-generated but can be manually edited.

​

Request Body

Schema

{
  "job": "App\\Jobs\\RequestReviews",
  "data": {
    "api_key": "string",
    "foreign_key": "string",
    "lazy": "boolean",
    "business": {
      "id": "string",
      "name": "string",
      "address": {
        "street": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country": "string"
      },
      "phone": "string",
      "description": "string",
      "tags": ["string"]
    },
    "publishers": {
      "publisher.com": {
        "profile_key": "string",
        "last_review_hashes": ["string"],
        "first_page_only": "boolean"
      }
    }
  }
}

Required Fields

• job: Must be "App\\Jobs\\RequestReviews"
• data.api_key: Your API key for authentication
• data.foreign_key: External request identifier
• data.business: Business information object
• data.publishers: Publisher configurations object

Business Object

Field	Type	Required	Description
id	string	Yes	Business identifier
name	string	Yes	Business name
address	object	Yes	Physical address
phone	string	Yes	Contact number
description	string	Yes	Business details
tags	array	Yes	Additional categories

Address Object

Field	Type	Required	Description
street	string	Yes	Street address
city	string	Yes	City name
state	string	Yes	State/province
zip	string	Yes	Postal code
country	string	Yes	3-letter country code (e.g., USA, GBR)

Publisher Configuration

Field	Type	Required	Description
profile_key	string	Yes	Business URL/ID at publisher
last_review_hashes	array	Yes	Hashes from previous reviews
first_page_only	boolean	Yes	true=first page, false=all pages
persona.additional_cookies	object	No	Required for Facebook

Example Request

Basic Request

{
  "job": "App\\Jobs\\RequestReviews",
  "data": {
    "lazy": true,
    "api_key": "YOUR_API_KEY_HERE",
    "business": {
      "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."
    },
    "publishers": {
      "maps.google.com": {
        "profile_key": "https://www.google.com/maps/place/McDonald's/@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=EgoyMDI1MDYyMi4wIKXMDSoASAFQAw%3D%3D",
        "first_page_only": false,
        "last_review_hashes": []
      }
    },
    "foreign_key": "TEST_1751446701622_hznlpc"
  }
}

Request with Additional Cookies

{
  "job": "App\\Jobs\\RequestReviews",
  "data": {
    "lazy": true,
    "api_key": "YOUR_API_KEY_HERE",
    "business": {
      "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."
    },
    "publishers": {
      "facebook.com": {
        "profile_key": "https://www.facebook.com/McDonalds/",
        "first_page_only": true,
        "last_review_hashes": [],
        "persona": {
          "additional_cookies": {
            "login": [
              {
                "name": "Cookie_Name",
                "value": "Cookie_Value",
                "domain": "Cookie_domain"
              }
            ]
          }
        }
      }
    },
    "foreign_key": "TEST_1751446701622_hznlpc"
  }
}

Response

Success Response (201)

{
    "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",
}

Error Response (400)

{
  "error": "Invalid payload",
  "details": {
    "data": {
      "business": {
        "address": {
          "street": ["This field is required."]
        }
      }
    }
  }
}

Error Response (401)

{
  "error": "Invalid API key",
  "details": {
    "api_key": ["The provided API key is invalid"]
  }
}

Parameters

Job Key

Must be "App\\Jobs\\RequestReviews"

API Key

Client authentication key placed in data.api_key

Foreign Key

External request identifier (data.foreign_key)

Lazy Mode

Set data.lazy=true to increase timeout for large requests

Business Data

Used for profile lookup when no profile_key is provided:

• id: Business identifier
• name: Business name
• address: Physical address
• phone: Contact number
• description: Business details
• tags: Additional categories

Address Requirements

• country: 3-letter country code (e.g., USA, GBR)

Publisher Configuration

Key-value pairs where key is publisher name (e.g., yelp.com)

Field	Description
profile_key	Business URL/ID at publisher
last_review_hashes	Hashes from previous reviews
first_page_only	true=first page, false=all pages
additional_cookies	Required for Facebook/Yelp

Rate Limiting

This endpoint is subject to rate limiting based on your subscription plan. If you exceed your rate limit, you'll receive a 429 Too Many Requests response.

Next Steps

After submitting a request:

1. Use the Retrieve Task endpoint to check status
2. Configure Webhooks for real-time notifications
3. Monitor task progress and retrieve results when complete