Review Sources API

Review sources are external rating platforms (Google Business Profile, Trustpilot, Yelp, ProvenExpert, Trusted Shops, …) that Rankion polls and consolidates on a regular schedule. Through the API you manage sources, rotate auth keys, and optionally receive real-time updates via webhook — the only outbound-capable webhook endpoint of the entire Rankion API.

Module context: Review Sources · see also Webhooks.

rankion.aiManage sources

curl "$BASE/review-sources" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {id, platform, source_url, status, avg_rating, total_reviews, last_pull_at}'

rankion.aiAuth control

For each source there is one auth key (for key-based platforms) or one OAuth connection (for Google).

curl -X POST "$BASE/review-sources/4/rotate-key" \
  -H "Authorization: Bearer $TOKEN"

The response returns the new key exactly once — afterwards only masked (xxxx-…-1234). Save it to your config immediately.

rankion.aiSource onboarding

New sources are created through two paths: active webhook registration (for platforms with push support) or waitlist entry (for platforms not yet enabled).

curl -X POST "$BASE/review-sources/webhook" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"platform": "trustpilot", "source_url": "https://trustpilot.com/review/example.com"}'

rankion.aiPublic review webhook (inbound)

External platforms or Zapier/Make can push reviews directly into Rankion — this is the only public, key-authenticated endpoint of the API.

{source} is the slug of a source from GET /review-sources (e.g. trustpilot-example-com). Auth runs not through Authorization: Bearer but through the source-specific key from rotate-key. That lets you safely give the webhook URL to third-party systems without sharing the master token.

curl -X POST "https://rankion.ai/api/v1/webhooks/reviews/trustpilot-example-com" \
  -H "X-Rankion-Key: $SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "tp-987654",
    "rating": 5,
    "title": "Top service",
    "body": "Fast response, everything smooth.",
    "author": "Anna M.",
    "submitted_at": "2026-04-30T11:22:33Z",
    "url": "https://trustpilot.com/reviews/987654"
  }'

Response 200:

{"received": true, "review_id": 4521, "duplicate": false}

On duplicate: true the review was deduped via external_id — no new insert, no error.

rankion.aiNotes

• Webhook key ≠ API token. The X-Rankion-Key authorizes only pushes to that one source — it cannot read, change, or call anything else. A compromise is limited to fake reviews for that source.
• Rotate immediately on compromise. POST /rotate-key invalidates the old key atomically — in-flight requests with the old key get 401.
• Disconnect instead of DELETE if you only want to pause. DELETE also removes all pulled reviews from the DB (cascades).
• Cron pulls run automatically every 6 h per active source. Manual re-pull is (as of 2026-05) only possible via the UI.
• Google reviews go through OAuth, not source keys — see Google Integrations API.

Related: Google Integrations · Webhooks · Review Sources.