API & Webhooks

Trigger review requests from your booking system, POS, or CRM, and get an event the moment a review or private feedback arrives. Create a key under Developers in your dashboard.

Authentication

Pass your key as a bearer token on every request. You get the full key once, at creation; store it somewhere safe. You can also send it as an X-API-Key header.

Authorization: Bearer rbr_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

GET /api/v1/me checks a key and returns the account it belongs to: { id, name, slug }.

Send a review request

POST /api/v1/review-requests creates a tracked review link and sends it by SMS or email. Prepaid credit is charged at 10c per SMS segment or 2c per email. Longer texts cost more; a failed send is refunded. The response below is illustrative; costCents varies with message length.

curl -X POST https://rankbyreviews.com/api/v1/review-requests \
  -H "Authorization: Bearer $RBR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10432" \
  -d '{
    "channel": "SMS",
    "phone": "+61412345678",
    "name": "Jordan"
  }'

Response 201:

{
  "id": "clx...",
  "token": "rAbC...",
  "link": "https://rateus.au/r/rAbC...",
  "channel": "SMS",
  "to": "+61412345678",
  "status": "sent",
  "costCents": 10
}

• • channel — "SMS" or "EMAIL" (required).
• • phone / email — the recipient, matching the channel (required).
• • name — optional, personalises the message.
• • message — optional custom body with {name}, {business}, {link} placeholders. Leave {link} out and we append the review link for you.
• • Idempotency-Key — optional header; a retry with the same key returns the first result and never sends twice.

We refuse contacts who have unsubscribed (422). Insufficient credit returns 402. API requests never trigger automatic reminder texts.

Read your stats

GET /api/v1/stats returns your funnel numbers and credit balance. Optional ?days=30 (1–365) for a trailing window.

curl https://rankbyreviews.com/api/v1/stats?days=30 -H "Authorization: Bearer $RBR_KEY"

List recent reviews and feedback

Two read endpoints return your newest items in the same shape as the webhook payloads below. Use them for backfills or to load samples into a polling tool.

curl https://rankbyreviews.com/api/v1/reviews?limit=10  -H "Authorization: Bearer $RBR_KEY"
curl https://rankbyreviews.com/api/v1/feedback?limit=10 -H "Authorization: Bearer $RBR_KEY"

limit is optional: 1–50, default 10, newest first.

Webhooks

Add an https:// endpoint under Developers and pick your events. We POST a JSON body and sign it so you can be sure it came from us.

• • review.received — a new Google review synced to your account.
• • feedback.received — a customer left private feedback through your funnel.

Each delivery carries these headers:

X-RBR-Event: review.received
X-RBR-Delivery: 7c9f...        (unique per delivery)
X-RBR-Timestamp: 1752900000     (unix seconds)
X-RBR-Signature: sha256=<hex>

Verify by computing an HMAC-SHA256 of `${timestamp}.${rawBody}`with your endpoint's signing secret and comparing it to the signature. Reject anything older than five minutes to prevent replay.

import crypto from "crypto";

function verify(rawBody, headers, secret) {
  const ts = headers["x-rbr-timestamp"];
  const got = headers["x-rbr-signature"];
  if (typeof ts !== "string" || !/^[0-9]+$/.test(ts)) return false;
  if (typeof got !== "string" || !/^sha256=[a-f0-9]{64}$/.test(got)) return false;
  if (!Number.isSafeInteger(Number(ts))) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(ts + "." + rawBody).digest("hex");
  return got.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

Respond 2xx within a few seconds. We retry on 5xx, 408, 429and timeouts, then back off, and we pause an endpoint that keeps failing. Re-enable it from Developers once it's fixed.

Subscribe by API

Everything you can do under Developers you can also do over REST; Zapier-style tools manage their hooks this way. Subscribe one URL to one event:

curl -X POST https://rankbyreviews.com/api/v1/hooks \
  -H "Authorization: Bearer $RBR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/rbr", "event": "review.received" }'

201 returns { id, url, event, secret }. The signing secret appears only in this response. Subscribe the same URL and event again and you get the existing id with 200 (a paused endpoint comes back enabled), so retries never create duplicates.

• • GET /api/v1/hooks — list your endpoints (we never return secrets).
• • DELETE /api/v1/hooks/<id> — unsubscribe; responds 204 even if the endpoint is already gone.

URLs must be https:// and publicly routable. API and dashboard endpoints share one limit of 10 per account.

Need a hand? Email [email protected].