Skip to main content

Creating referral codes through Iterable

In this tutorial, let's set up Talon.One and Iterable to have Iterable automatically request a user-specific referral code directly from Talon.One.

For example, let's imagine that:

  • We are sending an email to users in some segment.
  • We want to include user-specific referral codes worth 10% off purchases over $20.

With this integration, you can automate the process of creating those referral codes via Talon.One and displaying them in the promotional email from Iterable.


If you're not using Iterable, see the generic customer engagement platform endpoints.

Rate limiting recommendations

Contact your Iterable CSM for implementation support.

Talon.One requirements

  1. You have an Application and campaign in Talon.One.
  2. You have a least 2 customer profiles in Talon.One. These profiles also exist in Iterable.
  3. You have set up a referral program your Application. For more information, see the Help Center.

Iterable requirements

  1. You have created a campaign and template.
  2. You have a way to identify a given customer across Talon.One and Iterable. In this tutorial, we assume a customer's Talon.One integrationId also exists in Iterable. For example, You can create a new property on your Iterable customer profiles called talonone_id to store Talon.One's integration ID.

Creating 3rd-party API key

Let's generate a Talon.One API key that we will use for a 3rd-party service, in our case, Iterable.

  1. Navigate to the developer settings of your Talon.One Application.
  2. Click Create API Key
  3. For Do you want to use this API Key with a 3rd party service?, select Yes.
  4. Select Iterable from the dropdown.
  5. Select and expiry date and click Create API Key.
  6. Copy it for later use.

The integration endpoint for referrals

To generate the referral in Iterable, we call the following endpoint:

GET referral

Authentication scheme

Use the Authorization header with a Iterable-specific API key generated in Talon.One.


Authorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3

Path parameters

The endpoint supports the following path parameters:

deployment*Required. The base URL of your deployment.
applicationID*Required. The ID of the Application in Talon.One.
campaignID*Required. The ID of the campaign in Talon.One where the referral code will be created.
iterableCampaignId*Required. The ID of the campaign in Iterable.
advocateProfileIntegrationId*Required. The integration ID of the advocate.
friendProfileIntegrationIdThe profile ID of the referred customer.
usageLimitnumber of times a referral code can be used. This can be set to 0 for no limit, but any campaign usage limits will still apply
startDateDate when the referral code can be used.
expiryDateDate when the referral code can't be used anymore.

To set a custom attribute, add the attribute name and value as an extra query parameter prefixed with a .. For example, if you have an email attribute, set it with: &

Response example

"id": 803,
"created": "2021-11-08T08:53:42.251326815Z",
"usageLimit": 1,
"campaignId": 3882,
"advocateProfileIntegrationId": "Customer1234",
"friendProfileIntegrationId": "Customer9876",
"attributes": {},
"code": "E3VY-XP5E",
"usageCounter": 0

Generating the URI

Generate the URI with the following form:

You can now use this URI inside Iterable.

Configuring Iterable

Creating the data feed

In Iterable, create a new data feed to pull in referral codes:

  1. Click Content > Data Feeds > Create New Feed.
  2. Choose a name, for example Talon.One referral code.
  3. In URL, paste the generated URI.
  4. Set Format to JSON.
  5. In Authorization token, type ApiKey-v1 and enter your the API generated earlier.

Creating a template and linking the data feed

  1. Create an Iterable template that will be used for your marketing campaign

  2. In the Advanced Options tab, select your Talon.One data feed.

    For more information about data feeds, see the Iterable docs.

  3. Reference the referral code and/or entire response from Talon.One within the email template by using square brackets.

    For example: Your referral code is [[code]]!.

    See the Iterable Docs.

  4. Check the template and placement of the data feed response by using the Preview with data tool.

  5. Click Load template feed in order to bring in the data feed response data into the template.