Skip to main content

Integrating with a customer engagement platform

You can integrate with any customer engagement platform, or CEP, using the following endpoints designed for 3rd-party tools, rather than your own integration layer.

note

These endpoints do not appear in the API reference documentation.

important

These endpoints are for general use with any platform. If you use Braze or Iterable, read the following tutorials instead:

PlatformTutorials
Braze
Iterable

The following endpoints are available:

Authenticating

All these endpoints rely on Talon.One's a 3rd-party API key of type Customer Engagement. To generate one:

  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 Customer Engagement from the dropdown.
  5. Select and expiry date and click Create API Key.
  6. Copy it for later use.

Use the key in the Authorization header of each of these endpoints:

Example:

Authorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3

Create coupon

To create a coupon from a CEP platform, use the following endpoint:

GET coupon
https://integration.talon.one/customer_engagement/coupon

Headers

ParameterDescriptionExample
Authorization*Required. API authorization keyApiKey-v1 <TOKEN>
customer-engagement-platform-name*Required. The name of the 3rd party platform.<name of the third party platform>
destination-hostname*Required. The external campaign id that should be referenced.https://mycompany.europe-west1.talon.one/
X-DRY-RUNIndicates whether to persist the changes. Changes are ignored when dry=truetrue

Path parameters

ParameterDescriptionExample
campaignId*Required. The ID of the campaign in Talon.One where the coupon will be created.34
applicationId*Required. The ID of the Application in Talon.One.12
externalCampaignId*Required. The external campaign id that should be referencedabc123
recipientIntegrationIDThe integration ID of the only customer that can use the generated coupon code. Leave blank to allow any user to use the coupon.abc123
discountLimitThe discount amount the coupon is worth. Can be blank if for example the coupon provides a 10% discount or something other than a set value of discounts.1.23
startDateTime when the coupon starts becomes valid.2020-12-31T13:00:00Z
expiryDateTime when the coupon stops being valid.2021-12-31T13:00:00Z
AttributesObject containing all the coupon attributes to set on the coupon.

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: &.email=john.doe@example.com.

note

You can modify the shape of Talon.One-generated coupon codes for any campaign:

  1. Open your campaign.
  2. Click Settings > Coupon codes.

Response example

{
"ID": 12715850,
"ApplicationID": 270,
"CampaignID": 3882,
"DiscountLimit": null,
"Value": "SUMMER-K35A",
"StartDate": null,
"ExpiryDate": null,
"RecipientIntegrationID": null,
"UsageLimit": 1,
"UsageCounter": 0,
"Attributes": {}
}

Create referral

To create a referral from a CEP platform, use the following endpoint:

GET referral
https://integration.talon.one/customer_engagement/referral

Headers

ParameterDescriptionExample
Authorization*Required. API authorization keyApiKey-v1 <TOKEN>
customer-engagement-platform-name*Required. The name of the 3rd party platform.<name of the third party platform>
destination-hostname*Required. The external campaign id that should be referenced.https://mycompany.europe-west1.talon.one/
X-DRY-RUNIndicates whether to persist the changes. Changes are ignored when dry=truetrue

Path parameters

ParameterDescriptionExample
campaignIdRequired. The ID of the campaign in Talon.One where the referral code will be created.34
externalCampaignIdRequired. The external campaign id that should be referencedabc123
advocateprofileintegrationidRequired. The integration ID of the advocateabc123
friendprofileintegrationidThe profile ID of the referred customer.abc123
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.1.23
startDateDate when the referral code can be used.2020-12-31T13:00:00Z
expiryDateDate when the referral code can't be used anymore.2020-12-31T13:00:00Z
AttributesObject containing all the coupon attributes to set on the coupon.

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: &.email=john.doe@example.com.

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
}

Fetch loyalty ledger

To fetch a loyalty ledger from a CEP, use the following endpoint:

GET loyalty
https://integration.talon.one/customer_engagement/loyalty

Headers

ParameterDescriptionExample
AuthorizationRequired. API authorization key.ApiKey-v1 TOKEN
customer-engagement-platform-nameRequired. Third party name.<name of the third party platform>
destination-hostnameRequired. The external campaign id that should be referenced.https://mycompany.europe-west1.talon.one/

Path parameters

ParameterDescriptionExample
profileIntegrationIDRequired. The integration ID of the customer profile in Talon.One.abc123
loyaltyProgramIDRequired. The ID of the loyalty program in Talon.One.34
projectionEndDateRequired. The end date to query the projected loyalty balances. You can project results up to 31 days from today.2020-12-31T13:00:00Z

Response example

{
"id": 302,
"title": "My loyalty program",
"name": "myloyaltyprogram",
"ledger": {
"currentBalance": 0,
"pendingBalance": 0,
"expiredBalance": 0,
"spentBalance": 0,
"tentativeCurrentBalance": 0,
"projection": {
"projections": [
{
"date": "2021-11-11T00:00:00Z",
"expiringPoints": 0,
"activatingPoints": 0,
"projectedBalance": 0
},
{
"date": "2021-11-12T00:00:00Z",
"expiringPoints": 0,
"activatingPoints": 0,
"projectedBalance": 0
},
],
"totalExpiringPoints": 0,
"totalActivatingPoints": 0
}
},
"subLedgers": {}
}