Skip to main content
API docs by Redocly

Third-party API reference docs

Download OpenAPI specification:Download

Use the Third-party API to exchange data between Talon.One and one of the supported 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.

All endpoints of this API start with https://integration.talon.one.

You must specify the base URL of your deployment in the headers or parameters.

Looking for a different API?

Depending on the use case, you can choose from the following APIs:

Authentication

ApiKeyAuth

To authenticate to use these endpoints, create a Third-party API key in the Campaign Manager:

  1. Sign in to the Campaign Manager, and open the Application of your choice.
  2. Click Settings > Integration API Keys.
  3. Click Create API Key.
  4. In the Create API Key drawer, if you are asked for a key type, select Production.
  5. In Key name, type a name to identify the key.
  6. In Key expiration date, select a date.
  7. In Third-party integration, select Yes and the platform to integrate with.
  8. Click Create API Key, and copy the generated value for use.

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

ApiKeyBasicAuth

To authenticate to use these endpoints, create a Third-party API key in the Campaign Manager:

  1. Sign in to the Campaign Manager, and open the Application of your choice.
  2. Click Settings > Integration API Keys.
  3. Click Create API Key.
  4. In the Create API Key drawer, if you are asked for a key type, select Production.
  5. In Key name, type a name to identify the key.
  6. In Key expiration date, select a date.
  7. In Third-party integration, select Yes and the platform to integrate with.
  8. Click Create API Key, and copy the generated value for use.
  9. Modify the generated value by prefixing it with ApiKey-v1 and suffixing it with :. For example: ApiKey-v1 <generated-api-key>:.
  10. Encode this modified value to Base64.

You can now use the API key, prefixing the Base64-encoded string with Authorization: Basic :

Authorization: Basic YmFzZTY0ZW5vZGV0aGlzcGxlYXNlYXNhcDQzMjE0MTI=
Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

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 X-DRY-RUN=true.

Request Body schema: application/json
deploymentUrl
required
string

The base url of your deployment.

campaignId
required
integer <int64> >= 1

The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.

advocateProfileIntegrationId
required
string non-empty

The customer integration ID of the advocate.

friendProfileIntegrationId
string non-empty

The customer integration ID of the person being referred.

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

An object containing the value of each attributes to set.

New attributes are created automatically. For more information, see Attributes.

Responses

Request samples

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": {
    }
}

Response samples

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": {
    },
  • "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.

Tip: You can edit the default coupon code format in the campaign's settings.

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. It is displayed in your Talon.One deployment URL.

campaignId
required
integer <int64> >= 1

The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.

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 and does not create a new coupon.

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.

discountLimit
number [ 0 .. 999999 ]

The discount amount the coupon is worth. Can be blank if, for example, the coupon provides a 10% discount, or something other than a fixed value of discounts.

reservationLimit
integer <int64> [ 0 .. 999999 ]

The number of reservations that can be made with this coupon code.

isReservationMandatory
boolean

Indicates whether the code can be redeemed only if it has been reserved first.

Array of objects

Limits configuration for a coupon. These limits will override the limits set from the campaign.

Note: Only usable when creating a single coupon which is not tied to a specific recipient. Only per-profile limits are allowed to be configured.

Array
action
required
string

The limitable action to which this limit applies. Must be set to redeemCoupon.

limit
required
number >= 0

The number of times a coupon can be redeemed per customer.

entities
required
Array of strings
Items Enum: "Coupon" "Profile"

The entities that this limit applies to. Must be set to ["Coupon", "Profile"].

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

Content type
application/json
{
  • "deploymentUrl": "mycompany.europe-west1.talon.one",
  • "applicationId": 398,
  • "campaignId": 5671,
  • "identifier": "test-coupon",
  • "usageLimit": 4,
  • "discountLimit": 30,
  • "reservationLimit": 45,
  • "integrationId": "URN-GV8294NV",
  • "startDate": "2021-09-30T15:35:02.371569+02:00",
  • "expiryDate": "2024-10-03T15:35:02.371569+02:00",
  • "validCharacters": [
    ],
  • "couponPattern": "ew-####",
  • "isReservationMandatory": false,
  • "limits": [
    ],
  • "attributes": {
    }
}

Response samples

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,
  • "IsReservationMandatory": false,
  • "Limits": [
    ],
  • "Attributes": {
    }
}

Create coupon reservation

Create a coupon reservation for a specified customer profile on the specified coupon.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
deploymentUrl
required
string

The base url of your deployment.

couponValue
required
string

The coupon code.

integrationId
required
string

The integration ID of the customer profile.

Responses

Request samples

Content type
application/json
{
  • "deploymentUrl": "mycompany.europe-west1.talon.one",
  • "couponValue": "EW-1BC2",
  • "integrationId": "URN-GV8294NV"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "campaignId": 1,
  • "created": "2022-03-02T16:46:17.758585Z",
  • "value": "EW-1BC2",
  • "usageCounter": 0,
  • "usageLimit": 1
}

Track event

Triggers a custom event inside Talon.One. You can then trigger rules when this event is received.

An event is a type of custom attribute. You must create it first in the Campaign Manager. See creating custom events. To see the events received by your Application in Talon.One, open the Application and click Events.

For more information, see the tutorial.

Authorizations:
ApiKeyAuth
header Parameters
destination-hostname
required
string <hostname>
Example: 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" "(list string)" "(list number)" "(list time)" "(list 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

The integration ID of the customer profile. If the customer profile does not exist, it will be created.

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

Property to set the attributes of your choice to the values of your choice.

You can use built-in attributes or custom ones.

Custom attributes must be created in the Campaign Manager before you set them with this property.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "eventType": "myBrazeEvent",
  • "type": "string",
  • "eventAttributes": {
    },
  • "customerProfileId": "URN-GV8294NV",
  • "identifier": "NNjETb6XxDV7hQhLMA"
}

Response samples

