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.
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 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:
header Parameters
X-DRY-RUN | boolean Example: true Indicates whether to persist the changes. Changes are ignored when |
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
{- "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
{- "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:
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:
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 |
attributes | object Arbitrary properties associated with item. |
Responses
Request samples
- Payload
{- "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
{- "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:
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 See dispatch ID behavior. |
object Arbitrary properties associated with this entity |
Responses
Request samples
- Payload
{- "eventType": "myBrazeEvent",
- "type": "string",
- "eventAttributes": {
- "Language": "english",
- "ShippingCountry": "DE"
}, - "customerProfileId": "URN-GV8294NV",
- "identifier": "NNjETb6XxDV7hQhLMA"
}
Response samples
- 200
- 400
- 401
- 404
- 429
{- "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": { }
}
}
}
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:
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 |
object |
Responses
Request samples
- Payload
{- "attributes": {
- "Language": "english",
- "ShippingCountry": "DE"
}, - "runRuleEngine": false,
- "audiencesChanges": {
- "adds": [
- 1,
- 2,
- 3
], - "deletes": [
- 4,
- 5,
- 6
]
}
}
Response samples
- 200
- 400
- 401
- 404
- 429
{- "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:
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
{- "audienceId": "382370BKDB946",
- "audienceName": "Travel audience"
}
Response samples
- 201
- 400
- 401
- 404
- 409
- 429
{- "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:
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
{- "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:
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
{- "audienceId": "382370BKDB946",
- "audienceName": "Travel audience"
}
Response samples
- 200
- 400
- 401
- 404
- 429
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 6,
- "name": "Travel audience",
- "integration": "My platform name",
- "integrationId": "382370BKDB946"
}
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:
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 |
Responses
Response samples
- 200
- 400
- 401
- 404
- 429
{- "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:
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 |
Responses
Response samples
- 200
- 400
- 401
- 404
- 429
{- "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:
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
{- "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 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:
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
{- "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:
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
{- "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:
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
{- "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 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:
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 |
object | |
Array of objects[ items ] Use this field if you want to specify type of an attribute. |
Responses
Request samples
- Payload
{- "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
{- "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:
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
|
Responses
Request samples
- Payload
{- "data": [
- {
- "adds": [
- 1,
- 2,
- 3
], - "deletes": [
- 4,
- 5,
- 6
], - "customerProfileId": "URN-GV8294NV"
}
]
}
Response samples
- 400
- 401
- 404
- 429
{- "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:
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
{- "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
{- "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:
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
{- "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
{- "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:
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
{- "audienceId": "382370BKDB946",
- "audienceName": "Travel audience"
}
Response samples
- 201
- 400
- 401
- 404
- 409
- 429
{- "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:
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
{- "StatusCode": 400,
- "Error": "No Deployment URL specified",
- "RequestUUID": "fd2f7c55-d064-46e1-ab87-a39cb877cd82"
}
Update audience
Update an audience.
Authorizations:
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
{- "audienceId": "382370BKDB946",
- "audienceName": "Travel audience"
}
Response samples
- 200
- 400
- 401
- 404
- 429
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 6,
- "name": "Travel audience",
- "integration": "My platform name",
- "integrationId": "382370BKDB946"
}
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:
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
{- "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 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
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
{- "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",
- "userIdField": "email"
}
}
}
Response samples
- 200
- 400
- 401
- 409
- 429
{- "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
}
}