Referral ReactorDocs
← Back to app

Changelog

All notable changes to the Referral Reactor API are documented here in reverse chronological order. Entries are categorized as Added, Changed, Deprecated, or Removed. Breaking changes are marked with a [Breaking] label.

v1.3.0 — 2025-06-01

Added

  • GET /api/v1/organizations/{id}/stats — Returns aggregate referral and payment statistics for an organization (requires organizations:read scope).
  • Webhook endpoint management via API: POST /api/v1/webhooks, GET /api/v1/webhooks, GET /api/v1/webhooks/{id}, PATCH /api/v1/webhooks/{id}, DELETE /api/v1/webhooks/{id}.
  • X-ReferralReactor-Request-Id response header on all endpoints — matches the requestId field in error bodies for easier log correlation.

Changed

  • Rate limit window increased from 15 minutes to 60 minutes. The X-RateLimit-Reset header now reflects the longer window. Existing integrations are unaffected unless they relied on the 15-minute reset cadence.

v1.2.0 — 2025-04-14

Added

  • GET /api/v1/files/{storageId} — Retrieves a signed download URL for a file stored in Referral Reactor (e.g. referral photos). Requires referrals:read scope. Signed URLs expire after 1 hour.
  • include query parameter on GET /api/v1/referrals — Accepts a comma-separated list of related resources to embed in the response (e.g. include=bonusPayments).

v1.1.0 — 2025-03-03

Added

  • bonusPaymentStatus query parameter on GET /api/v1/referrals — Filter referrals by the status of their associated bonus payment (pending, processing, completed, failed).
  • search query parameter on GET /api/v1/referrals — Full-text search across referral names and notes. Minimum 2 characters required.
  • GET /api/v1/users/{id} — Retrieve a single user by their ID. Requires users:read scope.
  • Pagination support (page and limit query parameters) on GET /api/v1/users and GET /api/v1/referrals. Default page size is 50; maximum is 200.

Changed

  • [Breaking] GET /api/v1/referrals response shape changed: the top-level array is now wrapped in a { data: [...], pagination: { ... } } envelope to support pagination. Update any code that reads the response directly as an array.

v1.0.0 — 2025-01-20

Initial public release of the Referral Reactor REST API.

Added

  • Authentication — Clerk-issued Bearer token authentication with five scopes: referrals:read, referrals:write, users:read, users:write, organizations:read.
  • Rate limiting — Sliding-window rate limiting per API key with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers.
  • GET /api/v1/health — Unauthenticated health check endpoint.
  • GET /api/v1 — Returns API version and available endpoints.
  • GET /api/v1/referrals — List referrals for the authenticated organization (requires referrals:read).
  • POST /api/v1/referrals — Submit a new referral (requires referrals:write).
  • GET /api/v1/users — List users in the organization (requires users:read).
  • POST /api/v1/users — Create a new user (requires users:write).
  • GET /api/v1/organizations — Retrieve organization details (requires organizations:read).
  • Webhook system — 15 event types across referrals, bonus payments, and users. HMAC-SHA256 signature verification, 5-attempt exponential backoff retry policy, and auto-disable on repeated failures.
  • Consistent error shapes — All error responses include code, message, and requestId fields.

Next Steps