Referral program via API

The Talkable API lets you run a referral program from a mobile app or your backend. You create the Advocate’s offer and show their referral link. The Advocate shares it, and you record the share. A Friend opens the link and lands on your site or app. When the Friend buys, you report the purchase, and Talkable attributes the referral and issues the rewards.

You set up campaigns, rewards, reward A/B tests, fraud checks, and emails in Talkable, and changes apply without an app release. Each call is described in full in the Talkable API reference.

How it works

The integration has four steps:

Steps 1, 2, and 4 are POST calls to paths under /api/v2:

1. Create the Advocate’s offer — required. Talkable returns the referral link and the current rewards. Call /origins/affiliate_member.

2. Record the share — recommended. Talkable counts the share and issues a sharing reward if the campaign has one. Call /offers/{short_url_code}/shares/social.

3. The Friend opens the link — no call. Talkable records the click, creates the Friend’s offer, and sends the Friend to your site or app.

4. Report the purchase or event — required. Talkable creates the referral when it matches the purchase to the Advocate. Call /origins/purchase or /origins/event.

Talkable issues the rewards that qualify after your approval period. You can also track custom activities, such as steps in your app, at any point.

Choose an API key

Pick the integration by where your code runs:

Where your code runs	What to use
Website pages	Talkable integration script
Mobile app	Public API key
Your backend	API key, the private key. Keep it on your server

A mobile app can also call your backend, which calls Talkable.

The two keys are in All site settings → Integrations → API integration:

• Public API key — safe to ship in an app. It can create offers, record shares and custom activities, and report purchases and refunds. It can’t read person profiles or call the Referrals API.

• API key — the private key. It can also read and update people, approve or void referrals, and read campaigns and metrics. Keep it on your server.

Send the key as a Bearer token. site_slug is the Site ID shown with the keys:

curl 'https://www.talkable.com/api/v2/origins/affiliate_member' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"site_slug": "example-site", "data": {"email": "jane@example.com"}}'

Send site_slug in the JSON body for origins and in the query string for most other calls. The share calls don’t take it.

Create the Advocate’s offer

An origin is an action you report to Talkable: a person joining the program (Affiliate Member), a purchase, or another event. Create an Affiliate Member origin when the signed-in Advocate opens your referral screen. Talkable picks the campaign and returns the Advocate’s offer. A repeat call for the same person and campaign returns the same offer.

Send POST /api/v2/origins/affiliate_member with this body:

{
  "site_slug": "example-site",
  "data": {
    "email": "jane@example.com",
    "campaign_tags": "invite",
    "ip_address": "current",
    "traffic_source": "ios-app"
  }
}

Field	Use
email	The Advocate’s email. Use the same email in every call for this person
campaign_tags	Selects the campaign. A campaign must carry all the tags you send. Copy the tag from Campaign tags in the campaign’s rules
ip_address	Used to pick the offer’s currency and language, and in fraud checks. From the app, send current to use the request’s IP. From your backend, send the user’s IP address
traffic_source	A label for reporting, for example ios-app or android-app

Talkable gives the offer only to people who meet the campaign’s criteria. When no campaign matches, the call succeeds with "offer": null. Show your screen without a referral link in that case.

Keep these fields from result.offer:

Field	Use
short_url_code	The offer’s stable identifier. Use it to record shares
claim_url	The referral link the Advocate shares. It changes over time. Share the link from the latest response
incentives	The rewards to show on your screen
show_url	The Advocate share page hosted by Talkable

See Create an Affiliate Member origin in the API reference.

Advocate Impressions

Call this endpoint when the Advocate opens your referral screen, not when the app starts. Each call that returns an offer counts as an Advocate Impression, once per offer in two minutes. Advocacy percentage divides Sharers by Advocate Impressions.

Note

Whether API calls count Advocate Impressions depends on your site’s settings. Ask your Customer Success Manager to check it for your site.

Show the offer

You can show the offer on your own screen or on the hosted share page:

• Your own screen — build it from offer.incentives. Each entry has a description, such as “$10 off”, and the for_advocate and for_friend flags that say who gets the reward. If you format amount yourself, check percentage to tell a percentage from a fixed amount.

• Hosted share page — open show_url. You design the page in Talkable, and Talkable shows it in the Advocate’s language.

Either way, the rewards come from the live campaign. A reward you change in Talkable shows in the next response. When the campaign runs an A/B test of its rewards, incentives shows the variant assigned to the offer.

To show the Advocate a reward they earned, use offer.coupon_code: the coupon of their largest reward. It stays empty until that reward is approved.

Record the share

