Skip to main content

Management API reference docs

Download OpenAPI specification:Download

The Talon.One Management API is the channel between the Campaign Manager and the Rule Engine. For more background information about this API, see Management API overview

Use the Management API to programmatically do what the Campaign Manager does. For example, use it for management purposes and backoffice systems.

Ensure you authenticate to make requests to the API.

Warnings:

  • This API is not meant to be used in real-time integrations that directly serve your end users.
  • This API supports a maximum of 3 requests per second for each of these endpoints.

Are you looking for a different API?

If you need the API to:

Authentication

manager_auth

This authentication scheme relies on a bearer token that you can use to access all the endpoints of the Management API.

To create the token:

  1. Get a bearer token by calling the createSession endpoint.
  2. Use the token property of the response in the HTTP header of your next queries: Authorization: Bearer $TOKEN.

A token is valid for 3 months. In accordance with best pratices, use your generated token for all your API requests. Do not regenerate a token for each request.

Note: We recommend that you use a Management API key instead of a bearer token.

Security Scheme Type: API Key
Header parameter name: Authorization

management_key

The API key authentication gives you access to the endpoints selected by the admin who created the key. Using an API key is the recommended authentication method.

The key must be generated by an admin and given to the developer that requires it:

  1. Log into the Campaign Manager and click Account > Management API keys.
  2. Click Create Key and give it a name.
  3. Set an expiration date.
  4. Choose the endpoints the key should give access to.
  5. Click Create Key.
  6. Share it with your developer.

The developer can now use the API key in the HTTP header, prefixing it with ManagementKey-v1:

Authorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3
Security Scheme Type: API Key
Header parameter name: Authorization

Accounts and users

Operations for updating account information such as billing email addresses, inviting users, etc.

List users in account

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Retrieve all users in your account.

Authorizations:
manager_authmanagement_key
query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

Responses

Response samples

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

Get user

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Retrieve the data (including an invitation code) for a user. Non-admin users can only get their own profile.

Authorizations:
manager_authmanagement_key
path Parameters
userId
required
integer

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "modified": "2021-09-12T10:12:42Z",
  • "email": "john.doe@example.com",
  • "accountId": 3886,
  • "inviteToken": "Gy9b8w1irmQtEPo5RmbMmSPheL5h4",
  • "state": "invited",
  • "name": "John Doe",
  • "policy": {
    },
  • "latestFeedTimestamp": "2020-06-01T00:00:00Z",
  • "roles": [
    ],
  • "applicationNotificationSubscriptions": null,
  • "authMethod": "basic_auth"
}

Request a password reset

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Send an email with a password recovery link to the email address of an existing account.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
email
required
string <email> non-empty

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "email": "user@example.com"
}

Reset password

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Consumes the supplied password reset token and updates the password for the associated account.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
password
required
string

The new password for your account.

resetToken
required
string non-empty

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "resetToken": "string"
}

Response samples

Content type
application/json
{
  • "password": "string",
  • "resetToken": "string"
}

Get account details

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Return the details of your companies Talon.One account.

Authorizations:
manager_authmanagement_key
path Parameters
accountId
required
integer

The identifier of the account. Retrieve it via the List users in account endpoint, in the accountId property.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "modified": "2021-09-12T10:12:42Z",
  • "companyName": "string",
  • "domainName": "string",
  • "state": "active",
  • "billingEmail": "user@example.com",
  • "planName": "string",
  • "planExpires": "2019-08-24T14:15:22Z",
  • "applicationLimit": 0,
  • "userLimit": 0,
  • "campaignLimit": 0,
  • "apiLimit": 0,
  • "applicationCount": 0,
  • "userCount": 0,
  • "campaignsActiveCount": 0,
  • "campaignsInactiveCount": 0,
  • "attributes": { }
}

Get account analytics

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Return the analytics of your Talon.One account.

Authorizations:
manager_authmanagement_key
path Parameters
accountId
required
integer

The identifier of the account. Retrieve it via the List users in account endpoint, in the accountId property.

Responses

Response samples

Content type
application/json
{
  • "applications": 11,
  • "liveApplications": 6,
  • "sandboxApplications": 2,
  • "campaigns": 35,
  • "activeCampaigns": 15,
  • "liveActiveCampaigns": 10,
  • "coupons": 850,
  • "activeCoupons": 650,
  • "expiredCoupons": 200,
  • "referralCodes": 500,
  • "activeReferralCodes": 100,
  • "expiredReferralCodes": 400,
  • "activeRules": 35,
  • "users": 0,
  • "roles": 10,
  • "customAttributes": 18,
  • "webhooks": 2,
  • "loyaltyPrograms": 5,
  • "liveLoyaltyPrograms": 5
}

Additional costs

An extra fee applied to the cart. For example, shipping fees, or processing fees. See the docs.

Create additional cost

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Create an additional cost.

These additional costs are shared across all applications in your account, and are never required.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
name
required
string^[A-Za-z](\w|\s)*$

The additional cost name that will be used in API requests and Talang. E.g. if name == "shipping" then you would set the shipping additional cost by including an additionalCosts.shipping property in your request payload.

title
required
string^[A-Za-z][A-Za-z0-9_.!~*'() -]*$

The human-readable name for the additional cost that will be shown in the Campaign Manager. Like name, the combination of entity and title must also be unique.

description
required
string

A description of this additional cost.

subscribedApplicationsIds
Array of integers

A list of the IDs of the applications that are subscribed to this additional cost.

type
string
Default: "session"
Enum: "session" "item" "both"

The type of additional cost. The following options can be chosen:

  • session: Additional cost will be added per session,
  • item: Additional cost will be added per item,
  • both: Additional cost will be added per item and session.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "subscribedApplicationsIds": [
    ],
  • "type": "session"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "subscribedApplicationsIds": [
    ],
  • "type": "session"
}

List additional costs

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Returns all the defined additional costs for the account.

Authorizations:
manager_authmanagement_key
query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

Responses

Response samples

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

Get additional cost

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Returns the additional cost.

Authorizations:
manager_authmanagement_key
path Parameters
additionalCostId
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "subscribedApplicationsIds": [
    ],
  • "type": "session"
}

Update additional cost

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Updates an existing additional cost. Once created, the only property of an additional cost that can be changed is the title (human readable description). This restriction is in place to prevent accidentally breaking live integrations.

Authorizations:
manager_authmanagement_key
path Parameters
additionalCostId
required
integer
Request Body schema: application/json
name
required
string^[A-Za-z](\w|\s)*$

The additional cost name that will be used in API requests and Talang. E.g. if name == "shipping" then you would set the shipping additional cost by including an additionalCosts.shipping property in your request payload.

