Third-party API reference docs (1.0.0)

Download OpenAPI specification:Download

Use the Third-party API from Talon.One's technology partners.

For example, use the Braze-specific endpoints from your Braze campaigns to interact with Talon.One.

If the CDP or CEP you are using isn't listed here, use the generic Customer Data Platforms and Customer Engagement Platform endpoints.

Are you looking for a different API? If you need the API to:

Integrate with Talon.One directly and send real-time data, see the Integration API reference docs.
Interact with the Campaign Manager for backoffice operations, see the Management API reference docs.

Authentication

ApiKeyAuth

To authenticate in order to use these endpoints, generate an API key in the Campaign Manager:

Log on to the Campaign Manager and open the Application of your choice, or create one.
Click Settings > Developer settings.
Click Create API Key.
Give it a title.
For Do you want to use this API Key with a 3rd party service?, select Yes and choose the platform to integrate with.
Set an expiration date. then click Create API Key.

You can now use the API key in the Authorization HTTP header of your requests, prefixing it with ApiKey-v1:

Authorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3

Security Scheme Type	API Key
Header parameter name:	Authorization

Braze

Braze is a customer engagement platform to manage customer-centric interactions between consumers and brands in real-time.

Use these endpoints to automate the creation of coupon and referral codes and deliver them to specific customer segments. To send requests to these endpoints, use the connected content feature in Braze.

For more information, see our integration examples in the developer docs.

Create referral

Create a referral code in Talon.One. To use it in your Braze deployment, see the tutorial.

Authorizations:

ApiKeyAuth

header Parameters

X-DRY-RUN

boolean

Example: true

Indicates whether to persist the changes. Changes are ignored when dry=true.

Request Body schema: application/json

deploymentUrl required	string The base url of your deployment.
campaignId required	integer <int64> >= 1
advocateProfileIntegrationId required	string non-empty
friendProfileIntegrationId	string non-empty
startDate	string <date-time> The date when the code becomes usable.
expiryDate	string <date-time> The date when the code becomes unsable.
usageLimit	integer <int64> >= 0 Default: 0 Set the usage limit of the referral to unlimited.
attributes	object

Responses

Request samples

Payload

Content type

application/json

{"deploymentUrl": "mycompany.europe-west1.talon.one",
"campaignId": 5672,
"advocateProfileIntegrationId": "2",
"friendProfileIntegrationId": "3",
"startDate": "2021-09-30T15:35:02.371569+02:00",
"expiryDate": "2021-10-03T15:35:02.371569+02:00",
"usageLimit": 3,
"attributes": {"welcome_message": "Welcome!"
}
}

Response samples

200
400
401
404
429

Content type

application/json

{"id": 1374,
"created": "2022-04-01T16:46:36.625152002Z",
"startDate": "2021-09-30T15:35:02.371569+02:00",
"expiryDate": "2021-10-03T15:35:02.371569+02:00",
"usageLimit": 0,
"campaignId": 5672,
"advocateProfileIntegrationId": "URN-GV8294NV",
"friendProfileIntegrationId": "PKBR-G06449OELK",
"attributes": {"welcome_message": "Welcome!"
},
"code": "P8BN-4T5V",
"usageCounter": 0
}

Create coupon

Create a coupon code in Talon.One. To use it in your Braze deployment, see the tutorial.

You can also use this endpoint to get an existing coupon's details by setting the identifier property to a value you previously used.

Authorizations:

ApiKeyAuth

Request Body schema: application/json

deploymentUrl required	string The base URL of your Talon.One deployment.
applicationId required	integer <int64> >= 1 The ID of the Application in Talon.One.
campaignId required	integer <int64> >= 1 The ID of the campaign in Talon.One.
identifier required	string non-empty The identifier of the request. Providing a new value creates a new coupon. Providing an existing value retrieves the existing coupon of that id. In general, you should set it to a variable controlled by Braze. Usual values include: `message_api_id` `variant_api_id` `dispatch_id` See Supported personalization tags and dispatch ID behavior.
usageLimit	integer <int64> Default: 1 The usage limit of the coupon.
integrationId	string The integration ID of the customer profile. When specified, only that customer will be able to use the coupon.
startDate	string <date-time> The start date of the coupon.
expiryDate	string <date-time> The expiry date of the coupon.
validCharacters	Array of strings The list of allowed characters to be used when generating the code.
couponPattern	string The coupon pattern to use. Use `#` to represent a random character picked from `validCharacters`.
attributes	object Arbitrary properties associated with item.

Responses

Request samples

Payload

Content type

application/json

{"deploymentUrl": "mycompany.europe-west1.talon.one",
"applicationId": 398,
"campaignId": 5671,
"identifier": "test-coupon",
"usageLimit": 4,
"integrationId": "URN-GV8294NV",
"startDate": "2021-09-30T15:35:02.371569+02:00",
"expiryDate": "2024-10-03T15:35:02.371569+02:00",
"validCharacters": ["A",
"B",
"C",
"1",
"2"
],
"couponPattern": "ew-####",
"attributes": {"venueId": "BER4271",
"venueName": "Admiralspalast"
}
}

Response samples

200
400
401
404
429

Content type

application/json

