Record Referral
Record a referral that you already know, for example from a support ticket or a sales call: the referee (by kind and your external ID; RefRef creates it when it does not know it), the referrer (by kind and external ID, or by its referral code, the only way to name a partner), and the Program. The referrer must be enrolled in the Program now. A referee that already has a referral is a conflict. The referral has no binding fact: Events that RefRef receives after it use it. A write applies at once. Needs the referrals:write key permission.
Authorization
WorkspaceApiKey Workspace-owned Better Auth API key of one environment (Sandbox or Live); it authorizes the Projects of that environment in its Workspace. A Project of the other environment returns 403 ENVIRONMENT_MISMATCH. Never expose it in the browser.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/referrals" \ -H "Content-Type: application/json" \ -d '{ "projectId": "string", "programId": "string", "referee": { "kind": "individual", "externalId": "string" } }'{ "success": true, "referralId": "string", "programId": "string", "referrerParticipantId": "string", "refereeParticipantId": "string", "touchId": "string", "touchKind": "click", "boundAt": "string"}Publish Reward Terms POST
Previous Page
Created Webhook
RefRef bound a referral: attribution found a referrer for the referee of an Event or a Subscription, or you recorded the referral. RefRef POSTs the event to each enabled endpoint of the Project that subscribes to referral.created, and retries for about 72 hours until the endpoint answers 2xx.