Skip to main content
API docs by Redocly

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:

Authentication

ApiKeyAuth

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

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

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

Authorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3
Security Scheme Type: API Key
Header parameter name: Authorization

Braze

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

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

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

Create referral

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

Authorizations:
ApiKeyAuth
header Parameters
X-DRY-RUN
boolean
Example: true

Indicates whether to persist the changes. Changes are ignored when 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.

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.

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,
  • "integrationId": "URN-GV8294NV",
  • "startDate": "2021-09-30T15:35:02.371569+02:00",
  • "expiryDate": "2024-10-03T15:35:02.371569+02:00",
  • "validCharacters": [
    ],
  • "couponPattern": "ew-####",
  • "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,
  • "Attributes": {
    }
}

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

Unique Customer Profile ID.

identifier
required
string non-empty

The identifier of the request. Providing a new value sends a new event to Talon.One. Providing an existing value retrieves the existing event of that id.

In general, you should set it to a dispatch_id variable controlled by Braze.

See dispatch ID behavior.

object

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

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

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 the given customer profile to add or remove audiences.

Note: Create all the required attributes and audiences before using this endpoint.

Authorizations:
ApiKeyAuth
path Parameters
customerProfileId
required
string
Example: URN-GV8294NV

The integration ID of the customer profile.

query Parameters
skipNonExistingAttributes
boolean
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.

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.

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 is created automatically.

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

Unique Customer Profile ID.

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

Content type
application/json
{
  • "audienceId": "382370BKDB946",
  • "audienceName": "Travel audience"
}

Response samples

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

Delete audience

Delete an audience created by a third-party integration.

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

Authorizations:
ApiKeyAuth
path Parameters
audienceId
required
integer <int64>
Example: 4729630

The ID of the audience.

header Parameters
customer-data-platform-name
required
string <string>
Example: My CDP platform

The name of the CDP platform.

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

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

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.

Full URI example: https://<url>?applicationId=5&.myAttribute1=1234&.myAttribute2=abc.

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 ..

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.

Full URI example: https://<url>?applicationId=5&.myAttribute1=1234&.myAttribute2=abc.

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.

Authorizations:
ApiKeyAuth
query Parameters
profileIntegrationId
required
string
Example: profileIntegrationId=URN-GV8294NV

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

loyaltyProgramId
required
integer <int64>
Example: loyaltyProgramId=25

The ID of the loyalty program in Talon.One.

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

Iterable

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

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

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

Create coupon

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

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

The base URL of your deployment.

applicationId
required
integer <int64>
Example: applicationId=316

The ID of the Application in Talon.One. 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 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: .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 ..

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.

Full URI example: https://<url>?applicationId=5&.myAttribute1=1234&.myAttribute2=abc.

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 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 ..

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.

Full URI example: https://<url>?applicationId=5&.myAttribute1=1234&.myAttribute2=abc.

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.

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

The base URL of your deployment.

profileIntegrationId
required
string
Example: profileIntegrationId=URN-GV8294NV

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

loyaltyProgramId
required
integer <int64>
Example: loyaltyProgramId=25

The ID of the loyalty program in Talon.One.

Responses

Response samples

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

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

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.

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

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.

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.

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

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.

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

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

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.

Responses

Request samples

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

Response samples

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

Update customer profile

Create or update the given customer profile.

Note:

Authorizations:
ApiKeyAuth
path Parameters
customerProfileId
required
string

The integration ID of the customer profile.

query Parameters
skipNonExistingAttributes
boolean
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.

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

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.

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 is created automatically.

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

Unique Customer Profile ID.

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

Unique Customer Profile ID.

object

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

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

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.

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
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.

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

customerProfileId
string <string> <= 1000 characters

Unique Customer Profile ID.

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 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
integer <int64>
Example: 4729630

The 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 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
integer <int64>
Example: 4729630

The 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

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: effects, customerProfile, customerSession

A comma-separated list of field names from the Update customer enpdoint'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
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 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.

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": [