Content type
application/json
{
  • "customerSession": {
    },
  • "customerProfile": {
    },
  • "event": {
    },
  • "loyalty": {
    },
  • "referral": {
    },
  • "coupons": [
    ],
  • "triggeredCampaigns": [
    ],
  • "effects": [
    ],
  • "ruleFailureReasons": [
    ],
  • "createdCoupons": [
    ],
  • "createdReferrals": [
    ],
  • "awardedGiveaways": [
    ],
  • "return": {
    },
  • "previousReturns": [
    ]
}

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 or create a customer profile. This endpoint triggers the Rule Builder.

You can use this endpoint for the following tasks:

  • Set attributes for the given customer profile. Ensure you create the attributes in the Campaign Manager first.
  • Add the customer profile to audiences or remove it from audiences.
Authorizations:
ApiKeyAuth
path Parameters
customerProfileId
required
string
Example: customer1

The integration ID of the customer profile. If the customer profile does not exist, it will be created.

query Parameters
skipNonExistingAttributes
boolean
Default: false
Example: skipNonExistingAttributes=true

Indicates whether to skip non-existing attributes.

If true, the non-existing attributes are skipped and a 400 error is not returned.

If false, a 400 error is returned in case of non-existing attributes.

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: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

Request Body schema: application/json
object

Property to set the attributes of your choice to the values of your choice.

Note: If set to null, the attribute is deleted from the customer profile.

property name*
additional property
any
runRuleEngine
boolean
Default: false

Indicates whether to run the Rule Engine.

If true, the rules are run and their effects are applied.

If false:

  • The rules are not executed.
  • The response time improves.

Note: If the audiencesChanges request parameter is not empty, this value is automatically set to true.

object

A list of audiences where the customer should be removed or added.

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.

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    },
  • "runRuleEngine": false,
  • "audiencesChanges": {
    }
}

Response samples

Content type
application/json
{
  • "customerSession": {
    },
  • "customerProfile": {
    },
  • "event": {
    },
  • "loyalty": {
    },
  • "referral": {
    },
  • "coupons": [
    ],
  • "triggeredCampaigns": [
    ],
  • "effects": [
    ],
  • "ruleFailureReasons": [
    ],
  • "createdCoupons": [
    ],
  • "createdReferrals": [
    ],
  • "awardedGiveaways": [
    ],
  • "return": {
    },
  • "previousReturns": [
    ]
}

Update audiences in multiple customer profiles

Update the specified audiences for the specified profiles.

If a provided customer profile doesn't exist, it will be created.

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: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

Request Body schema: application/json
Array of objects

Indicates audience changes for a selected profile.

Note: The total number of adds and deletes items should be equal to or less than 1000.

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

The integration ID of the customer profile. If the customer profile does not exist, it will be created.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "StatusCode": 400,
  • "Error": "No Deployment URL specified",
  • "RequestUUID": "fd2f7c55-d064-46e1-ab87-a39cb877cd82"
}

Update audiences in multiple customer profiles (external ID)

Update the specified audiences for the specified profiles. To identify the audience, you can use its ID in the third-party integration.

If a provided customer profile doesn't exist, it will be created.

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: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

Request Body schema: application/json
Array of objects

Indicates audience changes for a selected profile.

Note: The total number of adds and deletes items should be equal to or less than 1000.

Array
adds
Array of strings[ items non-empty ]

The external IDs of the audiences for the customer to join.

deletes
Array of strings[ items non-empty ]

The external IDs of the audiences for the customer to leave.

customerProfileId
string <string> <= 1000 characters

The integration ID of the customer profile. If the customer profile does not exist, it will be created.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "StatusCode": 400,
  • "Error": "No Deployment URL specified",
  • "RequestUUID": "fd2f7c55-d064-46e1-ab87-a39cb877cd82"
}

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: 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 integration 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

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"
}

Update audience

Update an audience created by a third-party integration.

Authorizations:
ApiKeyAuth
path Parameters
audienceId
required
string
Example: audience1

The integration 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: 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 integration 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

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
string
Example: audience1

The integration 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: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

Responses

Response samples

Content type
application/json
{
  • "StatusCode": 400,
  • "Error": "No Deployment URL specified",
  • "RequestUUID": "fd2f7c55-d064-46e1-ab87-a39cb877cd82"
}

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.

Tip: You can edit the default coupon code format in the campaign's settings.

Authorizations:
ApiKeyAuth
query Parameters
applicationId
required
integer <int64>
Example: applicationId=316

The ID of the Application in Talon.One. It is displayed in your Talon.One deployment URL.

campaignId
required
integer <int64>
Example: campaignId=5843

The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.

externalCampaignId
required
string
Example: externalCampaignId=testCampaignId

The ID of the campaign in the third-party platform.

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 fixed 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: .firstName=john&.country=DE

Optional parameter to set the value of custom attributes. They are defined in the Campaign Manager, see Managing attributes.

Prefix each attribute name with . or _.

Certain attributes can also be set to mandatory in your Application settings. If your Application uses mandatory attributes, you must use this parameter to set their value.

The type of the value must match the type of the attribute. If you provide an integer value, the attribute must also be of type Integer in Talon.One.

If the types do not match, and the attribute in Talon.One is of type String, put the value in quotes. For example, if you provide a Boolean value for a String attribute, use "true" and "false".

Full URI example: https://<url>?applicationId=5&.myIntegerAttribute=1234&.myStringAttribute1=Text&.myStringAttribute2="1234"&.myStringAttribute3="true".

identifier
string
Example: identifier=3495-4323

The identifier of the request. Providing a new value creates a new coupon. Providing an existing value retrieves the existing coupon of that ID and does not create a new coupon.

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: 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 X-DRY-RUN=true.

Responses

Response samples

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,
  • "Attributes": {
    }
}

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. It is displayed in your Talon.One deployment URL.

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: .firstName=john&.country=DE

Optional parameter to set the value of custom attributes. They are defined in the Campaign Manager, see Managing attributes.

