Developer documentation

Top Ten Reviews API

A small, versioned REST surface for reading verified review data. Pass your key as a Bearer token and you're done — there's no SDK to install.

Authentication

Every request must carry a Bearer token in the Authorization header. Generate keys from your API Keys dashboard or from a provider's or establishment's Integrations tab.

Authorization: Bearer ct_live_...
API access is a Professional or Enterprise feature. Keys belonging to a Free-tier account are rejected with HTTP 403.

Base URL

https://toptenreviews.org/api/v1

All responses are JSON. Successful responses have a top-level data field; list responses also include a meta field with pagination info.

Endpoints

GET/companies/{domain}

Look up a provider or establishment by its primary domain.

Response

{
  "data": {
    "id": "uuid",
    "slug": "example-com",
    "name": "Example Inc.",
    "domain": "example.com",
    "website": "https://example.com",
    "category": "software",
    "subcategory": "saas",
    "description": "...",
    "logo_url": "https://...",
    "rating": 4.7,
    "review_count": 1523,
    "verified": true,
    "profile_url": "https://toptenreviews.org/review/example.com",
    "created_at": "2025-...Z"
  }
}
GET/companies/{domain}/reviews

List published reviews for a provider or establishment, newest first.

Query parameters

  • limit — Page size. Default 20, max 100.
  • offset — Zero-based offset for pagination.
  • rating — Filter to a specific star rating (1–5).

Response

