Developer documentation
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.
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_...
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.
/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"
}
}/companies/{domain}/reviewsList 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
}
}
}"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.
/providers/batch-upsertCreate 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
}
}
]
}/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 } }/providers/{id}/reviewsA 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 }
}
}/providers/{id}/reviewsSubmit 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" } }/reviews/exportIncremental 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 } ]
}
}Per-key limits are enforced based on the subscription plan of the provider or establishment (or account) that issued the key.
| Plan | Requests / minute | Requests / month |
|---|---|---|
| Free | — (no API access) | — |
| Professional · $49/mo | 100 | 100,000 |
| Enterprise · $250/mo | 1,000 | 1,000,000 |
Each response includes the headers X-RateLimit-Limit and X-RateLimit-Tier so you can size your worker concurrency accordingly.
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.
curl https://toptenreviews.org/api/v1/companies/example.com \ -H "Authorization: Bearer ct_live_..."
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()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()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.