Prefix each attribute name with . or _.

Certain attributes can also be set to mandatory in your Application settings. If your Application uses mandatory attributes, you must use this parameter to set their value.

The type of the value must match the type of the attribute. If you provide an integer value, the attribute must also be of type Integer in Talon.One.

If the types do not match, and the attribute in Talon.One is of type String, put the value in quotes. For example, if you provide a Boolean value for a String attribute, use "true" and "false".

Full URI example: https://<url>?applicationId=5&.myIntegerAttribute=1234&.myStringAttribute1=Text&.myStringAttribute2="1234"&.myStringAttribute3="true".

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: 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 X-DRY-RUN=true.

Responses

Response samples

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": {
    },
  • "code": "P8BN-4T5V",
  • "usageCounter": 0
}

Get loyalty ledger

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

This endpoint only works with profile-based loyalty programs.

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 profile-based loyalty program in Talon.One.

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: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

Responses

Response samples

Content type
application/json
{
  • "id": 302,
  • "title": "My loyalty program",
  • "name": "myloyaltyprogram",
  • "ledger": {
    },
  • "subLedgers": {
    }
}

Add loyalty points

Add points in the specified loyalty program for the given customer.

This endpoint only works with profile-based loyalty programs.

Authorizations:
ApiKeyAuth
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: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

Request Body schema: application/json
loyaltyProgramId
required
integer

The ID of the profile-based loyalty program in Talon.One.

profileIntegrationId
required
string

The integration ID of the customer profile in Talon.One.

points
required
number ( 0 .. 999999999999.99 ]

Amount of loyalty points.

name
string

Name / reason for the point addition.

validityDuration
string

The time format is either:

  • immediate or,
  • an integer followed by one letter indicating the time unit.

Examples: immediate, 30s, 40m, 1h, 5D, 7W, 10M, 15Y.

Available units:

  • s: seconds
  • m: minutes
  • h: hours
  • D: days
  • W: weeks
  • M: months
  • Y: years

You can round certain units up or down:

  • _D for rounding down days only. Signifies the start of the day.
  • _U for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year.

If passed, validUntil should be omitted.

validUntil
string <date-time>

Date and time when points should expire. The value should be provided in RFC 3339 format. If passed, validityDuration should be omitted.

pendingDuration
string

The amount of time before the points are considered valid.

The time format is either:

  • immediate or,
  • an integer followed by one letter indicating the time unit.

Examples: immediate, 30s, 40m, 1h, 5D, 7W, 10M, 15Y.

Available units:

  • s: seconds
  • m: minutes
  • h: hours
  • D: days
  • W: weeks
  • M: months
  • Y: years

You can round certain units up or down:

  • _D for rounding down days only. Signifies the start of the day.
  • _U for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year.
pendingUntil
string <date-time>

Date and time after the points are considered valid. The value should be provided in RFC 3339 format. If passed, pendingDuration should be omitted.

subledgerId
string

ID of the subledger the points are added to. If there is no existing subledger with this ID, the subledger is created automatically.

applicationId
integer

ID of the Application that is connected to the loyalty program. It is displayed in your Talon.One deployment URL.

Responses

Request samples

Content type
application/json
{
  • "profileIntegrationId": "URN-GV8294NV",
  • "loyaltyProgramId": 25,
  • "points": 300,
  • "name": "Compensation",
  • "validityDuration": "5D",
  • "validUntil": "2021-07-20T22:00:00Z",
  • "pendingDuration": "12h",
  • "pendingUntil": "2021-07-20T22:00:00Z",
  • "subledgerId": "sub-123",
  • "applicationId": 322
}

Response samples

Content type
application/json
{
  • "StatusCode": 400,
  • "Error": "No Deployment URL specified",
  • "RequestUUID": "fd2f7c55-d064-46e1-ab87-a39cb877cd82"
}

Emarsys

Emarsys is a customer engagement platform that enables marketers to build, launch, and scale personalized cross-channel promotional campaigns that have measurable impact.

Use these endpoints to integrate with Talon.One.

Get coupon

Retrieve a coupon code from Talon.One.

Authorizations:
ApiKeyBasicAuth
query Parameters
deployment
required
string
Example: deployment=company.talon.one

The base URL of your Talon.One deployment.

Request Body schema: application/json
required
fields
required
Array of strings

Any additional data we want in the response.

Note: For the supported fields, see the List customer data response (any nested arrays and objects are discarded from the response). In addition to this, custom attributes are supported.

limit
required
number >= 0

The value to set for the limit.

required
Array of objects
Array
campaignId
string

The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.

integrationId
string

The integration ID of the customer profile.

Responses

Request samples

Content type
application/json
{
  • "parameters": [
    ],
  • "fields": [
    ],
  • "limit": 1000
}

Response samples

Content type
application/json
{
  • "content": [
    ]
}

Get loyalty balance

Retrieve the loyalty balance of a customer profile from Talon.One.

This endpoint only works with profile-based loyalty programs.

Authorizations:
ApiKeyBasicAuth
query Parameters
deployment
required
string
Example: deployment=company.talon.one

The base URL of your Talon.One deployment.

Request Body schema: application/json
required
fields
required
Array of strings

Additional fields to include in the response. Valid fields are activeBalance, pendingBalance, expiredBalance, and spentBalance.

required
Array of objects
Array
loyaltyProgramId
required
string

The ID of the loyalty program in Talon.One.

integrationId
required
string

The integration ID of the customer profile.

subledgerId
string

The ID of the subledger from which to retrieve the loyalty balance. If not provided, the loyalty balance is retrieved from the main ledger.

Responses

Request samples

Content type
application/json
{
  • "parameters": [
    ],
  • "fields": [
    ]
}

Response samples

Content type
application/json
{
  • "content": [
    ]
}

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.

Tip: You can edit the default coupon code format in the campaign's settings.

Authorizations:
ApiKeyAuth
query Parameters
deployment
required
string
Example: deployment=company.talon.one