When the Advocate shares the link, record the share with the offer’s short_url_code and the channel. For the offer a1B2c3, send POST /api/v2/offers/a1B2c3/shares/social with this body:

{
  "channel": "other"
}

Use other with claim_url for a copied link, or for a share sheet that doesn’t say which app was picked. If the campaign rewards sharing, the response carries the Advocate’s sharing reward.

To track a specific channel, add sharing_channels inside data in the origin request, for example ["sms", "whatsapp"]. The response then has result.claim_links with one link per channel. Share the link of the channel the Advocate picked, and record the share with the same channel. Use your site’s channels, such as sms, whatsapp, or facebook.

A repeat call within five minutes on other, sms, or whatsapp returns the existing share. If you don’t record a share, Talkable records one when a Friend opens the link, with an estimated time.

To have Talkable send the campaign’s share email, call POST /api/v2/offers/{short_url_code}/shares/email with the Friend’s addresses in recipients, separated by commas, for example "anna@example.com,ben@example.com". In the response, currently_sent is true for each address that this call shared the offer with.

See Share via social channel and Share via email in the API reference.

The Friend opens the link

The referral link always goes through Talkable first. Talkable records the click, creates the Friend’s offer, and runs fraud checks. Then the Friend goes to your site or app in one of two ways, set per campaign:

• Friend Claim Page on — the default. The Friend sees their offer on a page you design in Talkable, and continues to the destination URL. With Email gating for friend, the page asks for their email first.

• Friend Claim Page off — the Friend goes straight to the destination URL. Pass the coupon in the URL with {{ coupon.code }}. This option needs Email gating for friend turned off in the campaign.

Keep the page on when Friends may need to install your app first. Talkable can then match a purchase made with the email entered on the page. Turn the page off when your app opens straight from the link. See Friend Claim Page.

Note

You can’t turn off email gating when:

• the Friend’s reward uses Triggers only once per person, as in the standard campaign

• a reward uses a coupon list with Require Customer

• the campaign has an opt-in reward

The default destination URL carries the Friend’s visitor ID in the tkbl_cvuuid parameter. Store it when the Friend lands, and send it as uuid with their purchase. For a mobile app, use a deep link to your app as the site URL, and keep tkbl_cvuuid={{ visitor_uuid }} in any custom destination URL. See Deep linking on iOS and Deep linking on Android.

Report purchases and events

Report each order with POST /api/v2/origins/purchase. Send the buyer’s email and any coupon used:

{
  "site_slug": "example-site",
  "data": {
    "email": "friend@example.com",
    "order_number": "100125",
    "subtotal": 49.95,
    "coupon_code": "FRIEND10",
    "uuid": "0f2a6c3e-5b1d-4c8e-9f6a-2d4b8e1c0a57"
  }
}

Talkable matches the purchase to the Advocate, for example by uuid, the Friend’s coupon, or the email from the claim page. A match creates a referral. Your campaign’s criteria and fraud rules decide which rewards qualify. Talkable issues them after your approval period, with reward emails and any webhooks you set up. See Referral Tracking Methods.

To retry a purchase, send the same request again. A known order_number with a different email or subtotal returns an error. On a site with several currencies, add currency_iso_code.

For an action that isn’t an order, such as a paid subscription or an approved application, send POST /api/v2/origins/event with an event_category and an event_number. In the campaign, set the Advocate’s reward criterion Friend event category to the same category.

Track custom activities

A custom activity records an action that Talkable can’t see on its own, such as a step in your app. For example, send referral_page_viewed when the referral screen opens, and contacts_invited with the number of invited contacts. The Custom Activities report lists every activity. See Custom activities and Track a custom activity.

Test the integration

Test with an email on your account’s QA list. An account admin manages it in the user menu under Account settings → QA Allow-list. Emails at your store’s domain are on the list by default. Reports mark QA referrals and activities, and dashboard tiles leave QA data out.

Send the tag exactly as Campaign tags shows it. A new campaign in test mode has a test- prefix on its tags, such as test-invite. Update the tag in your integration when you launch the campaign.

Go through the flow once and check each result:

1. The offer request returns an offer with a claim_url.

2. The share request returns "ok": true with the share.

3. The referral link opens the Friend Claim Page or your destination URL.

4. The purchase request returns "ok": true with the origin.

5. The Referrals report shows the referral with the right Advocate, Friend, and rewards.

6. Your custom activities appear in the Custom Activities report.

Next steps

• Custom activities: record actions in your app or on campaign pages.

• Origins: report subscriptions, in-store purchases, and other events, and report refunds.

• Referrals: approve or void referrals from your backend.

• React Native: build the flow in a React Native app.