{"ID": 20190408,
"ApplicationID": 398,
"CampaignID": 5671,
"Value": "EW-1BC2",
"StartDate": "2021-09-30T15:35:02.371569+02:00",
"ExpiryDate": "2024-10-03T15:35:02.371569+02:00",
"RecipientIntegrationID": "URN-GV8294NV",
"UsageLimit": 1,
"UsageCounter": 0,
"Attributes": {"email": "user@mailbox.com",
"country": "DE"
}
}

Track event

Triggers a custom event. You can then check this event in your rules and apply an effect, such as adding loyalty points, or anything else.

For more information, see the tutorial.

Authorizations:

ApiKeyAuth

header Parameters

destination-hostname

required

string <hostname>

Example: https://mycompany.europe-west1.talon.one/

The base URL of your Talon.One deployment.

Request Body schema: application/json

eventType required	string <string> The event type, as defined in Talon.One when you created the custom attribute representing this event.
type required	string <string> Enum: "string" "time" "number" "boolean" "location" The data type of the event, as defined in Talon.One when you created the custom attribute representing this event.
customerProfileId required	string <string> <= 1000 characters Unique Customer Profile ID.
identifier required	string non-empty The identifier of the request. Providing a new value sends a new event to Talon.One. Providing an existing value retrieves the existing event of that id. In general, you should set it to a `dispatch_id` variable controlled by Braze. See dispatch ID behavior.
	object Arbitrary properties associated with this entity

Responses

Request samples

Payload

Content type

application/json

{"eventType": "myBrazeEvent",
"type": "string",
"eventAttributes": {"Language": "english",
"ShippingCountry": "DE"
},
"customerProfileId": "URN-GV8294NV",
"identifier": "NNjETb6XxDV7hQhLMA"
}

Response samples

200
400
401
404
429

Content type

application/json

{"customerProfile": {"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"accountId": 6,
"attributes": {"Language": "english",
"ShippingCountry": "DE"
},
"integrationId": "URNGV8294NV",
"closedSessions": 3,
"totalSales": 299.99,
"audienceMemberships": [{"id": 6,
"name": "audience1"
}
],
"lastActivity": "2020-02-08T14:15:20Z"
},
"event": {"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"applicationId": 322,
"profileId": "string",
"type": "pageViews",
"attributes": {"Language": "english",
"ShippingCountry": "DE"
},
"sessionId": "175KJPS947296",
"effects": [[4208,
20095,
0,
["showNotification",
"Info",
"My title",
"My content"
]
]
],
"ledgerEntries": [{"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"profileId": "string",
"accountId": 0,
"loyaltyProgramId": 323414846,
"eventId": 0,
"amount": 100,
"reason": "string",
"expiryDate": "2019-08-24T14:15:22Z",
"referenceId": 0
}
],
"meta": {"campaigns": { },
"coupons": { },
"couponRejectionReason": {"campaignId": 244,
"couponId": 4928,
"reason": "CouponNotFound"
},
"referralRejectionReason": {"campaignId": 0,
"referralId": 0,
"reason": "ReferralNotFound"
},
"warnings": { }
}
}
}

Customer data platforms

You can integrate with any customer data platform, or CDP, using the following endpoints designed for third-party tools, rather than your own integration layer.

Use these endpoints to automate the creation of coupon and referral codes and deliver them to specific customer segments.

Update customer profile

Update the given customer profile to add or remove audiences.

Authorizations:

ApiKeyAuth

path Parameters

customerProfileId

required

string

Example: URN-GV8294NV

The integration ID of the customer profile.

header Parameters

customer-data-platform-name required	string <string> Example: My CDP platform The name of the CDP platform.
destination-hostname required	string <hostname> Example: https://mycompany.europe-west1.talon.one/ The base URL of your Talon.One deployment.

Request Body schema: application/json

	object Arbitrary properties associated with this entity
runRuleEngine	boolean Default: false Indicates whether to run the rule engine. Setting this property to `false` improves response times. For audiences changes the runRuleEngine should be true. Default value is `false`.
	object

Responses

Request samples

Payload

Content type

application/json

{"attributes": {"Language": "english",
"ShippingCountry": "DE"
},
"runRuleEngine": false,
"audiencesChanges": {"adds": [1,
2,
3
],
"deletes": [4,
5,
6
]
}
}

Response samples

200
400
401
404
429

Content type

application/json

{"customerProfile": {"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"accountId": 6,
"attributes": {"Language": "english",
"ShippingCountry": "DE"
},
"integrationId": "URNGV8294NV",
"closedSessions": 3,
"totalSales": 299.99,
"audienceMemberships": [{"id": 6,
"name": "audience1"
}
],
"lastActivity": "2020-02-08T14:15:20Z"
},
"createdAttributes": [{"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"accountId": 6,
"entity": "CustomerProfile",
"eventType": "string",
"name": "country",
"title": "Country",
"type": "string",
"description": "a description",
"suggestions": ["suggestion1",
"suggestion2"
],
"hasAllowedList": false,
"restrictedBySuggestions": false,
"editable": true,
"subscribedApplicationsIds": [10,
20,
100
],
"eventTypeId": 22
}
]
}

Create audience

Create an audience. The audience can be created directly from scratch or can come from third party platforms.

Once you create your first audience, audience-specific rule conditions are enabled in the Rule Builder.

Authorizations:

ApiKeyAuth

header Parameters

customer-data-platform-name required	string <string> Example: My CDP platform The name of the CDP platform.
destination-hostname required	string <hostname> Example: https://mycompany.europe-west1.talon.one/ The base URL of your Talon.One deployment.

Request Body schema: application/json

