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.

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 Details

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 Details

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 Details

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

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

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

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: Refer to the "Business Object Details" accordion above for comprehensive business data fields.
Publisher Configuration: Refer to the "Publisher Configuration Details" accordion above for comprehensive publisher configuration fields.

Rate Limiting

This endpoint is subject to rate limiting to ensure fair usage and system stability. The default rate limit is 180 requests per 60 seconds.

Rate Limit Details

Limit: 180 requests per 60-second window
Window: Rolling 60-second window
Scope: Per API key

Rate Limit Headers

All successful responses include rate limit information in the headers:

X-RateLimit-Limit: 180
X-RateLimit-Window: 60s
X-RateLimit-Remaining: 179
X-RateLimit-Reset: 1738200123456

Rate Limit Exceeded Response (429)

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

Headers

X-RateLimit-Limit: 180
X-RateLimit-Window: 60s
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1738200123456
Retry-After: 14
Content-Type: application/json

Response Body

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please wait before retrying.",
    "status": 429,
    "details": {
      "limit_per_minute": 180,
      "window_seconds": 60,
      "remaining": 0,
      "reset_at": 1738200123456,
      "endpoint": "/v1/reviews",
      "method": "POST",
      "api_key": "redacted"
    },
    "suggestion": "Reduce request rate or implement exponential backoff with jitter."
  }
}

Best Practices

Monitor Headers: Check X-RateLimit-Remaining to track your usage
Implement Backoff: Use exponential backoff when approaching limits
Respect Retry-After: Wait for the specified time before retrying
Batch Requests: Combine multiple operations when possible