The base URL of your Talon.One deployment.

applicationId
required
integer <int64>
Example: applicationId=316

The ID of the Application in Talon.One. It is displayed in your Talon.One deployment URL.

campaignId
required
integer <int64>
Example: campaignId=5843

The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.

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 fixed 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: .firstName=john&.country=DE

Optional parameter to set the value of custom attributes. They are defined in the Campaign Manager, see Managing attributes.

Prefix each attribute name with . or _.

Certain attributes can also be set to mandatory in your Application settings. If your Application uses mandatory attributes, you must use this parameter to set their value.

The type of the value must match the type of the attribute. If you provide an integer value, the attribute must also be of type Integer in Talon.One.

If the types do not match, and the attribute in Talon.One is of type String, put the value in quotes. For example, if you provide a Boolean value for a String attribute, use "true" and "false".

Full URI example: https://<url>?applicationId=5&.myIntegerAttribute=1234&.myStringAttribute1=Text&.myStringAttribute2="1234"&.myStringAttribute3="true".

Responses

Response samples

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,
  • "Attributes": {
    }
}

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 Talon.One deployment.

campaignId
required
integer <int64>
Example: campaignId=5843

The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.

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: .firstName=john&.country=DE

Optional parameter to set the value of custom attributes. They are defined in the Campaign Manager, see Managing attributes.

Prefix each attribute name with . or _.

Certain attributes can also be set to mandatory in your Application settings. If your Application uses mandatory attributes, you must use this parameter to set their value.

The type of the value must match the type of the attribute. If you provide an integer value, the attribute must also be of type Integer in Talon.One.

If the types do not match, and the attribute in Talon.One is of type String, put the value in quotes. For example, if you provide a Boolean value for a String attribute, use "true" and "false".

Full URI example: https://<url>?applicationId=5&.myIntegerAttribute=1234&.myStringAttribute1=Text&.myStringAttribute2="1234"&.myStringAttribute3="true".

Responses

Response samples

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": {
    },
  • "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.

This endpoint only works with profile-based loyalty programs.

Authorizations:
ApiKeyAuth
query Parameters
deployment
required
string
Example: deployment=company.talon.one

The base URL of your Talon.One 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 profile-based loyalty program in Talon.One.

Responses

Response samples

Content type
application/json
{
  • "id": 302,
  • "title": "My loyalty program",
  • "name": "myloyaltyprogram",
  • "ledger": {
    },
  • "subLedgers": {
    }
}

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 has set up the Talon.One integration in mParticle.
  • audience_membership_change_request: Customers have been added to or removed from an audience in mParticle.
  • audience_subscription_request: An audience has been added, updated, or deleted in mParticle.
  • event_processing_request: One or more events have been triggered in mParticle.
This endpoint is not meant to be triggered manually. The above events are handled internally when using mParticle's feed inputs, event outputs, and audience outputs.
Request Body schema: application/json
One of
type
required
string

The type of the mParticle request. Must be set to module_registration_request.

required
object

The account settings for your Talon.One integration.

account_id
integer

The mParticle account ID.

object
apiKey
required
string

The mParticle API key you created in Talon.One.

deploymentURL
required
string

The base URL of your Talon.One deployment.

userIdField
required
string
Enum: "email" "customerId" "mpid"

Indicates how to identify customer profiles. If set to email or customerId, you must provide customer data in user_identities.

runRuleEngine
boolean

Indicates whether to run the Rule Engine.

id
string

The ID of the request.

timestamp_ms
integer

The timestamp of the request (in milliseconds).

firehose_version
string

The internal mParticle API version.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "module_registration_request",
  • "id": "62cdcd11-3913-4c66-a2c7-01ae7a445a61",
  • "timestamp_ms": 1586980879793,
  • "firehose_version": "2.4.0",
  • "account": {
    }
}

Response samples

Content type
application/json
Example
{
  • "type": "module_registration_response",
  • "id": "62cdcd11-3913-4c66-a2c7-01ae7a445a61",
  • "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": {
    },
  • "audience_processing_registration": {
    },
  • "event_processing_registration": {
    }
}

Segment

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

Use these endpoints to integrate with Talon.One.

Upsert customer profile Deprecated

Important: This endpoint is deprecated. We recommend you use the current Update customer profile endpoint.

Create or update the given customer profile, and creates or set the specified attributes. You can also use this endpoint to specify which audiences this customer has joined or left.

Note: The audiences must be created first with Create audience.

Authorizations:
ApiKeyAuth
path Parameters
customerProfileId
required
string
Example: customer1

The integration ID of the customer profile. If the customer profile does not exist, it will be created.

header Parameters
destination-hostname
required
string <hostname>
Example: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

Request Body schema: application/json
object

Property to set the attributes of your choice to the values of your choice.

You can use built-in attributes or custom ones.

Custom attributes must be created in the Campaign Manager before you set them with this property.

property name*
additional property
any
runRuleEngine
boolean
Default: false

Indicates whether to run the Rule Engine.

If true, the rules are run and their effects are applied, and audience changes are applied.

If false:

  • The rules are not executed.
  • The response time improves.
  • Audience changes are not applied.
object

A list of audiences where the customer should be removed or added.

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.

Array of objects

Allows you to set the type of the attribute to create instead of relying on auto-type detection.

For example, if you have a hasClickedProduct attribute set to false (boolean) in the attributes property, it will be created as boolean automatically. But to force it to be of type string, use the attributesInfo field to declare it at as a string.

Note: List types cannot be converted. A listOfSomething attribute set to (list string) type,) must not be declared as string in attributesInfo field.

Array
name
string

Attribute name

type
string
Enum: "string" "time" "number" "boolean" "location"

The data type of the attribute. When using time, send the attribute value as a string conforming to the RFC3339 timestamp format.

Responses

Request samples

Content type
application/json
{
  • "runRuleEngine": false,
  • "audiencesChanges": {
    },
  • "attributes": {
    },
  • "attributesInfo": [
    ]
}