audienceId required	string <string> [ 1 .. 1000 ] characters The ID of this audience. If the audience comes from a third-party platform, set this property to the ID given by the third-party platform.
audienceName required	string <string> [ 1 .. 1000 ] characters The human-friendly display name for this audience.

Responses

Request samples

Payload

Content type

application/json

{"audienceId": "382370BKDB946",
"audienceName": "Travel audience"
}

Response samples

Content type

application/json

{"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"accountId": 6,
"name": "Travel audience",
"integration": "My platform name",
"integrationId": "382370BKDB946"
}

Delete audience

Delete an audience created by a third-party integration.

Warning: This endpoint also removes any associations recorded between a customer profile and this audience.

Authorizations:

ApiKeyAuth

path Parameters

audienceId

required

integer <int64>

Example: 4729630

The ID of the audience.

header Parameters

customer-data-platform-name required	string <string> Example: My CDP platform The name of the CDP platform.
destination-hostname required	string <hostname> Example: https://mycompany.europe-west1.talon.one/ The base URL of your Talon.One deployment.

Responses

Response samples

400
401
404
429

Content type

application/json

{"StatusCode": 400,
"Error": "No Deployment URL specified",
"RequestUUID": "fd2f7c55-d064-46e1-ab87-a39cb877cd82"
}

Update audience

Update an audience created by a third-party integration.

Authorizations:

ApiKeyAuth

path Parameters

audienceId

required

integer <int64>

Example: 4729630

The ID of the audience.

header Parameters

customer-data-platform-name required	string <string> Example: My CDP platform The name of the CDP platform.
destination-hostname required	string <hostname> Example: https://mycompany.europe-west1.talon.one/ The base URL of your Talon.One deployment.

Request Body schema: application/json

audienceId required	string <string> [ 1 .. 1000 ] characters The ID of this audience. If the audience comes from a third-party platform, set this property to the ID given by the third-party platform.
audienceName required	string <string> [ 1 .. 1000 ] characters The human-friendly display name for this audience.

Responses

Request samples

Payload

Content type

application/json

{"audienceId": "382370BKDB946",
"audienceName": "Travel audience"
}

Response samples

200
400
401
404
429

Content type

application/json

{"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"accountId": 6,
"name": "Travel audience",
"integration": "My platform name",
"integrationId": "382370BKDB946"
}

Customer engagement platforms

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

Use these endpoints to automate the creation of coupon and referral codes and deliver them to specific customer segments.

For more information, see our integration examples in the developer docs.

Create coupon

Create a coupon code in Talon.One. See the tutorial.

Authorizations:

ApiKeyAuth

query Parameters

applicationId required	integer <int64> Example: applicationId=316 The ID of the Application in Talon.One.
campaignId required	integer <int64> Example: campaignId=5843 The ID of the campaign in Talon.One.
externalCampaignId required	string Example: externalCampaignId=testCampaignId The external campaign ID that should be referenced.
startDate	string <date-time> Example: startDate=2022-09-30T15:35:02Z The date when the code becomes usable.
expiryDate	string <date-time> Example: expiryDate=2022-10-30T15:35:02Z The date when the code becomes unusable.
discountLimit	integer <int64> Example: discountLimit=155 The 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.
recipientIntegrationId	string Example: recipientIntegrationId=URN-GV8294NV The integration ID of the only customer that can use the generated coupon code. Leave blank to allow any user to use the coupon.
usageLimit	integer <int64> Default: 1 Example: usageLimit=1 The number of times the coupon code can be redeemed. 0 means unlimited redemptions but any campaign usage limits will still apply. The default value is 1.
	object Example: .email=user@mailbox.com&.country=DE Object containing the attributes to set and their values. The attributes can be passed in by prefixing them with a `.`.

header Parameters

customer-engagement-platform-name required	string Example: My CEP platform The name of the third-party platform.
destination-hostname required	string <hostname> Example: https://mycompany.europe-west1.talon.one/ The base URL of your Talon.One deployment.
X-DRY-RUN	boolean Example: true Indicates whether to persist the changes. Changes are ignored when `dry=true`.

Responses

Response samples

200
400
401
404
429

Content type

application/json

{"ID": 20190408,
"ApplicationID": 398,
"CampaignID": 5671,
"Value": "EW-1BC2",
"StartDate": "2021-09-30T15:35:02.371569+02:00",
"ExpiryDate": "2024-10-03T15:35:02.371569+02:00",
"RecipientIntegrationID": "URN-GV8294NV",
"UsageLimit": 1,
"UsageCounter": 0,
"Attributes": {"email": "user@mailbox.com",
"country": "DE"
}
}

Create referral

Create a referral code in Talon.One. See the tutorial.

Authorizations:

ApiKeyAuth

query Parameters

campaignId required	integer <int64> Example: campaignId=5843 The ID of the campaign in Talon.One.
advocateProfileIntegrationId required	string Example: advocateProfileIntegrationId=testAdvocateProfile The integration ID of the advocate.
friendProfileIntegrationId	string Example: friendProfileIntegrationId=testFriendProfile The profile ID of the referred customer.
startDate	string <date-time> Example: startDate=2022-09-30T15:35:02Z The date when the code becomes usable.
expiryDate	string <date-time> Example: expiryDate=2022-10-30T15:35:02Z The date when the code becomes unusable.
usageLimit	integer <int64> Example: usageLimit=1 Number 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.
	object Example: .email=user@mailbox.com&.country=DE Object containing the attributes to set and their values. The attributes can be passed in by prefixing them with a `.`.

