Origins

The Talkable Origins API allows the registration of ‘off-site’ or ‘backend’ purchases or CRM events so they can be used in the referral flow. This functionality is generally utilized by businesses using subscription billing, off-site transactions, or other off-site events.

Note

The standard front-end Talkable integration will capture all one-time purchases happening on the client e-commerce site, but will not on its own capture purchases or CRM events happening on the backend. To do this, the Origins API must be utilized to feed ‘off-site’ or ‘backend’ purchases or CRM events to Talkable.

Example use cases for the Origins API

Subscription:

  • A company whose customers sign up for a monthly service by making an initial ‘on-site’ payment, then are charged monthly on the backend for subsequent subscription payments. This company would like to reward Advocate users (referrers) with a reward after their Friend has been a member for three billing cycles.
    • Talkable’s standard front-end integration captures the initial ‘on-site’ payment.
    • For Talkable to reward the Advocate after the third billing cycle of the Friend subscription, the Company must pass the subsequent subscription data to Talkable’s Origins API using "type": "Event".

Off-Site Events:

  • A company whose customers purchase product or perform events off-site. This company would like to reward Advocate users (referrers) with a reward after their Friend has purchased a product in the brick and mortar store, or attended an in-person appointment.
    • Talkable’s standard front-end integration captures an initial ‘on-site’ signup event if there is one.
    • For Talkable to reward the Advocate after the in-person Friend store purchase, or appointment attendance, the Company must pass the in store purchase, or appointment attendance data to Talkable’s Origins API with either "type": "Purchase" for a purchase or "type": "Event" for an appointment attendance.

User Approval:

  • User approval use cases start with customers who need to submit an application by performing an initial ‘on-site’ sign-up event. This company would like to reward Advocate users (referrers) with a reward after their Friend application is approved.
    • Talkable’s standard front-end integration captures the initial ‘on-site’ application sign-up event.
    • In order for Talkable to reward the Advocate after the Friend application approval, the Company must pass the approval data to Talkable’s Origins API using "type": "Event".


POST /origins
Parameter Description
site_slug Your Talkable Site ID. You can get this from your Talkable dashboard after you log in and create a site.
type Type of origin to create (“AffiliateMember”, “Purchase” or “Event”)
data

Hash or JSON object with following properties:

Common Fields:

  • email
  • customer_id (optional)
  • first_name (optional)
  • last_name (optional)
  • person_custom_properties (optional)
  • uuid (optional) - uuid given to a visitor on a claim page. See Referral Program via API
  • ip_address (optional) - IP address of client who is making the request. You might pass current string as a value so remote IP will be used
  • traffic_source (optional) - specific Traffic Source value that helps to distinguish different points of integration
  • campaign_tags (optional) - campaign tags for offer targeting
  • sharing_channels (optional) - array of social sharing channels for which will be generated sharing links

For Purchase:

  • subtotal
  • order_number
  • items (optional)
  • coupon_code (optional)

For Event:

  • event_number
  • event_category
  • subtotal (optional)
  • coupon_code (optional)

Example

Create a purchase

{
  "site_slug": "my-store",
  "type": "Purchase",
  "data": {
    "email": "customer@example.com",
    "order_number": 12,
    "subtotal": 100,
    "uuid": "b3967d36-4e7f-46bc-92b3-57344347cd6a",
    "items": [
      {
        "price": 25,
        "quantity": 4,
        "product_id": "TSHIRT"
      }
    ]
  }
}
curl -H "Content-Type: application/json" \
     -X POST \
     -u i9uil7nQgDjucCiTJu: \
     -d '{"site_slug":"my-store","type":"Purchase","data":{"email":"customer@example.com","order_number":12,"subtotal":100,"items":[{"price":25,"quantity":4,"product_id":"TSHIRT"}]}}' \
     https://www.talkable.com/api/v2/origins

Sample response:

{
  "ok": true,
  "result": {
    "origin": {
      "id": 31386398,
      "order_number": 12,
      "subtotal": 100.0,
      "customer_id": null,
      "ip_address": "127.0.0.1",
      "type": "Purchase",
      "coupon_code": ""
    },
    "offer": null
  }
}

Create an event

{
  "site_slug": "my-store",
  "type": "Event",
  "data": {
    "email": "customer@example.com",
    "event_category": "newsletter_subscription",
    "event_number": "42"
  }
}
curl -H "Content-Type: application/json" \
     -X POST \
     -u i9uil7nQgDjucCiTJu: \
     -d '{"site_slug":"my-store","type":"Event","data":{"email":"customer@example.com","event_category":"newsletter_subscription","event_number":"42"}}' \
     https://www.talkable.com/api/v2/origins

Sample response:

{
  "ok": true,
  "result": {
    "origin": {
      "id": 46141478,
      "type": "Event",
      "event_number": "42",
      "event_category": "newsletter_subscription",
      "customer_id": null,
      "ip_address": "127.0.0.1",
      "coupon_code": ""
    },
    "offer": null
  }
}

Create an affiliate member and target a campaign

{
  "site_slug": "my-store",
  "type": "AffiliateMember",
  "data": {
    "email": "affiliate@example.com",
    "campaign_tags": ["invite"]
  }
}
curl -H "Content-Type: application/json" \
     -X POST \
     -u i9uil7nQgDjucCiTJu: \
     -d '{"site_slug":"my-store","type":"AffiliateMember","data":{"email":"affiliate@example.com","campaign_tags":["invite"]}}' \
     https://www.talkable.com/api/v2/origins

Sample response:

{
  "ok": true,
  "result": {
    "origin": {
      "id": 31386400,
      "email": "affiliate@example.com",
      "customer_id": null,
      "ip_address": "127.0.0.1",
      "type": "AffiliateMember"
    },
    "offer": {
      "id": 89238912,
      "short_url_code": "Jp8qY9",
      "email": "affiliate@example.com",
      "show_url": "https://www.talkable.com/x/5BN5h7",
      "claim_url": "https://www.talkable.com/x/TM2OhR"
    }
  }
}