Response samples

Content type
application/json
{
  • "customerProfile": {
    },
  • "createdAttributes": [
    ]
}

Upsert customer profile V2 Deprecated

Important: This endpoint is deprecated. We recommend you use the current Update customer profile endpoint.

Create or update the given customer profile, and also creates or set the specified attributes and audiences.

You do not have to create attributes or audiences before using this endpoint.

Authorizations:
ApiKeyAuth
path Parameters
customerProfileId
required
string
Example: customer1

The integration ID of the customer profile.

header Parameters
destination-hostname
required
string <hostname>
Example: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

Request Body schema: application/json
object

Property to set the attributes of your choice to the values of your choice.

You can use built-in attributes or custom ones.

Custom attributes must be created in the Campaign Manager before you set them with this property.

property name*
additional property
any
runRuleEngine
boolean
Default: false

Indicates whether to run the Rule Engine.

If true, the rules are run and their effects are applied, and audience changes are applied.

If false:

  • The rules are not executed.
  • The response time improves.
  • Audience changes are not applied.
object
Array of objects

The audiences for the customer to join.

Array
name
required
string

The name of the audience belonging to this entity.

integrationId
string non-empty

The integration ID of the audience. You can either use an existing audience ID, or assign a new one.

When you specify a new integration ID with this property, all A-Z, a-z and 0-9 characters are preserved and all other characters are replaced by _. For example, My Travel audience1 becomes My_Travel_audience1

Array of objects

The audiences for the customer to leave.

Array
name
required
string

The name of the audience belonging to this entity.

integrationId
string non-empty

The integration ID of the audience. You can either use an existing audience ID, or assign a new one.

When you specify a new integration ID with this property, all A-Z, a-z and 0-9 characters are preserved and all other characters are replaced by _. For example, My Travel audience1 becomes My_Travel_audience1

Array of objects

Allows you to set the type of the attribute to create instead of relying on auto-type detection.

For example, if you have a hasClickedProduct attribute set to false (boolean) in the attributes property, it will be created as boolean automatically. But to force it to be of type string, use the attributesInfo field to declare it at as a string.

Note: List types cannot be converted. A listOfSomething attribute set to (list string) type,) must not be declared as string in attributesInfo field.

Array
name
string

Attribute name

type
string
Enum: "string" "time" "number" "boolean" "location"

The data type of the attribute. When using time, send the attribute value as a string conforming to the RFC3339 timestamp format.

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    },
  • "runRuleEngine": false,
  • "audiencesChanges": {
    },
  • "attributesInfo": [
    ]
}

Response samples

Content type
application/json
{
  • "customerProfile": {
    },
  • "createdAttributes": [
    ],
  • "audiences": [
    ]
}

Update customer profile

Update or create a customer profile. This endpoint triggers the Rule Builder.

You can use this endpoint for the following tasks:

  • Set attributes for the given customer profile. Ensure you create the attributes in the Campaign Manager first.
  • Add the customer profile to audiences or remove it from audiences.
Authorizations:
ApiKeyAuth
path Parameters
customerProfileId
required
string
Example: customer1

The integration ID of the customer profile. If the customer profile does not exist, it will be created.

query Parameters
skipNonExistingAttributes
boolean
Default: false
Example: skipNonExistingAttributes=true

Indicates whether to skip non-existing attributes.

If true, the non-existing attributes are skipped and a 400 error is not returned.

If false, a 400 error is returned in case of non-existing attributes.

header Parameters
destination-hostname
required
string <hostname>
Example: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

Request Body schema: application/json
object

Property to set the attributes of your choice to the values of your choice.

You can use built-in attributes or custom ones.

Custom attributes must be created in the Campaign Manager before you set them with this property.

property name*
additional property
any
runRuleEngine
boolean
Default: false

Indicates whether to run the Rule Engine.

If true, the rules are run and their effects are applied, and audience changes are applied.

If false:

  • The rules are not executed.
  • The response time improves.
  • Audience changes are not applied.
object

A list of audiences where the customer should be removed or added.

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.

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    },
  • "runRuleEngine": false,
  • "audiencesChanges": {
    }
}

Response samples

Content type
application/json
{
  • "customerProfile": {
    },
  • "event": {
    },
  • "loyalty": {
    },
  • "triggeredCampaigns": [
    ],
  • "ruleFailureReasons": [
    ],
  • "awardedGiveaways": [
    ],
  • "effects": [
    ],
  • "createdCoupons": [
    ],
  • "createdReferrals": [
    ]
}

Update audiences in multiple customer profiles

Update the specified audiences for the specified profiles.

If a provided customer profile doesn't exist, it will be created.

Authorizations:
ApiKeyAuth
header Parameters
destination-hostname
required
string <hostname>
Example: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

Request Body schema: application/json
Array of objects

Indicates audience changes for a selected profile.

Note: The total number of adds and deletes items should be equal to or less than 1000.

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

The integration ID of the customer profile. If the customer profile does not exist, it will be created.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "StatusCode": 400,
  • "Error": "No Deployment URL specified",
  • "RequestUUID": "fd2f7c55-d064-46e1-ab87-a39cb877cd82"
}

Update audiences in multiple customer profiles (external ID)

Update the specified audiences for the specified profiles. To identify the audience, you can use its ID in the third-party integration.

If a provided customer profile doesn't exist, it will be created.

Authorizations:
ApiKeyAuth
header Parameters
destination-hostname
required
string <hostname>
Example: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

Request Body schema: application/json
Array of objects

Indicates audience changes for a selected profile.

Note: The total number of adds and deletes items should be equal to or less than 1000.

Array
adds
Array of strings[ items non-empty ]

The external IDs of the audiences for the customer to join.

deletes
Array of strings[ items non-empty ]

The external IDs of the audiences for the customer to leave.

customerProfileId
string <string> <= 1000 characters