title
required
string^[A-Za-z][A-Za-z0-9_.!~*'() -]*$

The human-readable name for the additional cost that will be shown in the Campaign Manager. Like name, the combination of entity and title must also be unique.

description
required
string

A description of this additional cost.

subscribedApplicationsIds
Array of integers

A list of the IDs of the applications that are subscribed to this additional cost.

type
string
Default: "session"
Enum: "session" "item" "both"

The type of additional cost. The following options can be chosen:

  • session: Additional cost will be added per session,
  • item: Additional cost will be added per item,
  • both: Additional cost will be added per item and session.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "subscribedApplicationsIds": [
    ],
  • "type": "session"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "subscribedApplicationsIds": [
    ],
  • "type": "session"
}

Analytics

Analytics are used to retrieve statistical data about the performance of campaigns within an application.

Export triggered effects

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Download a CSV file containing the triggered effects that match the given attributes.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

query Parameters
campaignId
number

Filter results by campaign.

createdBefore
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

createdAfter
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

dateFormat
string
Enum: "excel" "ISO8601"

Determines the format of dates in the export document.

Responses

Response samples

Content type
application/csv
created,name,applicationid,campaignid,rulesetid,ruleindex,sessionintegrationid,profileintegrationid,sessionid,profileid,eventid,event_type,total_revenue,props,couponid
2021-06-02T21:14:16Z,rejectCoupon,270,0,0,0,newsession1,,9168,0,95797,talon_session_created,265.00,"{""value"": ""XMAS20"", ""rejectionReason"": ""CouponNotFound""}",
2021-09-01T13:04:04Z,setDiscountPerItem,270,3882,13599,0,test_flattening_2,integid_4,9707,4800,98806,talon_session_updated,405.00,"{""name"": ""10% off per item#1"", ""value"": 11.0, ""position"": 1}"

Export customer sessions

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Download a CSV file containing the customer sessions that match the request.

Important: Archived sessions cannot be exported. See the retention policy.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

query Parameters
createdBefore
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string.

createdAfter
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string.

profileIntegrationId
string

Only return sessions for the customer that matches this customer integration ID.

dateFormat
string
Enum: "excel" "ISO8601"

Determines the format of dates in the export document.

customerSessionState
string
Enum: "open" "closed" "partially_returned" "cancelled"

Filter results by state.

Responses

Response samples

