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.11.0 — 2026-10-14

Added

• Admin notes on CRM customers: GET and POST /api/v1/customers/{id}/admin-notes, PATCH and DELETE /api/v1/customers/{id}/admin-notes/{noteId}. They work like user and referral notes: admins only, organization keys may read (with customers:read) but not write, and only a note's author can edit or delete it. Returns 403 when the organization's CRM is turned off.
• Organization key scope referrals:delete (not granted by default).

Changed

• Organization API keys can now edit referrals: PATCH /api/v1/referrals/{id} (details, custom fields, status, referrer), POST /api/v1/referrals/{id}/restamp-company, and the photo endpoints (POST /photos/upload-url, POST /photos, DELETE /photos/{storageId}) need referrals:write. Changes made with an organization key show no person in the referral's history, and the referrer's notification names your organization.
• DELETE /api/v1/referrals/{id} with an organization key needs the new referrals:delete scope, which isn't granted by default. Personal keys are unchanged: super admins only.

v1.10.0 — 2026-10-13

Added

• Invitation codes: GET and POST /api/v1/invitation-codes, GET, PATCH and DELETE /api/v1/invitation-codes/{id}, and GET /api/v1/invitation-codes/{id}/qr (a PNG QR code of the code's join_url). Admins and organization keys manage every code; a marketer manages the codes they created. A used code can only be deactivated. New scopes: invitation-codes:read, invitation-codes:write.
• Public referral links: GET and POST /api/v1/public-links. Organization links and the caller's own links, each with its full url. New scopes: public-links:read, public-links:write.
• Associations: GET and POST /api/v1/users/{id}/associations and DELETE /api/v1/users/{id}/associations/{associationId}. Ending an association keeps it as ended (is_active: false, ended_at). Writes are for admins and organization keys.
• GET /api/v1/organizations/{id}/settings — Read-only organization settings, grouped like the Settings page: profile, branding, plan, referrers, referrals, bonus payments, public requests, BD portal and integrations. {id} is the organization's id, Clerk organization id or slug. Requires organizations:read; with a personal key, admins only. Bonus payment settings need bonus access (organization keys: bonus-payments:read).

Changed

• Organization keys can create and edit invitation codes, organization links and associations; they're recorded as the actor.

v1.9.0 — 2026-10-13

Added

• Referral stats and reports, read from the same totals as the app's dashboard and reports: GET /api/v1/stats/referrals, GET /api/v1/reports/referrals (per month or week, optionally grouped by referrer or company), GET /api/v1/reports/top-referrers, GET /api/v1/reports/top-companies and GET /api/v1/reports/bd-standings. Date ranges cover whole months or weeks and are capped at 24 months. Rates are fractions from 0 to 1.
• New reports:read scope for organization API keys. Payout figures also need bonus-payments:read.
• POST /api/v1/bonus-payments — Creates a bonus payment draft. It never sends money: a person reviews it in the app and chooses Approve and send or Discard. Personal API keys only, for super admins and people with Can send bonuses (organization keys get 403). Send an idempotency_key to make retries safe. The 201 response (and a 200 replay) includes id, status, awaiting_approval and an approval_url where a person approves or discards the draft.
• Items from GET /api/v1/bonus-payments carry awaitingApproval: true while a payment is a draft. The field is absent otherwise. Drafts are listed only for organization keys and for people who can send bonuses.

Changed

• POST /api/v1/bonus-payments returns 409 when an idempotency_key was already used with a different request, and 429 when the caller drafts too fast. A discarded draft frees its idempotency_key.

v1.8.0 — 2026-10-12

Added

• Conversations and messages: GET /api/v1/conversations, GET and POST /api/v1/conversations/{id}/messages, POST /api/v1/conversations/{id}/read, and POST /api/v1/referrals/{id}/conversation (gets or starts the referral's conversation). A person sees the conversations they're in, as in the app. Sending, starting a conversation and marking read need a personal API key. A sent message notifies everyone in the conversation exactly as one sent in the app. Images are read-only links.
• Organization key scope conversations:read (not granted by default) lets an organization key read every conversation and message.

v1.7.0 — 2026-10-12

Added

• BD portal endpoints for business developers, with personal API keys: GET /api/v1/bd/overview (rank, figures, open task counts), GET and POST /api/v1/bd/prospects, GET and PATCH /api/v1/bd/prospects/{id}, GET and POST /api/v1/bd/activities, GET and POST /api/v1/bd/tasks, PATCH and DELETE /api/v1/bd/tasks/{id}, and GET /api/v1/bd/goals (read-only).
• Reads take bd_user_id to read another business developer's portal when the app allows it; any denial is a 404. Writes act on your own portal only.
• PATCH /api/v1/bd/tasks/{id} takes exactly one of status (done or open), snooze: true, or task fields to edit.
• GET /api/v1/bd/activities pages can hold fewer than limit items while pagination.has_more is true. Keep following next_cursor.
• New tasks default to due tomorrow at 09:00 with a push reminder 1h_before; activities default to today. "Today" uses time_zone, then your saved time zone, then UTC.

Changed

• The BD portal needs a personal API key and the Unlimited plan. Organization keys get 403. Without bd_user_id, so does anyone who is not a business developer (a marketer, or an admin marked as a BDR); with it, anyone the app lets read that portal gets the data and everyone else a 404. Writes always need a business developer.

v1.6.0 — 2026-10-12

Added

• GET /api/v1/referrals/{id}/timeline — The referral's history, newest first, with each event's type, actor, time, a short summary and a few safe details. Edited values, payout details and message text are never included.
• Admin notes on users and referrals: GET and POST /api/v1/users/{id}/admin-notes, PATCH and DELETE /api/v1/users/{id}/admin-notes/{noteId}, and the same four under /api/v1/referrals/{id}/admin-notes. Admins only. Writes need a personal API key, and only a note's author can edit or delete it.

v1.5.0 — 2026-10-09

Added

• GET /api/v1/referrals/{id} is documented, and PATCH /api/v1/referrals/{id} edits a referral's details, address, notes, custom fields, status and referrer in one call. Custom fields are merged (send null to clear one) and keys may be field names or IDs. A combined edit is all-or-nothing. Changing referrerId is admin only.
• DELETE /api/v1/referrals/{id} — Deletes a referral (super admin only). Returns { id, deleted: true }.
• POST /api/v1/referrals/{id}/restamp-company — Sets the referral's company to its referrer's current company.
• Photos: POST /api/v1/referrals/{id}/photos/upload-url, POST /api/v1/referrals/{id}/photos and DELETE /api/v1/referrals/{id}/photos/{storageId}. Upload flow: get an upload URL and token, upload the bytes (JPEG, PNG or WebP, up to 10 MB), then attach with both uploadToken and storageId. A token covers one photo and expires after 24 hours.
• New filters on GET /api/v1/referrals: status (repeatable), search, label (repeatable), company, associated_user, created_from, created_to, updated_since, bonus and sort (created_desc, created_asc, updated_desc, updated_asc). For incremental sync, use updated_since=<last sync>&sort=updated_asc.
• Referral responses list labels as { _id, text, color }.

Changed

• Referral edits, deletes, re-stamps and photo changes need a personal API key. Organization keys get 403.
• [Breaking] Cursors issued before this release may return 400 INVALID_CURSOR; restart from the first page. Restart from the first page whenever you change sort or any filter, too: a cursor reused with a different sort or filter may be refused with INVALID_CURSOR.
• A page from GET /api/v1/referrals can hold fewer than limit items while meta.hasNext is true. Keep following meta.nextCursor.
• Bad created_from, created_to, updated_since, sort, bonus or status values return 400 naming the parameter. bonus is refused for callers who can't see bonus totals (organization keys, plain admins, business developers, referrers). Before this release it was silently ignored, so an integration that sends it with an organization key now gets a 400.
• The older names statuses, searchQuery, labelIds, minDate, maxDate, bonusPaymentFilter and sortOrder (newest | oldest) still work.
• A label or associated_user that isn't an ID in your organization returns 400. A malformed referral ID in the path returns 404.
• PATCH: lossReasonId and lossReasonNote only apply to a referral that is cancelled or being cancelled; otherwise 400. Malformed address, customFieldValues or referrerId values return 400 naming the field.
• PATCH custom fields: only the fields you change are checked, so a value stored before the organization changed its fields (for example a removed dropdown option, or a required field added later) no longer blocks an unrelated edit.
• When an edit changes both the referrer and the status, the status notification goes to the new referrer.
• Attaching a photo when the referral is at its plan's photo limit returns 403.
• The Referral schema's status values are new, acknowledged, in_progress, completed and cancelled, and the list response envelope is documented as { data: { data, meta }, requestId, timestamp }.

v1.4.0 — 2026-10-09

Added

• GET /api/v1/companies and GET /api/v1/companies/{id} — Companies with referrer and referral figures (credited by the company each referral was submitted under) and assigned BDRs. Requires companies:read. In the list, referral_count stops at 1,000 per company and a page reads at most 4,000 referrals in total; when referral_count_capped is true the count is a lower bound. The detail endpoint counts everything.
• PATCH /api/v1/companies/{id} — Rename a company or assign its BDR. Admins, personal API keys only.
• GET /api/v1/customers and GET /api/v1/customers/{id} — CRM customer records. Requires customers:read and the CRM turned on for the organization.
• New API key scopes: companies:read, customers:read.

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.

v1.1.0 — 2025-03-03

Added

• 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

• Getting Started — Make your first API call
• Authentication — API key scopes and rate limiting
• API Reference — Interactive reference for all endpoints
• Webhooks — Event types and signature verification