The integration ID of the customer profile. If the customer profile does not exist, it will be created.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "StatusCode": 400,
  • "Error": "No Deployment URL specified",
  • "RequestUUID": "fd2f7c55-d064-46e1-ab87-a39cb877cd82"
}

Track event Deprecated

Important: This endpoint is deprecated. We recommend you use the current Track Event endpoint.

Triggers a custom event inside Talon.One. You can then trigger rules when this event is received.

An event is a type of custom attribute, you must create it first in the Campaign Manager. See creating custom events. To see the events received by your Application in Talon.One, open the Application and click Events.

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: 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" "(list string)" "(list number)" "(list time)" "(list 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

The integration ID of the customer profile. If the customer profile does not exist, it will be created.

object

Property to set the attributes of your choice to the values of your choice.

You can use built-in attributes or custom ones.

Custom attributes must be created in the Campaign Manager before you set them with this property.

property name*
additional property
any
Array of objects

Allows you to set the type of the attribute to create instead of relying on auto-type detection.

For example, if you have a hasClickedProduct attribute set to false (boolean) in the attributes property, it will be created as boolean automatically. But to force it to be of type string, use the attributesInfo field to declare it at as a string.

Note: List types cannot be converted. A listOfSomething attribute set to (list string) type,) must not be declared as string in attributesInfo field.

Array
name
string

Attribute name

type
string
Enum: "string" "time" "number" "boolean" "location"

The data type of the attribute. When using time, send the attribute value as a string conforming to the RFC3339 timestamp format.

Responses

Request samples

Content type
application/json
{
  • "customerProfileId": "URN-GV8294NV",
  • "eventType": "mySegmentEvent",
  • "type": "string",
  • "eventAttributes": {
    },
  • "attributesInfo": [
    ]
}

Response samples

Content type
application/json
{
  • "customerSession": {
    },
  • "customerProfile": {
    },
  • "event": {
    },
  • "loyalty": {
    },
  • "referral": {
    },
  • "coupons": [
    ],
  • "triggeredCampaigns": [
    ],
  • "effects": [
    ],
  • "ruleFailureReasons": [
    ],
  • "createdCoupons": [
    ],
  • "createdReferrals": [
    ],
  • "awardedGiveaways": [
    ],
  • "return": {
    },
  • "previousReturns": [
    ]
}

Track event

Trigger a custom event inside Talon.One. You can then trigger rules when this event is received.

An event is a type of custom attribute, you must create it first in the Campaign Manager. See creating custom events. To see the events received by your Application in Talon.One, open the Application and click Events.

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

Note:

  • Create the event and all the required attributes before using this endpoint.
  • This v2 version replaces the previous v1 version of this endpoint.
Authorizations:
ApiKeyAuth
query Parameters
skipNonExistingAttributes
boolean
Default: false
Example: skipNonExistingAttributes=true

Indicates whether to skip non-existing attributes.

If true, the non-existing attributes are skipped and a 400 error is not returned.

If false, a 400 error is returned in case of non-existing attributes.

header Parameters
destination-hostname
required
string <hostname>
Example: 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.

object

Property to set the attributes of your choice to the values of your choice.

You can use built-in attributes or custom ones.

Custom attributes must be created in the Campaign Manager before you set them with this property.

property name*
additional property
any
customerProfileId
string <string> <= 1000 characters

The integration ID of the customer profile. If the customer profile does not exist, it will be created.

Responses

Request samples

Content type
application/json
{
  • "eventType": "mySegmentEvent",
  • "eventAttributes": {
    },
  • "customerProfileId": "URN-GV8294NV"
}

Response samples

Content type
application/json
{
  • "customerSession": {
    },
  • "customerProfile": {
    },
  • "event": {
    },
  • "loyalty": {
    },
  • "referral": {
    },
  • "coupons": [
    ],
  • "triggeredCampaigns": [
    ],
  • "effects": [
    ],
  • "ruleFailureReasons": [
    ],
  • "createdCoupons": [
    ],
  • "createdReferrals": [
    ],
  • "awardedGiveaways": [
    ],
  • "return": {
    },
  • "previousReturns": [
    ]
}

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: 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 integration 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

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"
}

Update audience

Update an audience.

Authorizations:
ApiKeyAuth
path Parameters
audienceId
required
string
Example: audience1

The integration ID of the audience.

header Parameters
destination-hostname
required
string <hostname>
Example: 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 integration 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

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
string
Example: audience1

The integration ID of the audience.

header Parameters
destination-hostname
required
string <hostname>
Example: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

Responses

Response samples

Content type
application/json
{
  • "StatusCode": 400,
  • "Error": "No Deployment URL specified",
  • "RequestUUID": "fd2f7c55-d064-46e1-ab87-a39cb877cd82"
}

Update customer session Deprecated

Important: This endpoint is deprecated. We recommend you use the current Update customer session endpoint.

Update the given customer session, or creates it if it doesn't exist.

Customer sessions are a key concept in Talon.One, see the documentation.

This endpoint also allows you to define a callback where the response will be sent. See the Header parameters section below.

Authorizations:
ApiKeyAuth
path Parameters
customerSessionId
required
string
Example: session1

The integration ID of the customer session. You set this ID when you create a customer session.

You can see existing customer session integration IDs in the Campaign Manager's Sessions menu, or via the List Application session endpoint.

header Parameters
destination-hostname
required
string <hostname>
Example: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

X-Callback-Destination-URI
string <hostname>
Example: http://mydomain.com/api/callbacks

The full URI where Talon.One sends the response content. The callback is a POST request.

X-Callback-API-Key
string
Example: Authorization 3aa74d582bd9479c59e16f970fe13bf3

The header and the API key, separated by a space. The first space marks the header.

For example:

  • To set Authorization: 3aa74d582bd94, use Authorization 3aa74d582bd94.
  • To set Authorization: ApiKey-v1 3aa74d582bd94, use Authorization ApiKey-v1 3aa74d582bd94.

The minimal length of the API key is 32 characters.

