Referrals#

A referral links an Advocate’s offer to a Friend’s purchase or event. Talkable creates the referral when it matches the purchase or event to the Advocate, and checks it against your fraud rules. Talkable approves pending referrals when your approval period ends, and issues the rewards that qualify.

If you run your own approval process, your backend can also approve or void a referral with the Referrals API while its status is pending or flagged.

Talkable approves a pending referral automatically when the approval period ends; optionally, your backend can approve it earlier or void it through the API. Talkable approves a pending referral automatically when the approval period ends; optionally, your backend can approve it earlier or void it through the API.

Referral statuses#

Status

Meaning

in_progress

Talkable is processing the referral

pending

The referral waits for the approval period to end

flagged

A fraud rule flagged the referral for review

approved

The referral is approved, and Talkable issues the rewards that qualify. Final status

blocked

A fraud rule blocked the referral

voided

The referral is canceled, and its rewards are voided. Final status

Set the approval period in Fraud Settings under Pending referrals. See Referrals Approval.

Approve or void a referral#

Call PUT /api/v2/origins/{origin_slug}/referral with the API key. For origin_slug, use the Friend’s order number. For an event, use its category and number, such as third_payment:4512:

{
  "site_slug": "example-site",
  "data": {
    "status": "voided"
  }
}

Send approved to issue the rewards that qualify, or voided to cancel the referral.

Talkable creates referrals in the background. If a call right after the purchase returns 400 with No referral found for given origin. or Status cannot be transitioned from 'in_progress', retry it later.

Example use cases#

Approve early. Send approved when your system confirms the Friend’s order, for example when it ships, before the approval period ends.

Void after your review. Send voided when your team rejects a pending or flagged referral.

Returns. Report the refund with the Origins API. A full refund voids a pending or flagged referral.

Note

To issue rewards only after your API approval, ask your Customer Success Manager.