{
  "data": [
    {
      "id": "uuid",
      "rating": 5,
      "title": "Excellent service",
      "content": "Best experience I've had in months...",
      "author": {
        "name": "John D.",
        "verified": true,
        "verification_type": "purchase"
      },
      "helpful_count": 42,
      "pinned": false,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "company": {
      "id": "uuid",
      "name": "Example Inc.",
      "domain": "example.com",
      "average_rating": 4.7,
      "total_reviews": 1523
    },
    "pagination": {
      "limit": 20,
      "offset": 0,
      "total": 1523,
      "has_more": true
    }
  }
}

Partner endpoints

These endpoints are for partner directories and are enabled for partner (admin-issued) keys only. Other keys get HTTP 403 with "code": "plan_required". A batch counts as one request against your rate limit.

Providers you send are linked by source + external_id, scoped to your key's account, so another partner can never change your links. Profiles claimed by their owner or edited by our team are never overwritten; otherwise the item with the newer source_updated_at wins. Photos are copied to our storage (not hotlinked) shortly after the response.

When an update changes an unclaimed provider's name, its slug and URLs change with it. The old profile and review page URLs keep working as 301 redirects, and the provider object in the response has the new slug and URLs, so store those. An old write_review_url still opens the review form for that provider.

To correct a name without changing the ad, send the same source_listing_url and source_updated_at with the new display_name. Only the name is applied. Any other change needs a newer source_updated_at.

POST/providers/batch-upsert

Create or update up to 100 providers. Idempotent. Matching order: your existing link for (source, external_id); then the same phone number in the same city, which merges and adds your external_id as an alias; otherwise a new published provider (creating the province or city if needed, with a slug unique in its city). Rejected items don't fail the batch.

Request body

{
  "source": "erosradar",
  "items": [
    {
      "external_id": "tel:3f9a1c2b",            // required, ≤128, stable
      "title": "Jessica - upscale GFE downtown", // required, ≤200
      "display_name": "Jessica",                // optional; the provider's name. Derived from title if absent
      "country": "usa",                         // usa | canada
      "state_slug": "new-york",
      "state_name": "New York",
      "state_code": "NY",                       // required for usa
      "city_slug": "new-york",
      "city_name": "New York",
      "category": "providers",
      "description": "Plain text, ≤2000",
      "age": 27,                                // 18–79
      "area_label": "Midtown",
      "incall": true,
      "outcall": false,
      "phone": "+12125550123",                  // E.164; used for matching
      "photo_urls": ["https://..."],            // ≤10 https URLs
      "source_listing_url": "https://partner.example/ad/123",
      "source_updated_at": "2026-11-01T18:30:00Z"
    }
  ]
}

Response

{
  "data": [
    {
      "external_id": "tel:3f9a1c2b",
      "status": "created",          // created | updated | merged | unchanged | rejected
      "error": null,                // or { "code": "invalid_item", "message": "..." }
      "provider": {
        "id": "uuid",
        "slug": "jessica",
        "name": "Jessica",
        "profile_url": "https://toptenreviews.org/states/new-york/new-york/providers/jessica",
        "review_page_url": "https://toptenreviews.org/review/jessica-new-york-ny",
        "city_url": "https://toptenreviews.org/states/new-york/new-york",
        "write_review_url": "https://toptenreviews.org/write-review?company=jessica-new-york-ny",
        "rating": null,
        "review_count": 0
      }
    }
  ]
}
GET/providers/{id}

One provider by its id (UUID), as the provider object above.

Response

{ "data": { "id": "uuid", "slug": "jessica", "name": "Jessica", "profile_url": "...", "review_page_url": "...", "city_url": "...", "write_review_url": "...", "rating": 4.8, "review_count": 12 } }
GET/providers/{id}/reviews

A provider's published reviews, newest first. Same review shape and pagination as /companies/{domain}/reviews; meta.provider replaces meta.company.

Query parameters

  • limit — Page size. Default 20, max 100.
  • offset — Zero-based offset for pagination.
  • rating — Filter to a specific star rating (1–5).

Response

{
  "data": [ { "id": "uuid", "rating": 5, "title": "...", "content": "...", "author": { ... }, "helpful_count": 3, "pinned": false, "created_at": "..." } ],
  "meta": {
    "provider": { "id": "uuid", "name": "Jessica", "rating": 4.8, "review_count": 12 },
    "pagination": { "limit": 20, "offset": 0, "total": 12, "has_more": false }
  }
}
POST/providers/{id}/reviews

Submit a review written on your site. It enters our moderation queue as pending with verification_type "partner". Idempotent on external_review_id: a replay returns 200 with the same id and the review's current status. author_email and submitted_ip are kept private and used for abuse checks only.

Request body

{
  "external_review_id": "rv_8812",   // required, idempotency key
  "source": "erosradar",             // optional; defaults to the source you linked the provider with
  "rating": 5,                       // 1–5
  "title": "Lovely evening",         // ≤120
  "content": "20–5000 characters...",
  "author_name": "Mike",             // ≤60, shown publicly
  "author_email": "mike@example.com",// optional, private
  "submitted_ip": "203.0.113.7"      // optional, private
}

Response

HTTP 201  { "data": { "id": "uuid", "status": "pending" } }
HTTP 200  (replay) { "data": { "id": "uuid", "status": "pending" } }
GET/reviews/export

Incremental feed of reviews for every provider linked to your source, ordered by (updated_at, id). Store meta.next_cursor and pass it back until it is null; keep the last updated_at you saw for the next run. Rejected, unpublished (including your still-pending submissions) and deleted reviews appear with status removed so you can drop them.

Query parameters

  • source — Required. Your source id, e.g. erosradar.
  • updated_since — ISO-8601. Only reviews changed at or after this time.
  • cursor — meta.next_cursor from the previous page.
  • limit — Page size. Default and max 500.

Response

{
  "data": [
    {
      "id": "uuid",
      "provider_id": "uuid",
      "external_ids": ["tel:3f9a1c2b", "ad:lc_991"],
      "rating": 5,
      "title": "...",
      "content": "...",
      "author": { "name": "Mike", "verified": false, "verification_type": "partner" },
      "helpful_count": 0,
      "pinned": false,
      "status": "approved",           // approved | removed
      "created_at": "2026-11-01T19:02:11.104Z",
      "updated_at": "2026-11-02T08:15:42.552013Z"
    }
  ],
  "meta": {
    "next_cursor": "WyIyMDI2LTEx...",  // null on the last page
    "providers": [ { "id": "uuid", "rating": 4.8, "review_count": 12 } ]
  }
}

Rate limits

Per-key limits are enforced based on the subscription plan of the provider or establishment (or account) that issued the key.

PlanRequests / minuteRequests / month
Free— (no API access)—
Professional · $49/mo100100,000
Enterprise · $250/mo1,0001,000,000

Each response includes the headers X-RateLimit-Limit and X-RateLimit-Tier so you can size your worker concurrency accordingly.

Error codes

  • 400 — invalid_json, invalid_request, invalid_id, invalid_rating, invalid_source, invalid_updated_since or invalid_cursor.
  • 401 — missing_auth or invalid_key: missing, malformed, or revoked key.
  • 403 — plan_required: the key's account has no API plan, or (partner endpoints) the key is not a partner key. Upgrade on /business/upgrade.
  • 404 — not_found: no such provider or establishment.
  • 429 — rate_limited. Wait for Retry-After seconds.
  • 500 — internal_error: transient server error. Retry with backoff.

All error responses are JSON: { "error": "human-readable message", "code": "snake_case" }. Rejected batch items use the same { code, message } shape in their error field.

Examples

cURL

curl https://toptenreviews.org/api/v1/companies/example.com \
  -H "Authorization: Bearer ct_live_..."

JavaScript (fetch)

const res = await fetch(
  'https://toptenreviews.org/api/v1/companies/example.com/reviews?limit=20',
  { headers: { Authorization: 'Bearer ct_live_...' } }
)
if (!res.ok) throw new Error(`API ${res.status}`)
const { data, meta } = await res.json()

Python (requests)

import requests

r = requests.get(
    "https://toptenreviews.org/api/v1/companies/example.com/reviews",
    headers={"Authorization": "Bearer ct_live_..."},
    params={"limit": 20, "rating": 5},
)
r.raise_for_status()
payload = r.json()

Ready to start?

Generate your first key from the dashboard. You'll need an active Professional or Enterprise subscription on the provider or establishment that owns the key.