header Parameters

customer-engagement-platform-name required	string Example: My CEP platform The name of the third-party platform.
destination-hostname required	string <hostname> Example: https://mycompany.europe-west1.talon.one/ The base URL of your Talon.One deployment.
X-DRY-RUN	boolean Example: true Indicates whether to persist the changes. Changes are ignored when `dry=true`.

Responses

Response samples

200
400
401
404
429

Content type

application/json

{"id": 1374,
"created": "2022-04-01T16:46:36.625152002Z",
"startDate": "2021-09-30T15:35:02.371569+02:00",
"expiryDate": "2021-10-03T15:35:02.371569+02:00",
"usageLimit": 0,
"campaignId": 5672,
"advocateProfileIntegrationId": "URN-GV8294NV",
"friendProfileIntegrationId": "PKBR-G06449OELK",
"attributes": {"welcome_message": "Welcome!"
},
"code": "P8BN-4T5V",
"usageCounter": 0
}

Get loyalty ledger

Get the loyalty ledger information of the given customer profile from Talon.One. See the tutorial.

Authorizations:

ApiKeyAuth

query Parameters

profileIntegrationId required	string Example: profileIntegrationId=URN-GV8294NV The integration ID of the customer profile in Talon.One.
loyaltyProgramId required	integer <int64> Example: loyaltyProgramId=25 The ID of the loyalty program in Talon.One.
projectionEndDate required	string <date-time> Example: projectionEndDate=2022-10-30T15:35:02Z The end date to query the projected loyalty balances. You can project results up to 31 days from today.

header Parameters

customer-engagement-platform-name required	string Example: My CEP platform The name of the third-party platform.
destination-hostname required	string <hostname> Example: https://mycompany.europe-west1.talon.one/ The base URL of your Talon.One deployment.

Responses

Response samples

200
400
401
404
429

Content type

application/json

{"id": 302,
"title": "My loyalty program",
"name": "myloyaltyprogram",
"ledger": {"currentBalance": 10.5,
"pendingBalance": 5.1,
"expiredBalance": 2,
"spentBalance": 0,
"tentativeCurrentBalance": 0,
"pointsToNextTier": 10,
"currentTier": {"id": 112345,
"name": "silver-tier"
},
"projection": {"totalExpiringPoints": 4,
"totalActivatingPoints": 4.2,
"projections": [{"date": "2021-11-11T00:00:00Z",
"expiringPoints": 2.7,
"activatingPoints": 2.9,
"projectedBalance": 200
}
]
}
},
"subLedgers": {"property1": {"currentBalance": 10.5,
"pendingBalance": 5.1,
"expiredBalance": 2,
"spentBalance": 0,
"tentativeCurrentBalance": 0,
"pointsToNextTier": 10,
"currentTier": {"id": 112345,
"name": "silver-tier"
},
"projection": {"totalExpiringPoints": 4,
"totalActivatingPoints": 4.2,
"projections": [{"date": "2021-11-11T00:00:00Z",
"expiringPoints": 2.7,
"activatingPoints": 2.9,
"projectedBalance": 200
}
]
}
},
"property2": {"currentBalance": 10.5,
"pendingBalance": 5.1,
"expiredBalance": 2,
"spentBalance": 0,
"tentativeCurrentBalance": 0,
"pointsToNextTier": 10,
"currentTier": {"id": 112345,
"name": "silver-tier"
},
"projection": {"totalExpiringPoints": 4,
"totalActivatingPoints": 4.2,
"projections": [{"date": "2021-11-11T00:00:00Z",
"expiringPoints": 2.7,
"activatingPoints": 2.9,
"projectedBalance": 200
}
]
}
}
}
}

Iterable

Iterable is a cross-channel marketing platform that powers unified customer experiences and empowers you to create, optimize and measure every interaction across the entire customer journey.

Use these endpoints to automate the creation of coupon and referral codes and deliver them to specific customer segments. To send requests to these endpoints, use the data feed feature in Iterable.

For more information, see our integration examples in the developer docs.

Create coupon

Create a coupon code in Talon.One. To use it in your Iterable deployment and generate the request, see the tutorial.

Authorizations:

ApiKeyAuth

query Parameters

deployment required	string Example: deployment=company.talon.one The base URL of your deployment.
applicationId required	integer <int64> Example: applicationId=316 The ID of the Application in Talon.One.
campaignId required	integer <int64> Example: campaignId=5843 The ID of the campaign in Talon.One.
iterableCampaignId required	string Example: iterableCampaignId=iterableCampaign The ID of the campaign in Iterable.
startDate	string <date-time> Example: startDate=2022-09-30T15:35:02Z The date when the code becomes usable.
expiryDate	string <date-time> Example: expiryDate=2022-10-30T15:35:02Z The date when the code becomes unusable.
discountLimit	integer <int64> Example: discountLimit=155 The 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.
recipientIntegrationId	string Example: recipientIntegrationId=URN-GV8294NV The integration ID of the only customer that can use the generated coupon code. Leave blank to allow any user to use the coupon.
usageLimit	integer <int64> Default: 1 Example: usageLimit=1 The number of times the coupon code can be redeemed. 0 means unlimited redemptions but any campaign usage limits will still apply. The default value is 1.
	object Example: .email=user@mailbox.com&.country=DE Object containing the attributes to set and their values. The attributes can be passed in by prefixing them with a `.`.