X-Content-Fields
string
Enum: "customerSession" "customerProfile" "coupons" "triggeredCampaigns" "referral" "loyalty" "event" "awardedGiveaways" "ruleFailureReasons" "previousReturns" … 4 more
Example: customerProfile

A comma-separated list of field names from the Update customer endpoint's response that you want to receive.

If omitted, all the fields will be sent to the callback destination URI.

X-Correlation-ID
string
Example: abc123

An arbitrary ID assigned to the callback request. You can use it to track the callbacks you receive from Talon.One. If omitted, the callback request does not include X-Correlation-ID.

Request Body schema: application/json
object
profileId
string

ID of the customers profile as used within this Talon.One account.

couponCodes
Array of strings[ items <= 100 characters ]

Any coupon codes entered.

Important: If you create a coupon budget for your campaign, ensure the session contains a coupon code by the time you close it.

referralCode
string <= 100 characters

Any referral code entered.

Important: If you create a referral budget for your campaign, ensure the session contains a referral code by the time you close it.

loyaltyCards
Array of strings <= 1 items

Any loyalty cards used.

state
string
Default: "open"
Enum: "open" "closed" "partially_returned" "cancelled"

Indicates the current state of the session. Sessions can be created as open or closed. The state transitions are:

  1. open → closed
  2. open → cancelled
  3. Either:
  1. partially_returned → cancelled

For more information, see Customer session states.

Array of objects

The items to add to this sessions.

  • If cart item flattening is disabled: Do not exceed 1000 items (regardless of their quantity) per request.
  • If cart item flattening is enabled: Do not exceed 1000 items and ensure the sum of all cart item's quantity does not exceed 10.000 per request.
Array
sku
required
string non-empty

Stock keeping unit of item.

quantity
required
integer >= 1

Quantity of item. Important: If you enabled cart item flattening, the quantity is always one and the same cart item might receive multiple per-item discounts. Ensure you can process multiple discounts on one cart item correctly.

name
string non-empty

Name of item.

returnedQuantity
integer

Number of returned items, calculated internally based on returns of this item.

remainingQuantity
integer

Remaining quantity of the item, calculated internally based on returns of this item.

price
number

Price of the item in the currency defined by your Application. This field is required if this item is not part of a catalog. If it is part of a catalog, setting a price here overrides the price from the catalog.

category
string

Type, group or model of the item.

weight
number

Weight of item in grams.

height
number

Height of item in mm.

width
number

Width of item in mm.

length
number

Length of item in mm.

position
number

Position of the Cart Item in the Cart (calculated internally).

object

Use this property to set a value for the attributes of your choice. Attributes represent any information to attach to this cart item.

Custom cart item attributes must be created in the Campaign Manager before you set them with this property.

property name*
additional property
any
object

Use this property to set a value for the additional costs of this item, such as a shipping cost. They must be created in the Campaign Manager before you set them with this property. See Managing additional costs.

additional property
object
price
number

Price of the additional cost.

object

Use this property to set a value for the additional costs of this session, such as a shipping cost.

They must be created in the Campaign Manager before you set them with this property. See Managing additional costs.

additional property
object
price
number

Price of the additional cost.

identifiers
Array of strings <= 5 items

Session custom identifiers that you can set limits on or use inside your rules.

For example, you can use IP addresses as identifiers to potentially identify devices and limit discounts abuse in case of customers creating multiple accounts. See the tutorial.

Important: If you create a unique identifier budget for your campaign, ensure the session contains an identifier by the time you close it.

object

Use this property to set a value for the attributes of your choice. Attributes represent any information to attach to your session, like the shipping city.

You can use built-in attributes or custom ones. Custom attributes must be created in the Campaign Manager before you set them with this property.

Note: If null, the attribute is deleted from the customer session.

property name*
additional property
any
Array of objects

Allows you to set the type of the attribute to create instead of relying on auto-type detection.

For example, if you have a hasClickedProduct attribute set to false (boolean) in the attributes property, it will be created as boolean automatically. But to force it to be of type string, use the attributesInfo field to declare it at as a string.

Note: List types cannot be converted. A listOfSomething attribute set to (list string) type,) must not be declared as string in attributesInfo field.

Array
name
string

Attribute name

type
string
Enum: "string" "time" "number" "boolean" "location"

The data type of the attribute. When using time, send the attribute value as a string conforming to the RFC3339 timestamp format.

Array of objects

Allows you to set the type of the attribute to create instead of relying on auto-type detection.

For example, if you have a hasClickedProduct attribute set to false (boolean) in the attributes property, it will be created as boolean automatically. But to force it to be of type string, use the attributesInfo field to declare it at as a string.

Note: List types cannot be converted. A listOfSomething attribute set to (list string) type,) must not be declared as string in attributesInfo field.

Array
name
string

Attribute name

type
string
Enum: "string" "time" "number" "boolean" "location"

The data type of the attribute. When using time, send the attribute value as a string conforming to the RFC3339 timestamp format.

Responses

Request samples

Content type
application/json
{
  • "customerSession": {
    },
  • "sessionAttributesInfo": [
    ],
  • "cartItemAttributesInfo": [
    ]
}

Response samples

Content type
application/json
{
  • "customerSession": {
    },
  • "customerProfile": {
    },
  • "event": {
    },
  • "loyalty": {
    },
  • "referral": {
    },
  • "coupons": [
    ],
  • "triggeredCampaigns": [
    ],
  • "effects": [
    ],
  • "ruleFailureReasons": [
    ],
  • "createdCoupons": [
    ],
  • "createdReferrals": [
    ],
  • "awardedGiveaways": [
    ],
  • "return": {
    },
  • "previousReturns": [
    ]
}

Update customer session

Update the given customer session, or create a customer session if it doesn't exist.

Customer sessions are a key concept in Talon.One, see the documentation.

This endpoint also allows you to define a callback where the response will be sent. See the Header parameters section below.

