The Refly REST API.

You'll need an API key. Grab one from /admin/developers — start with a rf_test_… key, promote to rf_live_… when you're wiring production traffic.

Every request needs an Authorization: Bearer header. Send the key from your backend only — never from a public frontend bundle.

curl https://clever-porcupine-923.convex.site/api/v1/health

Include the key on every request. Test keys allow read-only lookups in the same tenant. Test POST requests validate inputs and return dry_run: true without creating referrals, events, or commissions.

Authorization: Bearer rf_live_xxxxxxxxxxxxxxxx

Keys are hashed at rest. If a key leaks, revoke it from /admin/developers and issue a new one — old requests start returning 401 immediately.

Every request is scoped to the tenant that owns the key. You cannot read or write another program's data even if you know the IDs.

Call this from your signup handler as soon as you know the referral code (usually from a URL param or cookie). Refly attributes the signup to the partner behind that code and returns the referral ID for later events.

curl -X POST https://clever-porcupine-923.convex.site/api/v1/referrals \
  -H "Authorization: Bearer rf_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "referral_code": "juan-abc",
    "referred_email": "maria@rojas.com",
    "referred_name": "Maria Rojas",
    "referred_phone": "+59160000000",
    "utm_source": "landing",
    "utm_medium": "signup_form"
  }'

Response

{
  "referral_id": "kn7...",
  "partner_id": "k97...",
  "status": "signed_up",
  "created": true
}

Returns 201 for new referrals, 200 for upgrades of an existing invite, and 200 with duplicate: true when the email already exists in the tenant.

Advance a referral through your funnel. Refly generates the commission automatically once you send event_type: "activated" (or whatever your tenant is configured to trigger on).

curl -X POST https://clever-porcupine-923.convex.site/api/v1/events \
  -H "Authorization: Bearer rf_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "referral_id": "kn7...",
    "event_type": "activated",
    "occurred_at": "2026-08-31T18:22:14Z"
  }'

Allowed event types

• clicked
• signed_up
• kyc_pending
• kyc_approved
• activated
• churned

Read the tenant's referrals. Newest first.

curl "https://clever-porcupine-923.convex.site/api/v1/referrals?limit=25&status=activated" \
  -H "Authorization: Bearer rf_live_xxxxxxxxxxxxxxxx"

Query params: limit (default 50, max 200), status (optional, an event type above or invited), and cursor (optional). Responses include data, count, nextCursor, and isDone. Pass nextCursor as the next request's cursor with the same filters until isDone is true.

Useful for showing "Referred by X" on your signup page before creating the referral row.

curl "https://clever-porcupine-923.convex.site/api/v1/partners?code=juan-abc" \
  -H "Authorization: Bearer rf_live_xxxxxxxxxxxxxxxx"