Responses

Response samples

200
400
401
404
429

Content type

application/json

{"ID": 20190408,
"ApplicationID": 398,
"CampaignID": 5671,
"Value": "EW-1BC2",
"StartDate": "2021-09-30T15:35:02.371569+02:00",
"ExpiryDate": "2024-10-03T15:35:02.371569+02:00",
"RecipientIntegrationID": "URN-GV8294NV",
"UsageLimit": 1,
"UsageCounter": 0,
"Attributes": {"email": "user@mailbox.com",
"country": "DE"
}
}

Create referral

Create a referral code in Talon.One. To use it in your Iterable deployment and generate the request, see the tutorial.

Authorizations:

ApiKeyAuth

query Parameters

deployment required	string Example: deployment=company.talon.one The base URL of your deployment.
campaignId required	integer <int64> Example: campaignId=5843 The ID of the campaign in Talon.One.
advocateProfileIntegrationId required	string Example: advocateProfileIntegrationId=testAdvocateProfile The integration ID of the advocate.
friendProfileIntegrationId	string Example: friendProfileIntegrationId=testFriendProfile The profile ID of the referred customer.
startDate	string <date-time> Example: startDate=2022-09-30T15:35:02Z The date when the code becomes usable.
expiryDate	string <date-time> Example: expiryDate=2022-10-30T15:35:02Z The date when the code becomes unusable.
usageLimit	integer <int64> Example: usageLimit=1 Number 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.
	object Example: .email=user@mailbox.com&.country=DE Object containing the attributes to set and their values. The attributes can be passed in by prefixing them with a `.`.

Responses

Response samples

200
400
401
404
429

Content type

application/json

{"id": 1374,
"created": "2022-04-01T16:46:36.625152002Z",
"startDate": "2021-09-30T15:35:02.371569+02:00",
"expiryDate": "2021-10-03T15:35:02.371569+02:00",
"usageLimit": 0,
"campaignId": 5672,
"advocateProfileIntegrationId": "URN-GV8294NV",
"friendProfileIntegrationId": "PKBR-G06449OELK",
"attributes": {"welcome_message": "Welcome!"
},
"code": "P8BN-4T5V",
"usageCounter": 0
}

Get loyalty ledger

Get the loyalty ledger information of the given customer profile from Talon.One. To use it in your Iterable deployment and generate the request, see the tutorial.

Authorizations:

ApiKeyAuth

query Parameters

deployment required	string Example: deployment=company.talon.one The base URL of your deployment.
profileIntegrationId required	string Example: profileIntegrationId=URN-GV8294NV The integration ID of the customer profile in Talon.One.
loyaltyProgramId required	integer <int64> Example: loyaltyProgramId=25 The ID of the loyalty program in Talon.One.
projectionEndDate required	string <date-time> Example: projectionEndDate=2022-10-30T15:35:02Z The end date to query the projected loyalty balances. You can project results up to 31 days from today.

Responses

Response samples

200
400
401
404

Content type

application/json

{"id": 302,
"title": "My loyalty program",
"name": "myloyaltyprogram",
"ledger": {"currentBalance": 10.5,
"pendingBalance": 5.1,
"expiredBalance": 2,
"spentBalance": 0,
"tentativeCurrentBalance": 0,
"pointsToNextTier": 10,
"currentTier": {"id": 112345,
"name": "silver-tier"
},
"projection": {"totalExpiringPoints": 4,
"totalActivatingPoints": 4.2,
"projections": [{"date": "2021-11-11T00:00:00Z",
"expiringPoints": 2.7,
"activatingPoints": 2.9,
"projectedBalance": 200
}
]
}
},
"subLedgers": {"property1": {"currentBalance": 10.5,
"pendingBalance": 5.1,
"expiredBalance": 2,
"spentBalance": 0,
"tentativeCurrentBalance": 0,
"pointsToNextTier": 10,
"currentTier": {"id": 112345,
"name": "silver-tier"
},
"projection": {"totalExpiringPoints": 4,
"totalActivatingPoints": 4.2,
"projections": [{"date": "2021-11-11T00:00:00Z",
"expiringPoints": 2.7,
"activatingPoints": 2.9,
"projectedBalance": 200
}
]
}
},
"property2": {"currentBalance": 10.5,
"pendingBalance": 5.1,
"expiredBalance": 2,
"spentBalance": 0,
"tentativeCurrentBalance": 0,
"pointsToNextTier": 10,
"currentTier": {"id": 112345,
"name": "silver-tier"
},
"projection": {"totalExpiringPoints": 4,
"totalActivatingPoints": 4.2,
"projections": [{"date": "2021-11-11T00:00:00Z",
"expiringPoints": 2.7,
"activatingPoints": 2.9,
"projectedBalance": 200
}
]
}
}
}
}

Segment

Segment is a customer data platform that collects events from your web & mobile apps.

Use these endpoints to integrate with Talon.One.

Update customer profile

Update the given customer profile to add or remove audiences.

Authorizations:

ApiKeyAuth

path Parameters

customerProfileId

required

string

The integration ID of the customer profile.

header Parameters

destination-hostname

required

string <hostname>

Example: https://mycompany.europe-west1.talon.one/

The base URL of your Talon.One deployment.

Request Body schema: application/json

	object Arbitrary properties associated with this entity