Note:

  • Create all the required attributes before using this endpoint.
  • This v2 version replaces the previous v1 version of this endpoint.
Authorizations:
ApiKeyAuth
path Parameters
customerSessionId
required
string
Example: session1

The integration ID of the customer session. You set this ID when you create a customer session.

You can see the existing customer session integration IDs in the Campaign Manager's Sessions menu, or via the List Application session endpoint.

query Parameters
skipNonExistingAttributes
boolean
Default: false
Example: skipNonExistingAttributes=true

Indicates whether to skip non-existing attributes.

If true, the non-existing attributes are skipped and a 400 error is not returned.

If false, a 400 error is returned in case of non-existing attributes.

header Parameters
destination-hostname
required
string <hostname>
Example: mycompany.europe-west1.talon.one

The base URL of your Talon.One deployment.

X-Callback-Destination-URI
string <hostname>
Example: http://mydomain.com/api/callbacks

The full URI where Talon.One sends the response content. The callback is a POST request.

X-Callback-API-Key
string
Example: Authorization 3aa74d582bd9479c59e16f970fe13bf3

The header and the API key, separated by a space. The first space marks the header.

For example:

  • To set Authorization: 3aa74d582bd94, use Authorization 3aa74d582bd94.
  • To set Authorization: ApiKey-v1 3aa74d582bd94, use Authorization ApiKey-v1 3aa74d582bd94.

The minimal length of the API key is 32 characters.

X-Content-Fields
string
Enum: "customerSession" "customerProfile" "coupons" "triggeredCampaigns" "referral" "loyalty" "event" "awardedGiveaways" "ruleFailureReasons" "previousReturns" … 4 more
Example: customerProfile

A comma-separated list of field names from the Update customer endpoint's response that you want to receive.

If omitted, all the fields will be sent to the callback destination URI.

X-Correlation-ID
string
Example: abc123

An arbitrary ID assigned to the callback request. You can use it to track the callbacks you receive from Talon.One. If omitted, the callback request does not include X-Correlation-ID.

Request Body schema: application/json
profileId
string

ID of the customers profile as used within this Talon.One account.

couponCodes
Array of strings[ items <= 100 characters ]

Any coupon codes entered.

Important: If you create a coupon budget for your campaign, ensure the session contains a coupon code by the time you close it.

referralCode
string <= 100 characters

Any referral code entered.

Important: If you create a referral budget for your campaign, ensure the session contains a referral code by the time you close it.

loyaltyCards
Array of strings <= 1 items

Any loyalty cards used.

state
string
Default: "open"
Enum: "open" "closed" "partially_returned" "cancelled"

Indicates the current state of the session. Sessions can be created as open or closed. The state transitions are:

  1. open → closed
  2. open → cancelled
  3. Either:
  1. partially_returned → cancelled

For more information, see Customer session states.

Array of objects

The items to add to this sessions.

  • If cart item flattening is disabled: Do not exceed 1000 items (regardless of their quantity) per request.
  • If cart item flattening is enabled: Do not exceed 1000 items and ensure the sum of all cart item's quantity does not exceed 10.000 per request.
Array
sku
required
string non-empty

Stock keeping unit of item.

quantity
required
integer >= 1

Quantity of item. Important: If you enabled cart item flattening, the quantity is always one and the same cart item might receive multiple per-item discounts. Ensure you can process multiple discounts on one cart item correctly.

name
string non-empty

Name of item.

returnedQuantity
integer

Number of returned items, calculated internally based on returns of this item.

remainingQuantity
integer

Remaining quantity of the item, calculated internally based on returns of this item.

price
number

Price of the item in the currency defined by your Application. This field is required if this item is not part of a catalog. If it is part of a catalog, setting a price here overrides the price from the catalog.

category
string

Type, group or model of the item.

weight
number

Weight of item in grams.

height
number

Height of item in mm.

width
number

Width of item in mm.

length
number

Length of item in mm.

position
number

Position of the Cart Item in the Cart (calculated internally).

object

Use this property to set a value for the attributes of your choice. Attributes represent any information to attach to this cart item.

Custom cart item attributes must be created in the Campaign Manager before you set them with this property.

property name*
additional property
any
object

Use this property to set a value for the additional costs of this item, such as a shipping cost. They must be created in the Campaign Manager before you set them with this property. See Managing additional costs.

additional property
object
price
number

Price of the additional cost.

object

Use this property to set a value for the additional costs of this session, such as a shipping cost.

They must be created in the Campaign Manager before you set them with this property. See Managing additional costs.

additional property
object
price
number

Price of the additional cost.

identifiers
Array of strings <= 5 items

Session custom identifiers that you can set limits on or use inside your rules.

For example, you can use IP addresses as identifiers to potentially identify devices and limit discounts abuse in case of customers creating multiple accounts. See the tutorial.

Important: If you create a unique identifier budget for your campaign, ensure the session contains an identifier by the time you close it.

object

Use this property to set a value for the attributes of your choice. Attributes represent any information to attach to your session, like the shipping city.

You can use built-in attributes or custom ones. Custom attributes must be created in the Campaign Manager before you set them with this property.

Note: If null, the attribute is deleted from the customer session.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "profileId": "URN-GV8294NV",
  • "couponCodes": [
    ],
  • "referralCode": "NT2K54D9",
  • "loyaltyCards": [
    ],
  • "state": "open",
  • "cartItems": [
    ],
  • "additionalCosts": {
    },
  • "identifiers": [
    ],
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "customerSession": {
    },
  • "customerProfile": {
    },
  • "event": {
    },
  • "loyalty": {
    },
  • "referral": {
    },
  • "coupons": [
    ],
  • "triggeredCampaigns": [
    ],
  • "effects": [
    ],
  • "ruleFailureReasons": [
    ],
  • "createdCoupons": [
    ],
  • "createdReferrals": [
    ],
  • "awardedGiveaways": [
    ],
  • "return": {
    },
  • "previousReturns": [
    ]
}