API Reference

Introduction

The Reviewlee API is a RESTful API that allows you to programmatically manage every aspect of your review infrastructure. All endpoints are versioned under /api/v1/ and return JSON responses.

• RESTful endpoints with JSON request/response bodies
• API key authentication with granular scopes (read, write, admin)
• Paginated list endpoints with consistent meta format
• Webhook support for real-time event notifications

Base URL

All API requests should be made to the following base URL. All endpoints require the /api/v1/ prefix.

The API is versioned via URL path. The current version is v1. We will announce deprecation of older versions well in advance.

Authentication

Authenticate API requests using Bearer authentication with your organization API key. Keys start with rk_ and are scoped to a single organization.

curl -X GET https://api.reviewlee.com/api/v1/reviews \
  -H "Authorization: Bearer rk_your_api_key_here"

Rate Limiting

API requests are rate-limited per API key. Rate limit headers are included in every response to help you track usage.

Pagination

All list endpoints support pagination via page and limit query parameters. Responses include a meta object with total count and page information.

// Paginated response format
{
  "data": [...],
  "meta": {
    "total": 47,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

// Query parameters
GET /api/v1/reviews?page=2&limit=10

Reviews

Reviews are the core resource. List, retrieve, moderate, and submit reviews via these endpoints. Reviews cannot be deleted — only hidden via moderation with full audit trail.

Response Example

{
  "id": "cm...",
  "rating": 5,
  "title": "Excellent service",
  "content": "Great experience with the product!",
  "reviewer_name": "Jane Doe",
  "reviewer_email": "[email protected]",
  "verification_status": "verified",
  "is_hidden": false,
  "created_at": "2026-01-15T12:00:00Z",
  "form_id": "cm..."
}

Review Forms

Review forms define how reviews are collected. Configure verification modes, custom fields, and public submission links.

Organizations

Manage organization settings, team members, and invitations. All data is scoped to the organization associated with your API key.

Exports

Export review data as CSV or JSON. Exports run asynchronously — create a job, then poll or download when ready.

// Create an export job
POST /api/v1/organizations/:orgId/exports
{
  "format": "csv",   // "csv" or "json"
  "filters": {
    "startDate": "2026-01-01",
    "endDate": "2026-02-01"
  }
}

Webhooks

Receive real-time notifications when events occur in your organization. Webhook payloads are signed with HMAC-SHA256 for verification.

// Webhook payload example
{
  "event": "review.created",
  "timestamp": "2026-02-15T10:30:00Z",
  "data": {
    "id": "cm...",
    "rating": 5,
    "content": "Amazing product!",
    "reviewer_name": "John Smith"
  }
}

// Verify HMAC signature
const signature = request.headers["x-webhook-signature"];
const expected = crypto
  .createHmac("sha256", webhookSecret)
  .update(JSON.stringify(body))
  .digest("hex");

Embed Widget

Embed your reviews on any website with a lightweight JavaScript widget. Supports list, grid, and carousel layouts with light and dark themes.

<!-- Embed reviews on any website -->
<div id="reviewlee-widget" data-slug="your-business-slug"></div>
<script src="https://www.reviewlee.com/embed.js"></script>

Public Profiles

Public business profiles are SEO-indexed pages showing reviews with aggregate ratings. Manage profile settings and access public data.

API Keys

Create, list, rotate, and revoke API keys for your organization. Keys are scoped with read, write, or admin permissions.

Verification

Verify reviews using multiple methods. Each review form can be configured with a specific verification mode.

Review Requests

Automate review collection by sending email requests to customers. Support for single and bulk sends with delivery tracking.

Error Handling

The API uses conventional HTTP status codes. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.

// Error response format
{
  "statusCode": 401,
  "message": "Invalid or expired API key",
  "error": "Unauthorized"
}