runRuleEngine	boolean Default: false Indicates whether to run the rule engine. Setting this property to `false` improves response times. For audiences changes the runRuleEngine should be true. Default value is `false`.
	object
	Array of objects[ items ] Use this field if you want to specify type of an attribute.

Responses

Request samples

Payload

Content type

application/json

{"runRuleEngine": false,
"audiencesChanges": {"adds": [1,
2,
3
],
"deletes": [4,
5,
6
]
},
"attributes": {"Language": "english",
"ShippingCountry": "DE",
"ProductClicked": true
},
"attributesInfo": [{"name": "ProductClicked",
"type": "boolean"
}
]
}

Response samples

200
400
401
404
429

Content type

application/json

{"customerProfile": {"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"accountId": 6,
"attributes": {"Language": "english",
"ShippingCountry": "DE"
},
"integrationId": "URNGV8294NV",
"closedSessions": 3,
"totalSales": 299.99,
"audienceMemberships": [{"id": 6,
"name": "audience1"
}
],
"lastActivity": "2020-02-08T14:15:20Z"
},
"createdAttributes": [{"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"accountId": 6,
"entity": "CustomerProfile",
"eventType": "string",
"name": "country",
"title": "Country",
"type": "string",
"description": "a description",
"suggestions": ["suggestion1",
"suggestion2"
],
"hasAllowedList": false,
"restrictedBySuggestions": false,
"editable": true,
"subscribedApplicationsIds": [10,
20,
100
],
"eventTypeId": 22
}
]
}

Update audiences in multiple customer profiles

Update

Authorizations:

ApiKeyAuth

header Parameters

destination-hostname

required

string <hostname>

Example: https://mycompany.europe-west1.talon.one/

The base URL of your Talon.One deployment.

Request Body schema: application/json

Array of objects[ items ]

Indicates audience changes for a selected profile

Array

adds	Array of integers <int64> [ items <int64 > >= 1 ] The IDs of the audiences for the customer to join.
deletes	Array of integers <int64> [ items <int64 > >= 1 ] The IDs of the audiences for the customer to leave.
customerProfileId	string <string> <= 1000 characters Unique Customer Profile ID.

Responses

Request samples

Payload

Content type

application/json

{"data": [{"adds": [1,
2,
3
],
"deletes": [4,
5,
6
],
"customerProfileId": "URN-GV8294NV"
}
]
}

Response samples

400
401
404
429

Content type

application/json

{"StatusCode": 400,
"Error": "No Deployment URL specified",
"RequestUUID": "fd2f7c55-d064-46e1-ab87-a39cb877cd82"
}

Update attributes in multiple customer profiles

Update the given attributes in a set of customer profiles.

Authorizations:

ApiKeyAuth

header Parameters

destination-hostname

required

string <hostname>

Example: https://mycompany.europe-west1.talon.one/

The base URL of your Talon.One deployment.

Request Body schema: application/json

	Array of objects[ items ] Indicates attribute values for a selected profile.
	Array of objects[ items ] Indicates attribute values for all the profile in the request.
	Array of objects[ items ] Use this field if you want to specify type of an attribute.

Responses

Request samples

Payload

Content type

application/json

{"data": [{"customerProfileId": "URN-GV8294NV",
"attributes": {"Language": "english",
"ShippingCountry": "DE"
}
}
],
"mutualAttributes": [{"Language": "english",
"ShippingCountry": "DE"
}
],
"attributesInfo": [{"name": "ProductClicked",
"type": "boolean"
}
]
}

Response samples

200
400
401
404
429

Content type

application/json

{"states": [{"customerProfile": {"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"accountId": 6,
"attributes": {"Language": "english",
"ShippingCountry": "DE"
},
"integrationId": "URNGV8294NV",
"closedSessions": 3,
"totalSales": 299.99,
"audienceMemberships": [{"id": 6,
"name": "audience1"
}
],
"lastActivity": "2020-02-08T14:15:20Z"
}
}
],
"createdAttributes": [{"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"accountId": 6,
"entity": "CustomerProfile",
"eventType": "string",
"name": "country",
"title": "Country",
"type": "string",
"description": "a description",
"suggestions": ["suggestion1",
"suggestion2"
],
"hasAllowedList": false,
"restrictedBySuggestions": false,
"editable": true,
"subscribedApplicationsIds": [10,
20,
100
],
"eventTypeId": 22
}
]
}

Track event

Triggers a custom event. You can then check this event in your rules. Important: Talon.One offers a set of built-in events, ensure you do not create a custom event when you can use a built-in event.

For example, use this endpoint to trigger an event when a user updates their payment information.

If the specified session already exists, it must belong to the same profileId or an error will be returned.

Authorizations:

ApiKeyAuth

header Parameters

destination-hostname

required

string <hostname>

Example: https://mycompany.europe-west1.talon.one/

The base URL of your Talon.One deployment.

Request Body schema: application/json

eventType required	string <string> The event type, as defined in Talon.One when you created the custom attribute representing this event.
type required	string <string> Enum: "string" "time" "number" "boolean" "location" The data type of the event, as defined in Talon.One when you created the custom attribute representing this event.
customerProfileId required	string <string> <= 1000 characters Unique Customer Profile ID.
	object Arbitrary properties associated with this entity
	Array of objects[ items ] Use this field if you want to specify type of an attribute.

Responses

Request samples

Payload

Content type