Content type
application/csv
id,firstsession,integrationid,applicationid,profileid,profileintegrationid,created,state,cartitems,discounts,total,attributes,closedat,cancelledat,referral,identifiers,additional_costs,updated,coupons
12327,true,62791173fbf323ee5cfd96f3,270,6111,dxclwds,2022-05-09T13:05:31Z,open,"[{""sku"": ""B00004TKVY"", ""name"": ""Gravel bike - \""Aisle of Man\"""", ""price"": 1800, ""weight"": 6, ""category"": ""gravelbikes"", ""position"": 0, ""quantity"": 1, ""attributes"": {""color"": [""black,white""], ""material"": ""titanium""}, ""returnedQuantity"": 0, ""remainingQuantity"": 1}]","{}",1850.00,"{""ShippingCost"": 50, ""PaymentMethod"": ""creditcard"", ""ShippingMethod"": ""Standard""}",0001-01-01T00:00:00Z,0001-01-01T00:00:00Z,,"null","{""ShippingCost"": {""price"": 50}}",2022-05-09T13:13:28Z,"[""SORRY5QMUJRWA""]"

Applications

Represents an Application in the Campaign Manager, see the docs. It is also the target of every Integration API request to Talon.One.

One Application can hold various API keys used for Integration API requests.

You may have multiple Applications within one account, for example staging and production, or different international markets.

List applications

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

List all applications in the current account.

Authorizations:
manager_authmanagement_key
query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

Responses

Response samples

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

Get application

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Get the application specified by the ID.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "modified": "2021-09-12T10:12:42Z",
  • "accountId": 3886,
  • "name": "My Application",
  • "description": "A test Application",
  • "timezone": "Europe/Berlin",
  • "currency": "EUR",
  • "caseSensitivity": "sensitive",
  • "attributes": { },
  • "limits": [
    ],
  • "campaignPriority": "universal",
  • "exclusiveCampaignsStrategy": "listOrder",
  • "defaultDiscountScope": "sessionTotal",
  • "enableCascadingDiscounts": true,
  • "enableFlattenedCartItems": true,
  • "attributesSettings": {
    },
  • "sandbox": true,
  • "enablePartialDiscounts": false,
  • "defaultDiscountAdditionalCostPerItemScope": "price",
  • "loyaltyPrograms": [
    ]
}

Get report of health of application API

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Display the health of the application and show the last time the Application was used.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

Responses

Response samples

Content type
application/json
{
  • "summary": "OK",
  • "lastUsed": "2021-09-12T10:12:42Z"
}

Attributes

Represents a piece of information related to one of the entities avaialbe in the Campaign Manager. Use them to create highly customized rules. See the docs.

Create custom attribute

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Create a custom attribute in this account. Custom attributes allow you to attach new fields to Talon.One domain objects like campaigns, coupons, customers and so on.

These attributes can then be given values when creating/updating these objects, and these values can be used in your campaign rules. For example, you could define a zipCode field for customer sessions, and add a rule to your campaign that only allows certain ZIP codes.

These attributes are shared across all applications in your account, and are never required.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
entity
required
string
Enum: "Account" "Application" "Campaign" "CustomerProfile" "CustomerSession" "CartItem" "Coupon" "Event" "Giveaway" "Referral"

The name of the entity that can have this attribute. When creating or updating the entities of a given type, you can include an attributes object with keys corresponding to the name of the custom attributes for that type.

name
required
string^[A-Za-z]\w*$

The attribute name that will be used in API requests and Talang. E.g. if name == "region" then you would set the region attribute by including an attributes.region property in your request payload.

title
required
string^[A-Za-z][A-Za-z0-9_.!~*'() -]*$

The human-readable name for the attribute that will be shown in the Campaign Manager. Like name, the combination of entity and title must also be unique.

type
required
string
Enum: "string" "number" "boolean" "time" "(list string)" "(list number)" "(list time)" "location" "(list location)"

The data type of the attribute, a time attribute must be sent as a string that conforms to the RFC3339 timestamp format.

description
required
string

A description of this attribute.

suggestions
required
Array of strings <= 50 items [ items non-empty ]

A list of suggestions for the attribute.

editable
required
boolean

Whether or not this attribute can be edited.

eventType
string
hasAllowedList
boolean
Default: false

Whether or not this attribute has an allowed list of values associated with it.

restrictedBySuggestions
boolean
Default: false

Whether or not this attribute's value is restricted by suggestions (suggestions property) or by an allowed list of value (hasAllowedList property).

subscribedApplicationsIds
Array of integers

A list of the IDs of the applications where this attribute is available.

subscribedCatalogsIds
Array of integers

A list of the IDs of the catalogs where this attribute is available.

allowedSubscriptions
Array of strings <= 2 items
Items Enum: "application" "catalog"

A list of allowed subscription types for this attribute.

Note: This only applies to attributes associated with the CartItem entity.

Responses

Request samples

Content type
application/json
{
  • "entity": "Account",
  • "eventType": "string",
  • "name": "string",
  • "title": "string",
  • "type": "string",
  • "description": "string",
  • "suggestions": [
    ],
  • "hasAllowedList": false,
  • "restrictedBySuggestions": false,
  • "editable": true,
  • "subscribedApplicationsIds": [
    ],
  • "subscribedCatalogsIds": [
    ],
  • "allowedSubscriptions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "entity": "Account",
  • "eventType": "string",
  • "name": "string",
  • "title": "string",
  • "type": "string",
  • "description": "string",
  • "suggestions": [
    ],
  • "hasAllowedList": false,
  • "restrictedBySuggestions": false,
  • "editable": true,
  • "subscribedApplicationsIds": [
    ],
  • "subscribedCatalogsIds": [
    ],
  • "allowedSubscriptions": [
    ],
  • "eventTypeId": 22
}

List custom attributes

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Returns all the defined custom attributes for the account.

Authorizations:
manager_authmanagement_key
query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

entity
string

Returned attributes will be filtered by supplied entity.

Responses

Response samples

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

Get custom attribute

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Returns custom attribute for the account by its id.

Authorizations:
manager_authmanagement_key
path Parameters
attributeId
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "entity": "Account",
  • "eventType": "string",
  • "name": "string",
  • "title": "string",
  • "type": "string",
  • "description": "string",
  • "suggestions": [
    ],
  • "hasAllowedList": false,
  • "restrictedBySuggestions": false,
  • "editable": true,
  • "subscribedApplicationsIds": [
    ],
  • "subscribedCatalogsIds": [
    ],
  • "allowedSubscriptions": [
    ],
  • "eventTypeId": 22
}

Update custom attribute

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Updates an existing custom attribute. Once created, the only property of a custom attribute that can be changed is the title (human readable description). This restriction is in place to prevent accidentally breaking live integrations. E.g. if you have a customer profile attribute with the name region, and your integration is sending attributes.region with customer profile updates, changing the name to locale would cause the integration requests to begin failing.

If you really need to change the type or name property of a custom attribute, create a new attribute and update any relevant integrations and rules to use the new attribute. Then delete the old attribute when you are confident you have migrated any needed data from the old attribute to the new one.

Authorizations:
manager_authmanagement_key
path Parameters
attributeId
required
integer
Request Body schema: application/json
entity
required
string
Enum: "Account" "Application" "Campaign" "CustomerProfile" "CustomerSession" "CartItem" "Coupon" "Event" "Giveaway" "Referral"

The name of the entity that can have this attribute. When creating or updating the entities of a given type, you can include an attributes object with keys corresponding to the name of the custom attributes for that type.

name
required
string^[A-Za-z]\w*$

The attribute name that will be used in API requests and Talang. E.g. if name == "region" then you would set the region attribute by including an attributes.region property in your request payload.

title
required
string^[A-Za-z][A-Za-z0-9_.!~*'() -]*$

The human-readable name for the attribute that will be shown in the Campaign Manager. Like name, the combination of entity and title must also be unique.

type
required
string
Enum: "string" "number" "boolean" "time" "(list string)" "(list number)" "(list time)" "location" "(list location)"

The data type of the attribute, a time attribute must be sent as a string that conforms to the RFC3339 timestamp format.

description
required
string

A description of this attribute.

suggestions
required
Array of strings <= 50 items [ items non-empty ]

A list of suggestions for the attribute.

editable
required
boolean

Whether or not this attribute can be edited.

eventType
string
hasAllowedList
boolean
Default: false

Whether or not this attribute has an allowed list of values associated with it.

restrictedBySuggestions
boolean
Default: false

Whether or not this attribute's value is restricted by suggestions (suggestions property) or by an allowed list of value (hasAllowedList property).

subscribedApplicationsIds
Array of integers

A list of the IDs of the applications where this attribute is available.

subscribedCatalogsIds
Array of integers

A list of the IDs of the catalogs where this attribute is available.

allowedSubscriptions
Array of strings <= 2 items
Items Enum: "application" "catalog"

A list of allowed subscription types for this attribute.

Note: This only applies to attributes associated with the CartItem entity.

Responses

Request samples

Content type
application/json
{
  • "entity": "Account",
  • "eventType": "string",
  • "name": "string",
  • "title": "string",
  • "type": "string",
  • "description": "string",
  • "suggestions": [
    ],
  • "hasAllowedList": false,
  • "restrictedBySuggestions": false,
  • "editable": true,
  • "subscribedApplicationsIds": [
    ],
  • "subscribedCatalogsIds": [
    ],
  • "allowedSubscriptions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "entity": "Account",
  • "eventType": "string",
  • "name": "string",
  • "title": "string",
  • "type": "string",
  • "description": "string",
  • "suggestions": [
    ],
  • "hasAllowedList": false,
  • "restrictedBySuggestions": false,
  • "editable": true,
  • "subscribedApplicationsIds": [
    ],
  • "subscribedCatalogsIds": [
    ],
  • "allowedSubscriptions": [
    ],
  • "eventTypeId": 22
}

Import allowed values for attribute

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Upload a CSV file containing a list of picklist values for the specified attribute.

The file should be sent as multipart data.

The import replaces the previous list of allowed values for this attribute, if any.

The CSV file must only contain the following column:

  • item (required): the values in your allowed list, for example a list of SKU's.

An allowed list is limited to 500,000 items.

Example:

item
CS-VG-04032021-UP-50D-10
CS-DV-04042021-UP-49D-12
CS-DG-02082021-UP-50G-07
Authorizations:
manager_authmanagement_key
path Parameters
attributeId
required
integer
Request Body schema: multipart/form-data
upFile
string <csv>

The file with the information about the data that should be imported.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "userId": 0,
  • "entity": "AttributeAllowedList",
  • "amount": 10
}

Audiences

Represents lists of customer profiles that allow you to target specific groups of customers in your campaigns. Audiences can be synced from customer data platforms or created directly in Talon.One. See the docs.

List audiences

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Get all audiences created in the account. To create an audience, use Create audience.

Authorizations:
manager_authmanagement_key
query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

withTotalResultSize
boolean

When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.

  • When true: hasMore is true when there is a next page. totalResultSize is always zero.
  • When false: hasMore is always false. totalResultSize contains the total number of results for this query.

Responses

Response samples

Content type
application/json
{
  • "hasMore": true,
  • "totalResultSize": 0,
  • "data": [
    ]
}

Campaign templates

Represents templates used to generate campaigns from.

Create campaign from campaign template

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Use the campaign template referenced in the request body to create a new campaign in one of the connected Applications.

If the template was created from a campaign with rules referencing campaign collections, the corresponding collections for the new campaign are created automatically.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

Request Body schema: application/json
name
required
string non-empty

A user-facing name for this campaign.

templateId
required
integer

The ID of the Campaign Template which will be used in order to create the Campaign.

description
string

A detailed description of the campaign.

object

Custom Campaign Attributes. If the Campaign Template defines the same values, they will be overridden.

Array of objects

Actual values to replace the template placeholder values in the Ruleset bindings. Values for all Template Parameters must be provided.

Array of objects

Limits for this Campaign. If the Campaign Template or Application define default values for the same limits, they will be overridden.

campaignGroups
Array of integers

The IDs of the campaign groups this campaign belongs to.

tags
Array of strings <= 50 items [ items [ 1 .. 50 ] characters ]

A list of tags for the campaign. If the campaign template has tags, they will be overridden by this list.

Responses

Request samples

Content type
application/json
{
  • "name": "Discount campaign",
  • "description": "This template is for discount campaigns.",
  • "templateId": 4,
  • "campaignAttributesOverrides": { },
  • "templateParamValues": [
    ],
  • "limitOverrides": [
    ],
  • "campaignGroups": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "campaign": {
    },
  • "ruleset": {
    },
  • "collections": [
    ]
}

Campaigns

Campaigns are the primary resource used to control the behavior of the Talon.One Rule Engine. They combine rulesets, coupons, and limits into a single unit.

List campaigns

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

List the campaigns of the specified application that match your filter criteria.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

campaignState
string
Enum: "enabled" "disabled" "archived" "draft" "scheduled" "running" "expired"

Filter results by the state of the campaign.

  • enabled: Campaigns that are scheduled, running (activated), or expired.
  • running: Campaigns that are running (activated).
  • disabled: Campaigns that are disabled.
  • expired: Campaigns that are expired.
  • archived: Campaigns that are archived.
  • draft: Campaigns that are drafts.
name
string

Filter results performing case-insensitive matching against the name of the campaign.

tags
string

Filter results performing case-insensitive matching against the tags of the campaign. When used in conjunction with the "name" query parameter, a logical OR will be performed to search both tags and name for the provided values

createdBefore
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

createdAfter
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

campaignGroupId
integer

Filter results to campaigns owned by the specified campaign group ID.

templateId
integer

The ID of the Campaign Template this Campaign was created from.

Responses

Response samples

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

Get campaign

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Retrieve the given campaign.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "applicationId": 322,
  • "userId": 0,
  • "name": "Summer promotions",
  • "description": "Campaign for all summer 2021 promotions",
  • "startTime": "2021-07-20T22:00:00Z",
  • "endTime": "2021-09-22T22:00:00Z",
  • "attributes": { },
  • "state": "enabled",
  • "activeRulesetId": 0,
  • "tags": [
    ],
  • "features": [
    ],
  • "couponSettings": {
    },
  • "referralSettings": {
    },
  • "limits": [
    ],
  • "campaignGroups": [
    ],
  • "couponRedemptionCount": 163,
  • "referralRedemptionCount": 3,
  • "discountCount": 288,
  • "discountEffectCount": 343,
  • "couponCreationCount": 16,
  • "customEffectCount": 0,
  • "referralCreationCount": 8,
  • "addFreeItemEffectCount": 0,
  • "awardedGiveawaysCount": 9,
  • "createdLoyaltyPointsCount": 9,
  • "createdLoyaltyPointsEffectCount": 2,
  • "redeemedLoyaltyPointsCount": 8,
  • "redeemedLoyaltyPointsEffectCount": 9,
  • "callApiEffectCount": 0,
  • "reservecouponEffectCount": 9,
  • "lastActivity": "2022-11-10T23:00:00Z",
  • "updated": "2022-10-97T35:00:00Z",
  • "createdBy": "John Doe",
  • "updatedBy": "Jane Doe",
  • "templateId": 3
}

Update campaign

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Update the given campaign.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

Request Body schema: application/json
name
required
string non-empty

A user-facing name for this campaign.

tags
required
Array of strings <= 50 items [ items [ 1 .. 50 ] characters ]

A list of tags for the campaign.

required
Array of objects

The set of limits that will operate for this campaign.

features
required
Array of strings
Items Enum: "coupons" "referrals" "loyalty" "giveaways" "strikethrough"

A list of features for the campaign.

description
string

A detailed description of the campaign.

startTime
string <date-time>

Timestamp when the campaign will become active.

endTime
string <date-time>

Timestamp when the campaign will become inactive.

object

Arbitrary properties associated with this campaign.

state
string
Default: "enabled"
Enum: "enabled" "disabled" "archived"

A disabled or archived campaign is not evaluated for rules or coupons.

activeRulesetId
integer

ID of Ruleset this campaign applies on customer session evaluation.

object
object
campaignGroups
Array of integers

The IDs of the campaign groups that own this entity.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "startTime": "2019-08-24T14:15:22Z",
  • "endTime": "2019-08-24T14:15:22Z",
  • "attributes": { },
  • "state": "enabled",
  • "activeRulesetId": 0,
  • "tags": [
    ],
  • "features": [
    ],
  • "couponSettings": {
    },
  • "referralSettings": {
    },
  • "limits": [
    ],
  • "campaignGroups": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "applicationId": 322,
  • "userId": 0,
  • "name": "Summer promotions",
  • "description": "Campaign for all summer 2021 promotions",
  • "startTime": "2021-07-20T22:00:00Z",
  • "endTime": "2021-09-22T22:00:00Z",
  • "attributes": { },
  • "state": "enabled",
  • "activeRulesetId": 0,
  • "tags": [
    ],
  • "features": [
    ],
  • "couponSettings": {
    },
  • "referralSettings": {
    },
  • "limits": [
    ],
  • "campaignGroups": [
    ],
  • "couponRedemptionCount": 163,
  • "referralRedemptionCount": 3,
  • "discountCount": 288,
  • "discountEffectCount": 343,
  • "couponCreationCount": 16,
  • "customEffectCount": 0,
  • "referralCreationCount": 8,
  • "addFreeItemEffectCount": 0,
  • "awardedGiveawaysCount": 9,
  • "createdLoyaltyPointsCount": 9,
  • "createdLoyaltyPointsEffectCount": 2,
  • "redeemedLoyaltyPointsCount": 8,
  • "redeemedLoyaltyPointsEffectCount": 9,
  • "callApiEffectCount": 0,
  • "reservecouponEffectCount": 9,
  • "lastActivity": "2022-11-10T23:00:00Z",
  • "updated": "2022-10-97T35:00:00Z",
  • "createdBy": "John Doe",
  • "updatedBy": "Jane Doe",
  • "templateId": 3
}

Delete campaign

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Delete the given campaign.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

Responses

Copy the campaign into the specified application

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Copy the campaign into all specified application.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

Request Body schema: application/json
applicationIds
required
Array of integers

Application IDs of the applications to which a campaign should be copied to.

name
string

Name of the copied campaign (Defaults to "Copy of original campaign name").

description
string

A detailed description of the campaign.

startTime
string <date-time>

Timestamp when the campaign will become active.

endTime
string <date-time>

Timestamp when the campaign will become inactive.

tags
Array of strings <= 50 items [ items [ 1 .. 50 ] characters ]

A list of tags for the campaign.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "applicationIds": [
    ],
  • "description": "string",
  • "startTime": "2019-08-24T14:15:22Z",
  • "endTime": "2019-08-24T14:15:22Z",
  • "tags": [
    ]
}

Response samples

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

List campaigns that match the given attributes

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Get a list of all the campaigns that match a set of attributes.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

campaignState
string
Enum: "enabled" "disabled" "archived" "draft" "scheduled" "running" "expired"

Filter results by the state of the campaign.

  • enabled: Campaigns that are scheduled, running (activated), or expired.
  • running: Campaigns that are running (activated).
  • disabled: Campaigns that are disabled.
  • expired: Campaigns that are expired.
  • archived: Campaigns that are archived.
  • draft: Campaigns that are drafts.
Request Body schema: application/json
required
object

Properties to match against a campaign. All provided attributes will be exactly matched against campaign attributes.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "attributes": { }
}

Response samples

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

List campaign rulesets

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

List all rulesets of this campaign. A ruleset is a revision of the rules of a campaign. Important: The response also includes deleted rules. You should only consider the latest revision of the returned rulesets.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

Responses

Response samples

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

Get ruleset

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Retrieve the specified ruleset.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

rulesetId
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "userId": 0,
  • "rules": [
    ],
  • "strikethroughRules": [
    ],
  • "bindings": [ ],
  • "rbVersion": "v2",
  • "activate": true,
  • "campaignId": 320,
  • "templateId": 3,
  • "activatedAt": "2019-08-24T14:15:22Z"
}

Get analytics of campaigns

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Retrieve statistical data about the performance of the given campaign.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

query Parameters
rangeStart
required
string <date-time>

Only return results from after this timestamp, must be an RFC3339 timestamp string.

rangeEnd
required
string <date-time>

Only return results from before this timestamp, must be an RFC3339 timestamp string.

granularity
string
Enum: "1 hour" "1 day" "1 week" "1 month" "1 year"

The time interval between the results in the returned time-series.

Responses

Response samples

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

Collections

Represents a collection of arbitrary values that you can use inside rules. For example, a list of SKUs. See the docs.

List collections in account

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

List collections in account.

Authorizations:
manager_authmanagement_key
query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

withTotalResultSize
boolean

When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.

  • When true: hasMore is true when there is a next page. totalResultSize is always zero.
  • When false: hasMore is always false. totalResultSize contains the total number of results for this query.
name
string

Filter by the name of the Collection.

Responses

Response samples

Content type
application/json
{
  • "hasMore": true,
  • "totalResultSize": 0,
  • "data": [
    ]
}

Create account-level collection

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Create account-level collection.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
name
required
string non-empty ^[^[:cntrl:]\s][^[:cntrl:]]*$

The name of this collection.

description
string

A short description of the purpose of this collection.

subscribedApplicationsIds
Array of integers

A list of the IDs of the Applications where this collection is enabled.

Responses

Request samples

Content type
application/json
{
  • "description": "My collection of SKUs",
  • "subscribedApplicationsIds": [
    ],
  • "name": "My collection"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "modified": "2021-09-12T10:12:42Z",
  • "description": "My collection of SKUs",
  • "subscribedApplicationsIds": [
    ],
  • "name": "My collection",
  • "modifiedBy": 48,
  • "createdBy": 134,
  • "applicationId": 1,
  • "campaignId": 7,
  • "payload": [
    ]
}

Get account-level collection

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Retrieve a given account-level collection.

Authorizations:
manager_authmanagement_key
path Parameters
collectionId
required
integer

The ID of the collection. You can get it with the List collection in account endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "modified": "2021-09-12T10:12:42Z",
  • "description": "My collection of SKUs",
  • "subscribedApplicationsIds": [
    ],
  • "name": "My collection",
  • "modifiedBy": 48,
  • "createdBy": 134,
  • "applicationId": 1,
  • "campaignId": 7,
  • "payload": [
    ]
}

Delete account-level collection

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Delete the given account-level collection.

Authorizations:
manager_authmanagement_key
path Parameters
collectionId
required
integer

The ID of the collection. You can get it with the List collection in account endpoint.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ],
  • "StatusCode": 0
}

Update account-level collection

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Edit the description of the account-level collection and enable or disable the collection in the specified Applications.

Authorizations:
manager_authmanagement_key
path Parameters
collectionId
required
integer

The ID of the collection. You can get it with the List collection in account endpoint.

Request Body schema: application/json
description
string

A short description of the purpose of this collection.

subscribedApplicationsIds
Array of integers

A list of the IDs of the Applications where this collection is enabled.

Responses

Request samples

Content type
application/json
{
  • "description": "My collection of SKUs",
  • "subscribedApplicationsIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "modified": "2021-09-12T10:12:42Z",
  • "description": "My collection of SKUs",
  • "subscribedApplicationsIds": [
    ],
  • "name": "My collection",
  • "modifiedBy": 48,
  • "createdBy": 134,
  • "applicationId": 1,
  • "campaignId": 7,
  • "payload": [
    ]
}

Get collection items

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Retrieve the items from the given collection.

Authorizations:
manager_authmanagement_key
path Parameters
collectionId
required
integer

The ID of the collection. You can get it with the List collection in account endpoint.

query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

Responses

Response samples

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

List collections in application

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

List collections from all campaigns in the Application.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

withTotalResultSize
boolean

When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.

  • When true: hasMore is true when there is a next page. totalResultSize is always zero.
  • When false: hasMore is always false. totalResultSize contains the total number of results for this query.
name
string

Filter by the name of the Collection.

Responses

Response samples

Content type
application/json
{
  • "hasMore": true,
  • "totalResultSize": 0,
  • "data": [
    ]
}

List collections

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

List collections in the campaign.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

withTotalResultSize
boolean

When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.

  • When true: hasMore is true when there is a next page. totalResultSize is always zero.
  • When false: hasMore is always false. totalResultSize contains the total number of results for this query.
name
string

Filter by the name of the Collection.

Responses

Response samples

Content type
application/json
{
  • "hasMore": true,
  • "totalResultSize": 0,
  • "data": [
    ]
}

Create collection

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Create a collection.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

Request Body schema: application/json
name
required
string non-empty ^[^[:cntrl:]\s][^[:cntrl:]]*$

The name of this collection.

description
string

A short description of the purpose of this collection.

Responses

Request samples

Content type
application/json
{
  • "description": "My collection of SKUs",
  • "name": "My collection"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "modified": "2021-09-12T10:12:42Z",
  • "description": "My collection of SKUs",
  • "subscribedApplicationsIds": [
    ],
  • "name": "My collection",
  • "modifiedBy": 48,
  • "createdBy": 134,
  • "applicationId": 1,
  • "campaignId": 7,
  • "payload": [
    ]
}

Get collection

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Retrieve a given collection.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

collectionId
required
integer

The ID of the collection. You can get it with the List collection in account endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "modified": "2021-09-12T10:12:42Z",
  • "description": "My collection of SKUs",
  • "subscribedApplicationsIds": [
    ],
  • "name": "My collection",
  • "modifiedBy": 48,
  • "createdBy": 134,
  • "applicationId": 1,
  • "campaignId": 7,
  • "payload": [
    ]
}

Update collection description

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Edit the description of the collection.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

collectionId
required
integer

The ID of the collection. You can get it with the List collection in account endpoint.

Request Body schema: application/json
description
string

A short description of the purpose of this collection.

Responses

Request samples

Content type
application/json
{
  • "description": "My collection of SKUs"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "modified": "2021-09-12T10:12:42Z",
  • "description": "My collection of SKUs",
  • "subscribedApplicationsIds": [
    ],
  • "name": "My collection",
  • "modifiedBy": 48,
  • "createdBy": 134,
  • "applicationId": 1,
  • "campaignId": 7,
  • "payload": [
    ]
}

Delete collection

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Delete the given collection.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

collectionId
required
integer

The ID of the collection. You can get it with the List collection in account endpoint.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ],
  • "StatusCode": 0
}

Import data in existing collection

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Upload a CSV file containing the collection of string values that should be attached as payload for collection. The file should be sent as multipart data.

The import replaces the initial content of the collection.

The CSV file must only contain the following column:

  • item: the values in your collection.

A collection is limited to 500,000 items.

Example:

item
Addidas
Nike
Asics

Note: Before sending a request to this endpoint, ensure the data in the CSV to import is different from the data currently stored in the collection.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

collectionId
required
integer

The ID of the collection. You can get it with the List collection in account endpoint.

Request Body schema: multipart/form-data
upFile
string <csv>

The file with the information about the data that should be imported.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "userId": 0,
  • "entity": "AttributeAllowedList",
  • "amount": 10
}

Import data in existing account-level collection

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Upload a CSV file containing the collection of string values that should be attached as payload for collection. The file should be sent as multipart data.

The import replaces the initial content of the collection.

The CSV file must only contain the following column:

  • item: the values in your collection.

A collection is limited to 500,000 items.

Example:

item
Addidas
Nike
Asics

Note: Before sending a request to this endpoint, ensure the data in the CSV to import is different from the data currently stored in the collection.

Authorizations:
manager_authmanagement_key
path Parameters
collectionId
required
integer

The ID of the collection. You can get it with the List collection in account endpoint.

Request Body schema: multipart/form-data
upFile
string <csv>

The file with the information about the data that should be imported.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "userId": 0,
  • "entity": "AttributeAllowedList",
  • "amount": 10
}

Export account-level collection's items

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Download a CSV file containing items from an account-level collection.

Authorizations:
manager_authmanagement_key
path Parameters
collectionId
required
integer

The ID of the collection. You can get it with the List collection in account endpoint.

Responses

Response samples

Content type
application/csv
item
SKU1
SKU2
SKU3

Export a collection's items

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Download a CSV file containing a collection's items.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

collectionId
required
integer

The ID of the collection. You can get it with the List collection in account endpoint.

Responses

Response samples

Content type
application/csv
item
SKU1
SKU2
SKU3

Coupons

Coupons are unique codes belonging to a particular campaign. They don't define any behavior on their own, instead the campaign ruleset can include rules that validate coupons and carry out particular effects.

Create coupons for multiple recipients

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Create coupons according to some pattern for up to 1000 recipients.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

query Parameters
silent
string
Default: "yes"

Possible values: yes or no.

  • yes: Increases the perfomance of the API call by returning a 204 response.
  • no: Returns a 200 response that contains the updated customer profiles.
Request Body schema: application/json
recipientsIntegrationIds
required
Array of strings [ 1 .. 1000 ] items

The integration IDs for recipients.

usageLimit
required
integer [ 0 .. 999999 ]

The number of times the coupon code can be redeemed. 0 means unlimited redemptions but any campaign usage limits will still apply.

discountLimit
number [ 0 .. 999999 ]

The amount of discounts that can be given with this coupon code.

reservationLimit
integer [ 0 .. 999999 ]

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

startDate
string <date-time> >= 0

Timestamp at which point the coupon becomes valid.

expiryDate
string <date-time> >= 0

Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.

object

Arbitrary properties associated with this item.

validCharacters
Array of strings

List of characters used to generate the random parts of a code. By default, the list of characters is equivalent to the [A-Z, 0-9] regular expression.

couponPattern
string [ 3 .. 100 ] characters

The pattern used to generate coupon codes. The character # is a placeholder and is replaced by a random character from the validCharacters set.

Responses

Request samples

Content type
application/json
{
  • "usageLimit": 100,
  • "discountLimit": 30,
  • "reservationLimit": 45,
  • "startDate": "2019-08-24T14:15:22Z",
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "attributes": { },
  • "recipientsIntegrationIds": [
    ],
  • "validCharacters": [
    ],
  • "couponPattern": "string"
}

Response samples

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

Create coupons asynchronously

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Create any number of coupons from 20,001 to 5,000,000.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

Request Body schema: application/json
numberOfCoupons
required
integer [ 1 .. 5000000 ]

The number of new coupon codes to generate for the campaign.

usageLimit
required
integer [ 0 .. 999999 ]

The number of times the coupon code can be redeemed. 0 means unlimited redemptions but any campaign usage limits will still apply.

required
object

Arbitrary properties associated with coupons.

discountLimit
number [ 0 .. 999999 ]

The amount of discounts that can be given with this coupon code.

reservationLimit
integer [ 0 .. 999999 ]

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

startDate
string <date-time> >= 0

Timestamp at which point the coupon becomes valid.

expiryDate
string <date-time> >= 0

Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.

object

Responses

Request samples

Content type
application/json
{
  • "usageLimit": 100,
  • "discountLimit": 30,
  • "reservationLimit": 45,
  • "startDate": "2019-08-24T14:15:22Z",
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "numberOfCoupons": 200000,
  • "couponSettings": {
    },
  • "attributes": { }
}

Response samples

Content type
application/json
{
  • "batchId": "tqyrgahe"
}

Create coupons

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Create coupons according to some pattern. Up to 20.000 coupons can be created without a unique prefix. When a unique prefix is provided, up to 200.000 coupons can be created.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

query Parameters
silent
string
Default: "yes"

Possible values: yes or no.

  • yes: Increases the perfomance of the API call by returning a 204 response.
  • no: Returns a 200 response that contains the updated customer profiles.
Request Body schema: application/json
numberOfCoupons
required
integer

The number of new coupon codes to generate for the campaign. Must be at least 1.

usageLimit
required
integer [ 0 .. 999999 ]

The number of times the coupon code can be redeemed. 0 means unlimited redemptions but any campaign usage limits will still apply.

discountLimit
number [ 0 .. 999999 ]

The amount of discounts that can be given with this coupon code.

reservationLimit
integer [ 0 .. 999999 ]

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

startDate
string <date-time> >= 0

Timestamp at which point the coupon becomes valid.

expiryDate
string <date-time> >= 0

Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.

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.

uniquePrefix
string

DEPRECATED To create more than 20,000 coupons in one request, use Create coupons asynchronously endpoint.

object

Arbitrary properties associated with this item.

recipientIntegrationId
string <= 1000 characters

The integration ID for this coupon's beneficiary's profile.

validCharacters
Array of strings

List of characters used to generate the random parts of a code. By default, the list of characters is equivalent to the [A-Z, 0-9] regular expression.

couponPattern
string [ 3 .. 100 ] characters

The pattern used to generate coupon codes. The character # is a placeholder and is replaced by a random character from the validCharacters set.

isReservationMandatory
boolean
Default: true

Whether the reservation effect actually created a new reservation.

Responses

Request samples

Content type
application/json
{
  • "usageLimit": 100,
  • "discountLimit": 30,
  • "reservationLimit": 45,
  • "startDate": "2019-08-24T14:15:22Z",
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "limits": [
    ],
  • "numberOfCoupons": 1,
  • "uniquePrefix": "string",
  • "attributes": { },
  • "recipientIntegrationId": "URNGV8294NV",
  • "validCharacters": [
    ],
  • "couponPattern": "SUMMER-#####",
  • "isReservationMandatory": false
}

Response samples

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

Update coupons

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Update all coupons of an campaign, or a specific batch of coupons. You can find the batchId in the Coupons view of your Application in the Campaign Manager or by using List coupons.

Important:

  • Only send sequential requests to this endpoint.
  • Requests to this endpoint timeout after 30 minutes. If you hit a timeout, reach out to our support team.

To update a specific coupon, use Update coupon.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

Request Body schema: application/json
usageLimit
integer [ 0 .. 999999 ]

The number of times the coupon code can be redeemed. 0 means unlimited redemptions but any campaign usage limits will still apply.

discountLimit
number [ 0 .. 999999 ]

The amount of discounts that can be given with this coupon code.

reservationLimit
integer [ 0 .. 999999 ]

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

startDate
string <date-time> >= 0

Timestamp at which point the coupon becomes valid.

expiryDate
string <date-time> >= 0

Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.

object

Arbitrary properties associated with this item.

batchID
string

The id of the batch the coupon belongs to.

Responses

Request samples

Content type
application/json
{
  • "usageLimit": 100,
  • "discountLimit": 30,
  • "reservationLimit": 45,
  • "startDate": "2019-08-24T14:15:22Z",
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "attributes": { },
  • "batchID": "string"
}

Delete coupons

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Deletes all the coupons matching the specified criteria.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

query Parameters
value
string

Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.

createdBefore
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

createdAfter
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

startsAfter
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

startsBefore
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

expiresAfter
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

expiresBefore
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

valid
string
Enum: "expired" "validNow" "validFuture"
  • expired: Matches coupons in which the expiry date is set and in the past.
  • validNow: Matches coupons in which start date is null or in the past and expiry date is null or in the future.
  • validFuture: Matches coupons in which start date is set and in the future.
batchId
string

Filter results by batches of coupons

usable
string
Enum: "true" "false"
  • true: only coupons where usageCounter < usageLimit will be returned.
  • false: only coupons where usageCounter >= usageLimit will be returned.
referralId
integer

Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.

recipientIntegrationId
string

Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field.

exactMatch
boolean
Default: false

Filter results to an exact case-insensitive matching against the coupon code

Responses

List coupons

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

List all the coupons matching the specified criteria.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

value
string

Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.

createdBefore
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

createdAfter
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

valid
string
Enum: "expired" "validNow" "validFuture"

Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiry date is set and in the past. The second matches coupons in which start date is null or in the past and expiry date is null or in the future, the third matches coupons in which start date is set and in the future.

usable
string
Enum: "true" "false"

Either "true" or "false". If "true", only coupons where usageCounter < usageLimit will be returned, "false" will return only coupons where usageCounter >= usageLimit.

referralId
integer

Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.

recipientIntegrationId
string

Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field

batchId
string

Filter results by batches of coupons

exactMatch
boolean
Default: false

Filter results to an exact case-insensitive matching against the coupon code

Responses

Response samples

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

Update coupon

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Update the specified coupon.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

couponId
required
string

The ID of the coupon code to update

Request Body schema: application/json
usageLimit
integer [ 0 .. 999999 ]

The number of times the coupon code can be redeemed. 0 means unlimited redemptions but any campaign usage limits will still apply.

discountLimit
number [ 0 .. 999999 ]

The amount of discounts that can be given with this coupon code.

reservationLimit
integer [ 0 .. 999999 ]

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

startDate
string <date-time> >= 0

Timestamp at which point the coupon becomes valid.

expiryDate
string <date-time> >= 0

Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.

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.

recipientIntegrationId
string <= 1000 characters

The integration ID for this coupon's beneficiary's profile.

object

Arbitrary properties associated with this item.

isReservationMandatory
boolean
Default: true

Whether the reservation effect actually created a new reservation.

Responses

Request samples

Content type
application/json
{
  • "usageLimit": 100,
  • "discountLimit": 30,
  • "reservationLimit": 45,
  • "startDate": "2019-08-24T14:15:22Z",
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "limits": [
    ],
  • "recipientIntegrationId": "string",
  • "attributes": { },
  • "isReservationMandatory": false
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "campaignId": 211,
  • "value": "XMAS-20-2021",
  • "usageLimit": 100,
  • "discountLimit": 30,
  • "reservationLimit": 45,
  • "startDate": "2019-08-24T14:15:22Z",
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "limits": [
    ],
  • "usageCounter": 10,
  • "discountCounter": 0,
  • "discountRemainder": 0,
  • "reservationCounter": 0,
  • "attributes": { },
  • "referralId": 326632952,
  • "recipientIntegrationId": "URNGV8294NV",
  • "importId": 0,
  • "reservation": false,
  • "batchId": "32535-43255",
  • "isReservationMandatory": false
}

Delete coupon

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Delete the specified coupon.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

couponId
required
string

The ID of the coupon code to update

Responses

List coupons that match the given attributes in campaign (without total count)

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

List the coupons whose attributes match the query criteria in the given campaign.

The match is successful if all the attributes of the request are found in a coupon, even if the coupon has more attributes that are not present on the request.

Note: The total count is not included in the response.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

value
string

Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.

createdBefore
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

createdAfter
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

valid
string
Enum: "expired" "validNow" "validFuture"

Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiry date is set and in the past. The second matches coupons in which start date is null or in the past and expiry date is null or in the future, the third matches coupons in which start date is set and in the future.

usable
string
Enum: "true" "false"

Either "true" or "false". If "true", only coupons where usageCounter < usageLimit will be returned, "false" will return only coupons where usageCounter >= usageLimit.

referralId
integer

Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.

recipientIntegrationId
string

Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field

exactMatch
boolean
Default: false

Filter results to an exact case-insensitive matching against the coupon code

batchId
string

Filter results by batches of coupons

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "my_attribute_1": "some value",
  • "my_attribute_2": "some other value",
  • "my_attribute_3": "some other value"
}

Response samples

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

List coupons that match the given attributes (without total count)

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

List the coupons whose attributes match the query criteria in all active campaigns of the given Application.

The match is successful if all the attributes of the request are found in a coupon, even if the coupon has more attributes that are not present on the request.

Note: The total count is not included in the response.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

value
string

Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.

createdBefore
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

createdAfter
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

valid
string
Enum: "expired" "validNow" "validFuture"

Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiry date is set and in the past. The second matches coupons in which start date is null or in the past and expiry date is null or in the future, the third matches coupons in which start date is set and in the future.

usable
string
Enum: "true" "false"

Either "true" or "false". If "true", only coupons where usageCounter < usageLimit will be returned, "false" will return only coupons where usageCounter >= usageLimit.

referralId
integer

Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.

recipientIntegrationId
string

Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field

batchId
string

Filter results by batches of coupons

exactMatch
boolean
Default: false

Filter results to an exact case-insensitive matching against the coupon code

campaignState
string
Enum: "enabled" "disabled" "archived" "draft" "scheduled" "running" "expired"

Filter results by the state of the campaign.

  • enabled: Campaigns that are scheduled, running (activated), or expired.
  • running: Campaigns that are running (activated).
  • disabled: Campaigns that are disabled.
  • expired: Campaigns that are expired.
  • archived: Campaigns that are archived.
  • draft: Campaigns that are drafts.
Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "my_attribute_1": "some value",
  • "my_attribute_2": "some other value",
  • "my_attribute_3": "some other value"
}

Response samples

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

Import coupons

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Upload a CSV file containing the coupons that should be created. The file should be sent as multipart data.

The CSV file can contain the following columns:

  • value (required): The coupon code.
  • expirydate: The end date in RFC3339 of the code redemption period.
  • startdate: The start date in RFC3339 of the code redemption period.
  • recipientintegrationid: The integration ID of the customer who receives the coupon. Only the customer with this integration ID can redeem the corresponding coupon code. Learn about coupon reservation.
  • limitval: The maximum amount of redemptions of this code. For unlimited redemptions, use 0. Defaults to 1 when not provided.
  • attributes: A json object describing custom referral attribute names and their values. Double the double-quotes in the object.
  • discountlimit: The amount of discounts that can be given with this coupon code. For example, if you created a custom attribute called category associated to the coupon entity, set it with "{""category"": ""10_off""}".

Important: Do not leave empty columns in the file.

You can use the timezone of your choice. It is converted to UTC internally by Talon.One.

Example:

"value","expirydate","startdate","recipientintegrationid","limitval","attributes","discountlimit"
COUP1,2018-07-01T04:00:00Z,2018-05-01T04:00:00Z,cust123,1,"{""Category"": ""10_off""}",2.4

Once imported, you can find the batchId in the Campaign Manager or by using List coupons.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

campaignId
required
integer

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

Request Body schema: multipart/form-data
upFile
string <csv>

The file with the information about the data that should be imported.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "userId": 0,
  • "entity": "AttributeAllowedList",
  • "amount": 10
}

Export coupons

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Download a CSV file containing the coupons that match the given properties.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

query Parameters
campaignId
number

Filter results by campaign.

sort
string

The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with - to sort in descending order.

value
string

Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.

createdBefore
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

createdAfter
string <date-time>

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any timezone. Talon.One will convert to UTC internally.

valid
string
Enum: "expired" "validNow" "validFuture"

Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiry date is set and in the past. The second matches coupons in which start date is null or in the past and expiry date is null or in the future, the third matches coupons in which start date is set and in the future.

usable
string
Enum: "true" "false"

Either "true" or "false". If "true", only coupons where usageCounter < usageLimit will be returned, "false" will return only coupons where usageCounter >= usageLimit.

referralId
integer

Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.

recipientIntegrationId
string

Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field

batchId
string

Filter results by batches of coupons

exactMatch
boolean
Default: false

Filter results to an exact case-insensitive matching against the coupon code

dateFormat
string
Enum: "excel" "ISO8601"

Determines the format of dates in the export document.

campaignState
string
Enum: "enabled" "disabled" "archived" "draft" "scheduled" "running" "expired"

Filter results by the state of the campaign.

  • enabled: Campaigns that are scheduled, running (activated), or expired.
  • running: Campaigns that are running (activated).
  • disabled: Campaigns that are disabled.
  • expired: Campaigns that are expired.
  • archived: Campaigns that are archived.
  • draft: Campaigns that are drafts.

Responses

Response samples

Content type
application/csv
id,created,campaignid,value,expirydate,startdate,attributes,applicationid,deleted,deleted_changelogid,accountid,referralid,recipientintegrationid,importid,batchid,reservation,limits,limitval,counter,discount_counter,discount_limitval
20191301,2022-04-26T11:02:38Z,3882,COUP1,2022-04-27T10:56:47Z,2022-04-26T10:56:47Z,"{""test"": ""premium""}",270,,0,1,,cust123,671,axghjfdy,,"[]",1,0,0,1.5

Customer data

Represents the data of a customer, including sessions and events used for reporting and debugging in the Campaign Manager.

List application's customers

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

List all the customers of the specified application.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

query Parameters
integrationId
string

Filter results performing an exact matching against the profile integration identifier.

pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

withTotalResultSize
boolean

When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.

  • When true: hasMore is true when there is a next page. totalResultSize is always zero.
  • When false: hasMore is always false. totalResultSize contains the total number of results for this query.

Responses

Response samples

Content type
application/json
{
  • "totalResultSize": 0,
  • "hasMore": true,
  • "data": [
    ]
}

List application customers matching the given attributes

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Get a list of the application customers matching the provided criteria.

The match is successful if all the attributes of the request are found in a profile, even if the profile has more attributes that are not present on the request.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer

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

query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

withTotalResultSize
boolean

When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.

  • When true: hasMore is true when there is a next page. totalResultSize is always zero.
  • When false: hasMore is always false. totalResultSize contains the total number of results for this query.
Request Body schema: application/json
object

Properties to match against a customer profile. All provided attributes will be exactly matched against profile attributes.

integrationIDs
Array of strings
profileIDs
Array of integers

Responses

Request samples

Content type
application/json
{
  • "attributes": { },
  • "integrationIDs": [
    ],
  • "profileIDs": [
    ]
}

Response samples

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

List customer profiles matching the given attributes

Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Get a list of the customer profiles matching the provided criteria.

The match is successful if all the attributes of the request are found in a profile, even if the profile has more attributes that are not present on the request.

Authorizations:
manager_authmanagement_key
query Parameters
pageSize
integer [ 1 .. 1000 ]

The number of items in this response. When omitted, the maximum value of 1000 will be used.

skip
integer

Skips the given number of items when paging through large result sets.

sandbox
boolean
Default: false

Indicates whether you are pointing to a sandbox or Live customer.

Request Body schema: application/json
object

Properties to match against a customer profile. All provided attributes will be exactly matched against profile attributes.

integrationIDs
Array of strings
profileIDs
Array of integers

Responses

Request samples

Content type
application/json
{
  • "attributes": { },
  • "integrationIDs": [
    ],
  • "profileIDs": [
    ]
}

Response samples

Content type
application/json
{
  • "hasMore": true,
  • "data": [