Referrals
Create, retrieve, and list referral records tracking customer-to-customer referrals.
A referral tracks when one customer (the referrer) brings a new customer (the referred) to your
platform. Referrals move through a lifecycle from pending to qualified to rewarded as the
referred customer meets your program's conditions.
Illustrative content. Hand-authored to demonstrate the Standard/Advanced pattern; the production page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.
The referral objectAsk
idstringUnique identifier for the referral, e.g. ref_2Dm5kW.
referrer_customerobjectExpandableThe customer who made the referral. Expand to retrieve the full customer object.
referred_customerobjectExpandableThe customer who was referred. Expand to retrieve the full customer object.
statusenumOne of pending (referred customer signed up), qualified (referral conditions met), or
rewarded (reward has been issued to the referrer).
reward_amountintegerThe reward value issued to the referrer in the smallest currency unit, once the referral reaches
rewarded status. null until that point.
createdintegerUnix timestamp when this referral record was created.
Create a referralAsk
Record a new referral by providing the referrer and referred customer IDs. The referral starts in
pending status and transitions automatically as conditions are met.
Retrieve a referralAsk
Fetch a referral by its ID. Expand referrer_customer or referred_customer to include the full
customer objects inline.
List referralsAsk
Returns a paginated list of referrals. Filter by referrer_customer to see all referrals made by a
specific customer.
| Parameter | Type | Description |
|---|---|---|
referrer_customer | string | Filter by the referring customer's ID. |
limit | integer | Number of results to return. Default 10, max 100. |
Related eventsAsk
referral.created, referral.qualified, and referral.rewarded. See Events.