application/json

{"customerProfileId": "URN-GV8294NV",
"eventType": "mySegmentEvent",
"type": "string",
"eventAttributes": {"Language": "english",
"ShippingCountry": "DE",
"ProductClicked": true
},
"attributesInfo": [{"name": "ProductClicked",
"type": "boolean"
}
]
}

Response samples

200
400
401
404
429

Content type

application/json

{"customerProfile": {"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"accountId": 6,
"attributes": {"Language": "english",
"ShippingCountry": "DE"
},
"integrationId": "URNGV8294NV",
"closedSessions": 3,
"totalSales": 299.99,
"audienceMemberships": [{"id": 6,
"name": "audience1"
}
],
"lastActivity": "2020-02-08T14:15:20Z"
},
"event": {"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"applicationId": 322,
"profileId": "string",
"type": "pageViews",
"attributes": {"Language": "english",
"ShippingCountry": "DE"
},
"sessionId": "175KJPS947296",
"effects": [[4208,
20095,
0,
["showNotification",
"Info",
"My title",
"My content"
]
]
],
"ledgerEntries": [{"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"profileId": "string",
"accountId": 0,
"loyaltyProgramId": 323414846,
"eventId": 0,
"amount": 100,
"reason": "string",
"expiryDate": "2019-08-24T14:15:22Z",
"referenceId": 0
}
],
"meta": {"campaigns": { },
"coupons": { },
"couponRejectionReason": {"campaignId": 244,
"couponId": 4928,
"reason": "CouponNotFound"
},
"referralRejectionReason": {"campaignId": 0,
"referralId": 0,
"reason": "ReferralNotFound"
},
"warnings": { }
}
}
}

Create audience

Create an audience. The audience can be created directly from scratch or can come from Segment.

Once you create your first audience, audience-specific rule conditions are enabled in the Rule Builder

Authorizations:

ApiKeyAuth

header Parameters

destination-hostname

required

string <hostname>

Example: https://mycompany.europe-west1.talon.one/

The base URL of your Talon.One deployment.

Request Body schema: application/json

audienceId required	string <string> [ 1 .. 1000 ] characters The ID of this audience. If the audience comes from a third-party platform, set this property to the ID given by the third-party platform.
audienceName required	string <string> [ 1 .. 1000 ] characters The human-friendly display name for this audience.

Responses

Request samples

Payload

Content type

application/json

{"audienceId": "382370BKDB946",
"audienceName": "Travel audience"
}

Response samples

Content type

application/json

{"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"accountId": 6,
"name": "Travel audience",
"integration": "My platform name",
"integrationId": "382370BKDB946"
}

Delete audience

Delete the audience.

Warning: This endpoint also removes any associations recorded between a customer profile and this audience.

Authorizations:

ApiKeyAuth

path Parameters

audienceId

required

integer <int64>

Example: 4729630

The ID of the audience.

header Parameters

destination-hostname

required

string <hostname>

Example: https://mycompany.europe-west1.talon.one/

The base URL of your Talon.One deployment.

Responses

Response samples

400
401
404
429

Content type

application/json

{"StatusCode": 400,
"Error": "No Deployment URL specified",
"RequestUUID": "fd2f7c55-d064-46e1-ab87-a39cb877cd82"
}

Update audience

Update an audience.

Authorizations:

ApiKeyAuth

path Parameters

audienceId

required

integer <int64>

Example: 4729630

The ID of the audience.

header Parameters

destination-hostname

required

string <hostname>

Example: https://mycompany.europe-west1.talon.one/

The base URL of your Talon.One deployment.

Request Body schema: application/json

audienceId required	string <string> [ 1 .. 1000 ] characters The ID of this audience. If the audience comes from a third-party platform, set this property to the ID given by the third-party platform.
audienceName required	string <string> [ 1 .. 1000 ] characters The human-friendly display name for this audience.

Responses

Request samples

Payload

Content type

application/json

{"audienceId": "382370BKDB946",
"audienceName": "Travel audience"
}

Response samples

200
400
401
404
429

Content type

application/json

{"id": 6,
"created": "2020-06-10T09:05:27.993483Z",
"accountId": 6,
"name": "Travel audience",
"integration": "My platform name",
"integrationId": "382370BKDB946"
}

Selligent

Selligent Marketing Cloud is an AI-powered marketing automation platform that helps you make marketing personal, by activating your data to deliver unique, highly relevant experiences to your customers at every moment of interaction, across all channels and devices. For more information, see the developer docs.

Create coupon

Create a coupon code in Talon.One. To use it in your Selligent deployment, see the tutorial.

Authorizations:

ApiKeyAuth

query Parameters

deployment required	string Example: deployment=company.talon.one The base URL of your deployment.
campaignId required	integer <int64> Example: campaignId=5843 The ID of the campaign in Talon.One.
applicationId required	integer <int64> Example: applicationId=316 The ID of the Application in Talon.One.
selligentCampaignId required	string Example: selligentCampaignId=someCampaignId Selligent campaign id
recipientIntegrationId	string Example: recipientIntegrationId=URN-GV8294NV The integration ID of the only customer that can use the generated coupon code. Leave blank to allow any user to use the coupon.
discountLimit	integer <int64> Example: discountLimit=155 The 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.
startDate	string <date-time> Example: startDate=2022-09-30T15:35:02Z The date when the code becomes usable.
expiryDate	string <date-time> Example: expiryDate=2022-10-30T15:35:02Z The date when the code becomes unusable.
usageLimit	integer <int64> Default: 1 Example: usageLimit=1 The number of times the coupon code can be redeemed. 0 means unlimited redemptions but any campaign usage limits will still apply. The default value is 1.

