Request Payload Model

The Request Payload model defines the complete structure for submitting review collection requests to the API.

Schema

{
  "job": "string",
  "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",
        "persona": {
          "additional_cookies": {
            "login": [
              {
                "name": "string",
                "value": "string",
                "domain": "string"
              }
            ]
          }
        }
      }
    }
  }
}

Top-Level Fields

Field	Type	Required	Description
`job`	string	Yes	Must be `"App\Jobs\RequestReviews"`
`data`	object	Yes	Main request data object

Data Object Fields

Field	Type	Required	Description
`api_key`	string	Yes	Your API key for authentication
`foreign_key`	string	Yes	External request identifier
`lazy`	boolean	Yes	Enable lazy mode for large requests
`business`	object	Yes	Business information object
`publishers`	object	Yes	Publisher configurations object
`additional_cookies`	object	No	Additional cookies for publishers

Field Details

Job

Value: Must be exactly "App\\Jobs\\RequestReviews"
Purpose: Identifies the job type for the API
Validation: Exact string match required

API Key

Type: string
Length: Up to 128 characters
Format: Alphanumeric string
Purpose: Authentication and authorization
Example: "ndsjwlb3.Hj70uPbf7dr1............."

Foreign Key

Type: string
Length: 1-255 characters
Purpose: External identifier for tracking requests
Uniqueness: Should be unique within your system
Example: "RESTAURANT_001", "HOTEL_2024_001"

Lazy Mode

Type: boolean
Purpose: Increases timeout for large requests
Values:
- true: Extended timeout, suitable for large datasets
- false: Standard timeout, suitable for small datasets
Recommendation: Use true for requests with multiple publishers or large review volumes

Business Object

Type: object
Required: Yes
Description: Complete business information
Reference: See Business Model for detailed structure

Publishers Object

Type: object
Required: Yes
Description: Key-value pairs where keys are publisher names
Format: "publisher.com": { publisher_config }
Reference: See Publisher Model for detailed structure

Additional Cookies

Type: object
Required: No
Description: Additional cookies for specific publishers
Format: Key-value pairs where keys are publisher names and values are arrays of cookie strings

Complete Example

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

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": {
      "yelp.com": {
        "profile_key": "https://www.yelp.com/biz/mcdonalds-new-york",
        "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": false,
        "last_review_hashes": [],
        "persona": {
          "additional_cookies": {
            "login": [
              {
                "name": "Cookie_Name",
                "value": "Cookie_Value",
                "domain": "Cookie_domain"
              }
            ]
          }
        }
      }
    },
    "foreign_key": "TEST_1751446701622_hznlpc"
  }
}

Validation Rules

Job Field

Required: Yes
Value: Must be exactly "App\\Jobs\\RequestReviews"
Case: Case-sensitive

API Key

Required: Yes
Length: 1-128 characters
Format: Alphanumeric string
Validation: Must be valid API key

Foreign Key

Required: Yes
Length: 1-255 characters
Format: String
Characters: Letters, numbers, underscores, hyphens

Lazy Mode

Required: Yes
Type: Boolean
Values: true or false

Business Object

Required: Yes
Validation: Must conform to Business model schema
Reference: See Business Model

Publishers Object

Required: Yes
Validation: Must contain at least one publisher
Keys: Must be valid publisher names
Values: Must conform to Publisher model schema
Reference: See Publisher Model

Additional Cookies

Required: No
Format: Object with publisher names as keys
Values: Arrays of cookie strings

Error Responses

Validation Error (422)

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

Authentication Error (401)

{
  "error": "Invalid API key"
}

Missing Required Field (400)

{
  "error": "Missing required field",
  "details": {
    "job": ["This field is required."]
  }
}

Best Practices

Request Structure

Consistency: Use consistent foreign keys across your system
Validation: Validate payload structure before sending
Error Handling: Implement proper error handling for validation failures
Logging: Log request details for debugging and monitoring

API Key Management

Security: Store API keys securely
Rotation: Regularly rotate API keys
Environment: Use different keys for different environments
Monitoring: Monitor API key usage and errors

Foreign Key Strategy

Uniqueness: Ensure foreign keys are unique within your system
Format: Use consistent naming conventions
Tracking: Maintain a mapping of foreign keys to business entities
Cleanup: Implement cleanup for old foreign keys

Lazy Mode Usage

Large Requests: Use lazy: true for requests with multiple publishers
Performance: Consider processing time when setting lazy mode
Monitoring: Monitor timeout issues and adjust accordingly

Publisher Configuration

Validation: Verify publisher profile keys before submitting
Authentication: Keep authentication credentials current
Rate Limits: Be aware of publisher-specific rate limits
Testing: Test configurations with small requests first

Business Model - Business information structure
Publisher Model - Publisher configuration structure
Response Models - API response structures

Schema​

Top-Level Fields​

Data Object Fields​

Field Details​

Job​

API Key​

Foreign Key​

Lazy Mode​

Business Object​

Publishers Object​

Additional Cookies​

Complete Example​

Basic Request​

Basic Request​

Request with Additional Cookies​

Validation Rules​

Job Field​

API Key​

Foreign Key​

Lazy Mode​

Business Object​

Publishers Object​

Additional Cookies​

Error Responses​

Validation Error (422)​

Authentication Error (401)​

Missing Required Field (400)​

Best Practices​

Request Structure​

API Key Management​

Foreign Key Strategy​

Lazy Mode Usage​

Publisher Configuration​

Related Models​

Schema

Top-Level Fields

Data Object Fields

Field Details

Job

API Key

Foreign Key

Lazy Mode

Business Object

Publishers Object

Additional Cookies

Complete Example

Basic Request

Basic Request

Request with Additional Cookies

Validation Rules

Job Field

API Key

Foreign Key

Lazy Mode

Business Object

Publishers Object

Additional Cookies

Error Responses

Validation Error (422)

Authentication Error (401)

Missing Required Field (400)

Best Practices

Request Structure

API Key Management

Foreign Key Strategy

Lazy Mode Usage

Publisher Configuration

Related Models