Responses

Response samples

200
401
429

Content type

application/json

Example

success response

{"ID": 20190408,
"ApplicationID": 398,
"CampaignID": 5671,
"Value": "EW-1BC2",
"StartDate": "2021-09-30T15:35:02.371569+02:00",
"ExpiryDate": "2024-10-03T15:35:02.371569+02:00",
"RecipientIntegrationID": "URN-GV8294NV",
"UsageLimit": 1,
"UsageCounter": 0,
"Attributes": {"email": "user@mailbox.com",
"country": "DE"
}
}

mParticle

mParticle is the customer data platform that helps unify data and simplify partner integrations with enterprise-class security and reliability.

For more information, see our integration examples in the developer docs.

Send event

Send an mParticle event to Talon.One.

This endpoint supports the following mParticle events:

module_registration_request: A new client signs up for Talon.One in mParticle.
audience_subscription_request: A client adds/deletes/edits an audience in mParticle.
event_processing_request: Talon.One should process events that have been triggered in mParticle.
audience_membership_change_request: Customers are added to/removed from an audience in mParticle.

Request Body schema: application/json

One of

type required	string Enum: "module_registration_request" "audience_subscription_request" "event_processing_request" "audience_membership_change_request" The type of request/event coming from mParticle.
id	string The ID that is set by mParticle to identify this request.
timestamp_ms	integer Timestamp of the request (in milliseconds)
firehose_version	string mParticle's internal API version.
	object

Responses

Request samples

Payload

Content type

application/json

Example

moduleRegistrationRequest

{"type": "module_registration_request",
"id": "deadb33f-dead-b33f-b33f-deadbeef0000",
"timestamp_ms": 1586980879793,
"firehose_version": "2.4.0",
"account": {"account_id": 1234567,
"account_settings": {"apiKey": "someapikey",
"deploymentURL": "https://mycompany.europe-west1.talon.one/",
"userIdField": "email"
}
}
}

Response samples

200
400
401
409
429

Content type

application/json

Example

moduleRegistrationResponse

{"type": "module_registration_response",
"id": "deadb33f-dead-b33f-b33f-deadbeef0000",
"timestamp_ms": 1586980879793,
"firehose_version": "2.4.0",
"name": "Talon.One",
"description": "<a href='https://talon.one'>Talon.One</a> is the world's most flexible Promotion Engine. Create, manage and track coupon codes, discount campaigns, loyalty programs and referrals in one system.",
"version": "0.0.1",
"permissions": {"allow_consent_state": true,
"allow_access_mpid": true,
"allow_user_attributes": true,
"allow_audience_user_attributes": true,
"user_identities": [{"type": "email",
"encoding": "raw",
"required": false,
"value": ""
},
{"type": "customer",
"encoding": "raw",
"required": false,
"value": ""
}
]
},
"audience_processing_registration": {"account_settings": [{"type": "text",
"id": "deploymentURL",
"name": "Deployment URL",
"description": "URL of your Talon.One deployment",
"visible": true,
"required": true,
"confidential": true,
"default_value": ""
},
{"type": "text",
"id": "apiKey",
"name": "API Key",
"description": "API Key to be used for requests to your Talon.One deployment",
"visible": true,
"required": true,
"confidential": true,
"default_value": ""
},
{"type": "text",
"id": "userIdField",
"name": "User ID",
"description": "Select which user identity to forward to Talon.One as your customer's user ID.",
"visible": true,
"required": true,
"confidential": true,
"default_value": "customerId"
},
{"type": "boolean",
"id": "runRuleEngine",
"name": "Run Rule Engine",
"description": "Dictates whether the Rule Engine should be run after each membership change.",
"visible": true,
"required": true,
"confidential": false,
"default_value": false
}
],
"audience_subscription_settings": [{"type": "integer",
"id": "t1AudienceID",
"name": "Talon.One Audience ID",
"visible": false,
"required": false
}
]
},
"event_processing_registration": {"account_settings": [{"type": "text",
"id": "deploymentURL",
"name": "Deployment URL",
"description": "URL of your Talon.One deployment",
"visible": true,
"required": true,
"confidential": true,
"default_value": ""
},
{"type": "text",
"id": "apiKey",
"name": "API Key",
"description": "API Key to be used for requests to your Talon.One deployment",
"visible": true,
"required": true,
"confidential": true,
"default_value": ""
},
{"type": "text",
"id": "userIdField",
"name": "User ID",
"description": "Select which user identity to forward to Talon.One as your customer's user ID.",
"visible": true,
"required": true,
"confidential": true,
"default_value": "customerId"
},
{"type": "boolean",
"id": "runRuleEngine",
"name": "Run Rule Engine",
"description": "Dictates whether the Rule Engine should be run after each membership change.",
"visible": true,
"required": true,
"confidential": false,
"default_value": false
}
],
"supported_event_types": ["custom_event"
],
"supported_runtime_environments": ["unknown",
"android",
"ios",
"tvos",
"mobileweb",
"roku",
"xbox",
"firetv",
"alexa",
"smarttv"
],
"supported_system_notification_types": [ ],
"max_data_age_hours": -1
}
}