Skip to main content
API docs by Redocly

Management API

Download OpenAPI specification:Download

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

For more background information about this API, see Management API overview

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. Sign in to the Campaign Manager and click Account > Tools > 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 ]
Default: 1000
Example: pageSize=1000

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

sort
string
Example: sort=name

The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with -.

Note: This parameter works only with numeric fields.

Responses

Response samples

Content type
application/json
{
  • "totalResultSize": 1,
  • "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
Example: 33

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,
  • "name": "John Doe",
  • "state": "invited",
  • "inviteToken": "Gy9b8w1irmQtEPo5RmbMmSPheL5h4",
  • "isAdmin": false,
  • "policy": {
    },
  • "roles": [
    ],
  • "authMethod": "basic_auth",
  • "applicationNotificationSubscriptions": null,
  • "lastSignedIn": "2021-09-12T10:12:42Z",
  • "lastAccessed": "2021-09-12T10:14:42Z",
  • "latestFeedTimestamp": "2020-06-01T00:00:00Z",
  • "additionalAttributes": null
}

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

Update the details of a specific user.

Authorizations:
manager_authmanagement_key
path Parameters
userId
required
integer
Example: 33

The ID of the user.

Request Body schema: application/json
required

body

name
string

Name of the user.

state
string
Enum: "deactivated" "active"

The state of the user.

  • deactivated: The user has been deactivated.
  • active: The user is active.

Note: Only admin users can update the state of another user.

isAdmin
boolean

Indicates whether the user is an admin.

policy
string

Indicates the access level of the user.

roles
Array of integers

A list of the IDs of the roles assigned to the user.

Note: To find the ID of a role, use the List roles endpoint.

applicationNotificationSubscriptions
object

Application notifications that the user is subscribed to.

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe",
  • "state": "deactivated",
  • "isAdmin": false,
  • "policy": {
    },
  • "roles": [
    ],
  • "applicationNotificationSubscriptions": { }
}

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,
  • "name": "John Doe",
  • "state": "invited",
  • "inviteToken": "Gy9b8w1irmQtEPo5RmbMmSPheL5h4",
  • "isAdmin": false,
  • "policy": {
    },
  • "roles": [
    ],
  • "authMethod": "basic_auth",
  • "applicationNotificationSubscriptions": null,
  • "lastSignedIn": "2021-09-12T10:12:42Z",
  • "lastAccessed": "2021-09-12T10:14:42Z",
  • "latestFeedTimestamp": "2020-06-01T00:00:00Z",
  • "additionalAttributes": null
}

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

Delete a specific user.

Authorizations:
manager_authmanagement_key
path Parameters
userId
required
integer
Example: 33

The ID of the user.

Responses

Validate Okta API ownership

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.

Validate the ownership of the API through a challenge-response mechanism.

This challenger endpoint is used by Okta to confirm that communication between Talon.One and Okta is correctly configured and accessible for provisioning and deprovisioning of Talon.One users, and that only Talon.One can receive and respond to events from Okta.

Authorizations:
manager_authmanagement_key

Responses

List SCIM users

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 paginated list of users that have been provisioned using the SCIM protocol with an identity provider, for example, Microsoft Entra ID.

Authorizations:
manager_authmanagement_key

Responses

Response samples

Content type
application/json
{
  • "Resources": [
    ],
  • "schemas": [
    ],
  • "totalResults": 1
}

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

Create a new Talon.One user using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
required

body

userName
required
string

Unique identifier of the user. This is usually an email address.

active
boolean

Status of the user.

displayName
string

Display name of the user.

object

The components of the user’s real name.

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "displayName": "John Doe",
  • "userName": "john.doe@example.com",
  • "name": {
    }
}

Response samples

Content type
application/json
{
  • "active": true,
  • "displayName": "John Doe",
  • "userName": "john.doe@example.com",
  • "name": {
    },
  • "id": 359
}

Get SCIM 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 data for a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.

Authorizations:
manager_authmanagement_key
path Parameters
userId
required
integer
Example: 33

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "displayName": "John Doe",
  • "userName": "john.doe@example.com",
  • "name": {
    },
  • "id": 359
}

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

Delete a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.

Authorizations:
manager_authmanagement_key
path Parameters
userId
required
integer
Example: 33

The ID of the user.

Responses

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

Update the details of a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.

This endpoint replaces all attributes of the specific user with the attributes provided in the request payload.

Authorizations:
manager_authmanagement_key
path Parameters
userId
required
integer
Example: 33

The ID of the user.

Request Body schema: application/json
required

body

userName
required
string

Unique identifier of the user. This is usually an email address.

active
boolean

Status of the user.

displayName
string

Display name of the user.

object

The components of the user’s real name.

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "displayName": "John Doe",
  • "userName": "john.doe@example.com",
  • "name": {
    }
}

Response samples

Content type
application/json
{
  • "active": true,
  • "displayName": "John Doe",
  • "userName": "john.doe@example.com",
  • "name": {
    },
  • "id": 359
}

Update SCIM user 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.

Update certain attributes of a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.

This endpoint allows for selective adding, removing, or replacing specific attributes while leaving other attributes unchanged.

Authorizations:
manager_authmanagement_key
path Parameters
userId
required
integer
Example: 33

The ID of the user.

Request Body schema: application/json
required

body

required
Array of objects
schemas
Array of strings

SCIM schema for the given resource.

Responses

Request samples

Content type
application/json
{
  • "Operations": [
    ],
  • "schemas": [
    ]
}

Response samples

Content type
application/json
{
  • "active": true,
  • "displayName": "John Doe",
  • "userName": "john.doe@example.com",
  • "name": {
    },
  • "id": 359
}

List supported SCIM resource types

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 list of resource types supported by the SCIM provisioning protocol.

Resource types define the various kinds of resources that can be managed via the SCIM API, such as users, groups, or custom-defined resources.

Authorizations:
manager_authmanagement_key

Responses

Response samples

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

Get SCIM service provider configuration

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 configuration settings of the SCIM service provider. It provides details about the features and capabilities supported by the SCIM API, such as the different operation settings.

Authorizations:
manager_authmanagement_key

Responses

Response samples

Content type
application/json
{
  • "bulk": {
    },
  • "changePassword": {
    },
  • "documentationUri": "example.com/scim/docs",
  • "filter": {
    },
  • "patch": {
    },
  • "schemas": [
    ],
  • "x-sort": {
    }
}

List supported SCIM schemas

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 list of schemas supported by the SCIM provisioning protocol.

Schemas define the structure and attributes of the different resources that can be managed via the SCIM API, such as users, groups, and any custom-defined resources.

Authorizations:
manager_authmanagement_key

Responses

Response samples

Content type
application/json
{
  • "Resources": [
    ],
  • "schemas": [
    ],
  • "totalResults": 0
}

Delete user by email address

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 a specific user by their email address.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
required

body

email
required
string <email>

The email address associated with the user profile.

Responses

Request samples

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

Enable user by email address

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.

Enable a disabled user by their email address.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
required

body

email
required
string <email>

The email address associated with the user profile.

Responses

Request samples

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

Disable user by email address

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.

Disable a specific user by their email address.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
required

body

email
required
string <email>

The email address associated with the user profile.

Responses

Request samples

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

Invite user from identity provider

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.

Invite a user from an external identity provider to Talon.One by sending an invitation to their email address.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
required

body

email
required
string <email>

Email address of the user.

name
string

Name of the user.

userGroups
Array of strings

List of user groups in the external identity provider.

If there are roles in Talon.One whose names match these user groups, those roles will be automatically assigned to the user upon invitation.

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe",
  • "userGroups": [
    ],
  • "email": "john.doe@example.com"
}

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

Create a new user in the account and send an invitation to their email address.

Note: The invitation token is valid for 24 hours after the email has been sent. You can resend an invitation to a user with the Resend invitation email endpoint.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
required

body

email
required
string <email>

Email address of the user.

name
string

Name of the user.

isAdmin
boolean

Indicates whether the user is an admin.

roles
Array of integers

A list of the IDs of the roles assigned to the user.

acl
string

Indicates the access level of the user.

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe",
  • "email": "john.doe@example.com",
  • "isAdmin": false,
  • "roles": [
    ],
  • "acl": "string"
}

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,
  • "name": "John Doe",
  • "state": "invited",
  • "inviteToken": "Gy9b8w1irmQtEPo5RmbMmSPheL5h4",
  • "isAdmin": false,
  • "policy": {
    },
  • "roles": [
    ],
  • "authMethod": "basic_auth",
  • "applicationNotificationSubscriptions": null,
  • "lastSignedIn": "2021-09-12T10:12:42Z",
  • "lastAccessed": "2021-09-12T10:14:42Z",
  • "latestFeedTimestamp": "2020-06-01T00:00:00Z",
  • "additionalAttributes": null
}

Resend invitation email

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.

Resend an email invitation to an existing user.

Note: The invitation token is valid for 24 hours after the email has been sent.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
required

body

email
required
string <email>

Email address of the user.

token
required
string

Invitation token of the user.

Responses

Request samples

Content type
application/json
{
  • "email": "john.doe@example.com",
  • "token": "Gy9b8w1irmQtEPo5RmbMmSPheL5h4"
}

Response samples

Content type
application/json
{
  • "email": "john.doe@example.com",
  • "token": "Gy9b8w1irmQtEPo5RmbMmSPheL5h4"
}

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.

Note: The password recovery link expires 30 minutes after this endpoint is triggered.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
required

body

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
required

body

password
required
string

The new password for your account.

resetToken
required
string non-empty

Responses

Request samples

Content type
application/json
{
  • "password": "Admin&12943!7",
  • "resetToken": "Z2VgacVNkexLKBUIzsRDDZSGxnIkC53y"
}

Response samples

Content type
application/json
{
  • "password": "Admin&12943!7",
  • "resetToken": "Z2VgacVNkexLKBUIzsRDDZSGxnIkC53y"
}

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

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

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,
  • "lastUpdatedAt": "2022-12-12T12:12:12Z"
}

Achievements

Achievements allow you to reward a customer profile for performing a number of specific actions or reaching a transactional milestone within a defined period.

For example, you can use achievements to award your customers when they purchase five cups of coffee in one week or when they purchase items worth $3000 in three months.

Create achievement

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 new achievement in a specific campaign.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer
Example: 42

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

campaignId
required
integer
Example: 18

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

Request Body schema: application/json
required

body

name
required
string [ 1 .. 1000 ] characters ^[a-zA-Z]\w+$

The internal name of the achievement used in API requests.

Note: The name should start with a letter. This cannot be changed after the achievement has been created.

title
required
string

The display name for the achievement in the Campaign Manager.

description
required
string <string>

A description of the achievement.

target
required
number

The required number of actions or the transactional milestone to complete the achievement.

period
required
string

The relative duration after which the achievement ends and resets for a particular customer profile.

Note: The period does not start when the achievement is created.

The period is a positive real number followed by one letter indicating the time unit.

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

Available units:

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

You can also round certain units down to the beginning of period and up to the end of period.:

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

Note: You can either use the round down and round up option or set an absolute period.

object

The absolute duration after which the achievement ends and resets for a particular customer profile.

Note: The duration follows the time zone of the Application this achievement belongs to.

recurrencePolicy
string
Enum: "no_recurrence" "on_expiration"

The policy that determines if and how the achievement recurs.

  • no_recurrence: The achievement can be completed only once.
  • on_expiration: The achievement resets after it expires and becomes available again.
activationPolicy
string
Enum: "user_action" "fixed_schedule"

The policy that determines how the achievement starts, ends, or resets.

  • user_action: The achievement ends or resets relative to when the customer started the achievement.
  • fixed_schedule: The achievement starts, ends, or resets for all customers following a fixed schedule.
fixedStartDate
string <date-time>

The achievement's start date when activationPolicy is set to fixed_schedule.

Note: It must be an RFC3339 timestamp string.

endDate
string <date-time>

The achievement's end date. If defined, customers cannot participate in the achievement after this date.

Note: It must be an RFC3339 timestamp string.

Responses

Request samples

Content type
application/json
{
  • "name": "Order50Discount",
  • "title": "50% off on 50th purchase.",
  • "description": "50% off for every 50th purchase in a year.",
  • "target": 50,
  • "period": "1Y",
  • "periodEndOverride": {
    },
  • "recurrencePolicy": "no_recurrence",
  • "activationPolicy": "fixed_schedule",
  • "fixedStartDate": "2024-01-15T15:04:05Z07:00",
  • "endDate": "2024-02-15T15:04:05Z07:00"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "name": "Order50Discount",
  • "title": "50% off on 50th purchase.",
  • "description": "50% off for every 50th purchase in a year.",
  • "target": 50,
  • "period": "1Y",
  • "periodEndOverride": {
    },
  • "recurrencePolicy": "no_recurrence",
  • "activationPolicy": "fixed_schedule",
  • "fixedStartDate": "2024-01-15T15:04:05Z07:00",
  • "endDate": "2024-02-15T15:04:05Z07:00",
  • "campaignId": 1,
  • "userId": 1234,
  • "createdBy": "John Doe",
  • "hasProgress": true
}

List achievements

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 achievements for a specific campaign.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer
Example: 42

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

campaignId
required
integer
Example: 18

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

query Parameters
pageSize
integer [ 1 .. 50 ]
Default: 50
Example: pageSize=50

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

title
string
Example: title=achievement1

Filter by the display name for the achievement in the campaign manager.

Note: If no title is provided, all the achievements from the campaign are returned.

Responses

Response samples

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

Get achievement

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 details of a specific achievement.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer
Example: 42

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

campaignId
required
integer
Example: 18

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

achievementId
required
integer
Example: 45

The ID of the achievement. You can get this ID with the List achievement endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "name": "Order50Discount",
  • "title": "50% off on 50th purchase.",
  • "description": "50% off for every 50th purchase in a year.",
  • "target": 50,
  • "period": "1Y",
  • "periodEndOverride": {
    },
  • "recurrencePolicy": "no_recurrence",
  • "activationPolicy": "fixed_schedule",
  • "fixedStartDate": "2024-01-15T15:04:05Z07:00",
  • "endDate": "2024-02-15T15:04:05Z07:00",
  • "campaignId": 1,
  • "userId": 1234,
  • "createdBy": "John Doe",
  • "hasProgress": true
}

Update achievement

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 details of a specific achievement.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer
Example: 42

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

campaignId
required
integer
Example: 18

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

achievementId
required
integer
Example: 45

The ID of the achievement. You can get this ID with the List achievement endpoint.

Request Body schema: application/json
required

body

name
string [ 1 .. 1000 ] characters ^[a-zA-Z]\w+$

The internal name of the achievement used in API requests.

title
string

The display name for the achievement in the Campaign Manager.

description
string <string>

A description of the achievement.

target
number

The required number of actions or the transactional milestone to complete the achievement.

period
string

The relative duration after which the achievement ends and resets for a particular customer profile.

object

The absolute duration after which the achievement ends and resets for a particular customer profile.

Note: The duration follows the time zone of the Application this achievement belongs to.

recurrencePolicy
string
Enum: "no_recurrence" "on_expiration"

The policy that determines if and how the achievement recurs.

  • no_recurrence: The achievement can be completed only once.
  • on_expiration: The achievement resets after it expires and becomes available again.
activationPolicy
string
Enum: "user_action" "fixed_schedule"

The policy that determines how the achievement starts, ends, or resets.

  • user_action: The achievement ends or resets relative to when the customer started the achievement.
  • fixed_schedule: The achievement starts, ends, or resets for all customers following a fixed schedule.
fixedStartDate
string <date-time>

The achievement's start date when activationPolicy is set to fixed_schedule.

Note: It must be an RFC3339 timestamp string.

endDate
string <date-time>

The achievement's end date. If defined, customers cannot participate in the achievement after this date.

Note: It must be an RFC3339 timestamp string.

Responses

Request samples

Content type
application/json
{
  • "name": "Order50Discount",
  • "title": "50% off on 50th purchase.",
  • "description": "50% off for every 50th purchase in a year.",
  • "target": 50,
  • "period": "1Y",
  • "periodEndOverride": {
    },
  • "recurrencePolicy": "no_recurrence",
  • "activationPolicy": "fixed_schedule",
  • "fixedStartDate": "2024-01-15T15:04:05Z07:00",
  • "endDate": "2024-02-15T15:04:05Z07:00"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "name": "Order50Discount",
  • "title": "50% off on 50th purchase.",
  • "description": "50% off for every 50th purchase in a year.",
  • "target": 50,
  • "period": "1Y",
  • "periodEndOverride": {
    },
  • "recurrencePolicy": "no_recurrence",
  • "activationPolicy": "fixed_schedule",
  • "fixedStartDate": "2024-01-15T15:04:05Z07:00",
  • "endDate": "2024-02-15T15:04:05Z07:00",
  • "campaignId": 1,
  • "userId": 1234,
  • "createdBy": "John Doe",
  • "hasProgress": true
}

Delete achievement

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

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer
Example: 42

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

campaignId
required
integer
Example: 18

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

achievementId
required
integer
Example: 45

The ID of the achievement. You can get this ID with the List achievement endpoint.

Responses

Response samples

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

Export achievement customer data

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 list of all the customers who have participated in and are currently participating in the given achievement.

The CSV file contains the following columns:

  • profileIntegrationID: The integration ID of the customer profile participating in the achievement.
  • title: The display name of the achievement in the Campaign Manager.
  • target: The required number of actions or the transactional milestone to complete the achievement.
  • progress: The current progress of the customer in the achievement.
  • status: The status of the achievement. Can be one of: ['inprogress', 'completed', 'expired'].
  • startDate: The date on which the customer profile started the achievement in RFC3339.
  • endDate: The date on which the achievement ends and resets for the customer profile in RFC3339.
  • completionDate: The date on which the customer profile completed the achievement in RFC3339.
Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer
Example: 42

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

campaignId
required
integer
Example: 18

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

achievementId
required
integer
Example: 45

The ID of the achievement. You can get this ID with the List achievement endpoint.

Responses

Response samples

Content type
application/csv
profileIntegrationID,title,target,progress,status,startDate,endDate,completionDate
user1231,CoffeeFree10Orders,10.00,5,inprogress,2023-12-10T11:42:25+01:00,2024-01-10T11:42:25+01:00,
user341,CoffeeFree10Orders,10.00,10,completed,2023-12-10T11:42:25+01:00,2024-01-10T11:42:25+01:00,2023-12-20T10:24:34+01:00

List customer achievements

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.

For the given customer profile, list all the achievements that match your filter criteria.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer
Example: 42

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

integrationId
required
string
Example: customer1

The identifier of the profile.

query Parameters
pageSize
integer [ 1 .. 50 ]
Default: 50
Example: pageSize=50

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

achievementId
integer
Example: achievementId=41

The ID of the achievement. You can get this ID with the List achievement endpoint.

title
string
Example: title=achievement1

Filter results by the title of an achievement.

Responses

Response samples

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

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
required

body

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

The internal name used in API requests.

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

  • 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": "shippingFee",
  • "title": "Shipping fee",
  • "description": "A shipping fee",
  • "subscribedApplicationsIds": [
    ],
  • "type": "session"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "name": "shippingFee",
  • "title": "Shipping fee",
  • "description": "A shipping fee",
  • "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 ]
Default: 1000
Example: pageSize=1000

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

sort
string
Example: sort=name

The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with -.

Note: This parameter works only with numeric fields.

Responses

Response samples

Content type
application/json
{
  • "totalResultSize": 1,
  • "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
Example: 2

The ID of the additional cost. You can find the ID the the Campaign Manager's URL when you display the details of the cost in Account > Tools > Additional costs.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "name": "shippingFee",
  • "title": "Shipping fee",
  • "description": "A shipping fee",
  • "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 cannot be changed is the name property (or API name in the Campaign Manager). This restriction is in place to prevent accidentally breaking live integrations.

Authorizations:
manager_authmanagement_key
path Parameters
additionalCostId
required
integer
Example: 2

The ID of the additional cost. You can find the ID the the Campaign Manager's URL when you display the details of the cost in Account > Tools > Additional costs.

Request Body schema: application/json
required

body

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

The internal name used in API requests.

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

  • 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": "shippingFee",
  • "title": "Shipping fee",
  • "description": "A shipping fee",
  • "subscribedApplicationsIds": [
    ],
  • "type": "session"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "name": "shippingFee",
  • "title": "Shipping fee",
  • "description": "A shipping fee",
  • "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.

Tip: If the exported CSV file is too large to view, you can split it into multiple files.

The generated file can contain the following columns:

  • applicationid: The ID of the Application.
  • campaignid: The ID of the campaign.
  • couponid: The ID of the coupon, when applicable to the effect.
  • created: The timestamp of the effect.
  • event_type: The name of the event. See the docs.
  • eventid: The internal ID of the effect.
  • name: The effect name. See the docs.
  • profileintegrationid: The ID of the customer profile, when applicable.
  • props: The properties of the effect.
  • ruleindex: The index of the rule.
  • rulesetid: The ID of the rule set.
  • sessionid: The internal ID of the session that triggered the effect.
  • profileid: The internal ID of the customer profile.
  • sessionintegrationid: The integration ID of the session.
  • total_revenue: The total revenue.
  • store_integration_id: The integration ID of the store. You choose this ID when you create a store.
Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer
Example: 42

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

query Parameters
campaignId
number
Example: campaignId=49

Filter results by campaign ID.

createdBefore
string <date-time>
Example: createdBefore=2024-05-29T15:04:05Z07:00

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

createdAfter
string <date-time>
Example: createdAfter=2024-05-29T15:04:05Z07:00

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

dateFormat
string
Enum: "excel" "ISO8601"
Example: dateFormat=excel

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,store_id,store_integration_id
2021-06-02T21:14:16Z,rejectCoupon,270,0,0,0,newsession1,,9168,0,95797,talon_session_created,265.00,"{""value"": ""XMAS20"", ""rejectionReason"": ""CouponNotFound""}",,115,STORE-001
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}",,116,STORE-002

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.

Tip: If the exported CSV file is too large to view, you can split it into multiple files.

  • id: The internal ID of the session.
  • firstsession: Whether this is a first session.
  • integrationid: The integration ID of the session.
  • applicationid: The ID of the Application.
  • profileid: The internal ID of the customer profile.
  • profileintegrationid: The integration ID of the customer profile.
  • created: The timestamp when the session was created.
  • state: The state of the session.
  • cartitems: The cart items in the session.
  • discounts: The discounts in the session.
  • total: The total value of cart items and additional costs in the session, before any discounts are applied.
  • attributes: The attributes set in the session.
  • closedat: Timestamp when the session was closed.
  • cancelledat: Timestamp when the session was cancelled.
  • referral: The referral code in the session.
  • identifiers: The identifiers in the session.
  • additional_costs: The additional costs in the session.
  • updated: Timestamp of the last session update.
  • store_integration_id: The integration ID of the store.
  • coupons: Coupon codes in the session.
Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer
Example: 42

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

query Parameters
createdBefore
string <date-time>
Example: createdBefore=2024-05-29T15:04:05Z07:00

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

createdAfter
string <date-time>
Example: createdAfter=2024-05-29T15:04:05Z07:00

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

profileIntegrationId
string
Example: profileIntegrationId=customer1

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

dateFormat
string
Enum: "excel" "ISO8601"
Example: dateFormat=excel

Determines the format of dates in the export document.

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

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,store_integration_id,coupons
12328,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,"STORE-001","[""SORRY5QMUJRWA""]"

Applications

Represents an Application in the Campaign Manager. An Application is 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.

See the docs.

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 ]
Default: 1000
Example: pageSize=1000

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

sort
string
Example: sort=name

The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with -.

Note: This parameter works only with numeric fields.

Responses

Response samples

Content type
application/json
{
  • "totalResultSize": 1,
  • "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
Example: 42

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": [
    ],
  • "defaultDiscountScope": "sessionTotal",
  • "enableCascadingDiscounts": true,
  • "enableFlattenedCartItems": true,
  • "attributesSettings": {
    },
  • "sandbox": true,
  • "enablePartialDiscounts": false,
  • "defaultDiscountAdditionalCostPerItemScope": "price",
  • "defaultEvaluationGroupId": 3,
  • "defaultCartItemFilterId": 3,
  • "enableCampaignStateManagement": false,
  • "loyaltyPrograms": [
    ]
}

Get Application health

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.

You can also find this information in the Campaign Manager. In your Application, click Settings > Integration API Keys. See the docs.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer
Example: 42

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 add data to Talon.One domain entities like campaigns, coupons, customers and so on.

These attributes can then be given values when creating/updating these entities, 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
required

body

entity
required
string
Enum: "Application" "Campaign" "CustomerProfile" "CustomerSession" "CartItem" "Coupon" "Event" "Giveaway" "Referral" "Store"

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": "Event",
  • "eventType": "pageViewed",
  • "name": "pageViewed",
  • "title": "Page view event",
  • "type": "string",
  • "description": "Event triggered when a customer displays a page.",
  • "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": "Event",
  • "eventType": "pageViewed",
  • "name": "pageViewed",
  • "title": "Page view event",
  • "type": "string",
  • "description": "Event triggered when a customer displays a page.",
  • "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.

Return all the custom attributes for the account.

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

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

sort
string
Example: sort=name

The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with -.

Note: This parameter works only with numeric fields.

entity
string
Example: entity=entity1

Returned attributes will be filtered by supplied entity.

Responses

Response samples

Content type
application/json
{
  • "totalResultSize": 1,
  • "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.

Retrieve the specified custom attribute.

Authorizations:
manager_authmanagement_key
path Parameters
attributeId
required
integer
Example: 31

The ID of the attribute. You can find the ID in the Campaign Manager's URL when you display the details of an attribute in Account > Tools > Attributes.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "entity": "Event",
  • "eventType": "pageViewed",
  • "name": "pageViewed",
  • "title": "Page view event",
  • "type": "string",
  • "description": "Event triggered when a customer displays a page.",
  • "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.

Update an existing custom attribute. Once created, the only property of a custom attribute that can be changed is the description.

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.

Authorizations:
manager_authmanagement_key
path Parameters
attributeId
required
integer
Example: 31

The ID of the attribute. You can find the ID in the Campaign Manager's URL when you display the details of an attribute in Account > Tools > Attributes.

Request Body schema: application/json
required

body

entity
required
string
Enum: "Application" "Campaign" "CustomerProfile" "CustomerSession" "CartItem" "Coupon" "Event" "Giveaway" "Referral" "Store"

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": "Event",
  • "eventType": "pageViewed",
  • "name": "pageViewed",
  • "title": "Page view event",
  • "type": "string",
  • "description": "Event triggered when a customer displays a page.",
  • "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": "Event",
  • "eventType": "pageViewed",
  • "name": "pageViewed",
  • "title": "Page view event",
  • "type": "string",
  • "description": "Event triggered when a customer displays a page.",
  • "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
Example: 31

The ID of the attribute. You can find the ID in the Campaign Manager's URL when you display the details of an attribute in Account > Tools > Attributes.

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

The file containing the data that is being imported.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "userId": 388,
  • "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 ]
Default: 1000
Example: pageSize=1000

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

sort
string
Example: sort=name

The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with -.

Note: This parameter works only with numeric fields.

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": 1,
  • "data": [
    ]
}

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

Get a list of audience IDs and their member count.

Authorizations:
manager_authmanagement_key
query Parameters
audienceIds
required
string
Example: audienceIds=audience1

The IDs of one or more audiences, separated by commas, by which to filter results.

sort
string
Example: sort=name

The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with -.

Note: This parameter works only with numeric fields.

Responses

Response samples

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

List audience members

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 paginated list of the customer profiles in a given audience.

A maximum of 1000 customer profiles per page is allowed.

Authorizations:
manager_authmanagement_key
path Parameters
audienceId
required
integer
Example: 10

The ID of the audience.

query Parameters
pageSize
integer [ 1 .. 1000 ]
Default: 1000
Example: pageSize=1000

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

sort
string
Example: sort=name

The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with -.

Note: This parameter works only with numeric fields.

profileQuery
string
Example: profileQuery=profile1

The filter to select a profile.

Responses

Response samples

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

Import audience members

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 integration IDs of the members you want to add to an audience.

The file should be sent as multipart data and should contain only the following column (required):

  • profileintegrationid: The integration ID of the customer profile.

The import replaces the previous list of audience members.

Note: We recommend limiting your file size to 500MB.

Example:

profileintegrationid
charles
alexa
Authorizations:
manager_authmanagement_key
path Parameters
audienceId
required
integer
Example: 10

The ID of the audience.

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

The file containing the data that is being imported.

Responses

Response samples

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

Export audience members

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 integration IDs of the members of an audience.

Tip: If the exported CSV file is too large to view, you can split it into multiple files.

The file contains the following column:

  • profileintegrationid: The integration ID of the customer profile.
Authorizations:
manager_authmanagement_key
path Parameters
audienceId
required
integer
Example: 10

The ID of the audience.

Responses

Response samples

Content type
application/csv
profileintegrationid
URNGV8294NV
BZGGC2454PA

Campaign access groups

Represents the campaign access groups you can create in your Applications to organize your campaigns based on the type of campaign or the team in charge.

See the docs.

List campaign access groups

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 campaign access groups in the current account.

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

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

sort
string
Example: sort=name

The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with -.

Note: This parameter works only with numeric fields.

Responses

Response samples

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

Get campaign access group

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 campaign access group specified by its ID.

Authorizations:
manager_authmanagement_key
path Parameters
campaignGroupId
required
integer
Example: 37

The ID of the campaign access group.

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": "Europe access group",
  • "description": "A group that gives access to all the campaigns for the Europe market.",
  • "subscribedApplicationsIds": [
    ],
  • "campaignIds": [
    ]
}

Campaign templates

Represents templates used to generate campaigns from.

List campaign templates

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 list of campaign templates.

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

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

sort
string
Example: sort=name

The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with -.

Note: This parameter works only with numeric fields.

state
string
Enum: "draft" "enabled" "disabled"
Example: state=draft

Filter results by the state of the campaign template.

name
string
Example: name=template1

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

tags
string
Example: tags=tag1

Filter results performing case-insensitive matching against the tags of the campaign template. 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.

userId
integer
Example: userId=34

Filter results by user ID.

Responses

Response samples

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

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

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

Request Body schema: application/json
required

body

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.

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

evaluationGroupId
integer

The ID of the campaign evaluation group the campaign belongs to.

linkedStoreIds
Array of integers

A list of store IDs that are linked to the campaign.

Note: Campaigns with linked store IDs will only be evaluated when there is a customer session update that references a linked store.

Responses

Request samples

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

Response samples

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

Campaigns

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

See the docs.

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

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

query Parameters
pageSize
integer [ 1 .. 1000 ]
Default: 1000
Example: pageSize=1000

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

sort
string
Example: sort=name

The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with -.

Note: This parameter works only with numeric fields.

campaignState
string
Enum: "enabled" "disabled" "archived" "scheduled" "running" "expired" "staged"
Example: campaignState=enabled

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.
name
string
Example: name=campaign1

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

tags
string
Example: tags=tag1

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>
Example: createdBefore=2024-05-29T15:04:05Z07:00

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

createdAfter
string <date-time>
Example: createdAfter=2024-05-29T15:04:05Z07:00

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

campaignGroupId
integer
Example: campaignGroupId=12

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

templateId
integer
Example: templateId=18

The ID of the campaign template this campaign was created from.

storeId
integer
Example: storeId=23

Filter results to campaigns linked to the specified store ID.

Responses

Response samples

Content type
application/json
{
  • "totalResultSize": 1,
  • "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
Example: 42

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

campaignId
required
integer
Example: 18

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

Responses

Response samples

Content type
application/json
{
  • "id": 4,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "applicationId": 322,
  • "userId": 388,
  • "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": 6,
  • "tags": [
    ],
  • "features": [
    ],
  • "couponSettings": {
    },
  • "referralSettings": {
    },
  • "limits": [
    ],
  • "campaignGroups": [
    ],
  • "type": "advanced",
  • "linkedStoreIds": [
    ],
  • "budgets": [
    ],
  • "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,
  • "frontendState": "running",
  • "storesImported": true,
  • "revisionFrontendState": "revised",
  • "activeRevisionId": 6,
  • "activeRevisionVersionId": 6,
  • "version": 6,
  • "currentRevisionId": 6,
  • "currentRevisionVersionId": 6,
  • "stageRevision": false
}

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.

Important: You cannot use this endpoint to update campaigns if campaign staging and revisions is enabled for your Application.

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer
Example: 42

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

campaignId
required
integer
Example: 18

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

Request Body schema: application/json
required

body

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

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.

attributes
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 this campaign belongs to.

evaluationGroupId
integer

The ID of the campaign evaluation group the campaign belongs to.

type
string
Default: "advanced"
Enum: "cartItem" "advanced"

The campaign type. Possible type values:

  • cartItem: Type of campaign that can apply effects only to cart items.
  • advanced: Type of campaign that can apply effects to customer sessions and cart items.
linkedStoreIds
Array of integers

A list of store IDs that you want to link to the campaign.

Note:

  • Campaigns with linked store IDs will only be evaluated when there is a customer session update that references a linked store.
  • If you linked stores to the campaign by uploading a CSV file, you cannot use this property and it should be empty.
  • Use of this property is limited to 50 stores. To link more than 50 stores, upload them via a CSV file.

Responses

Request samples

Content type
application/json
{
  • "name": "Summer promotions",
  • "description": "Campaign for all summer 2021 promotions",
  • "startTime": "2021-07-20T22:00:00Z",
  • "endTime": "2021-10-01T02:00:00Z",
  • "attributes": {
    },
  • "state": "disabled",
  • "activeRulesetId": 2,
  • "tags": [
    ],
  • "features": [
    ],
  • "couponSettings": {
    },
  • "referralSettings": {
    },
  • "limits": [
    ],
  • "campaignGroups": [
    ],
  • "evaluationGroupId": 2,
  • "type": "advanced",
  • "linkedStoreIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 4,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "applicationId": 322,
  • "userId": 388,
  • "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": 6,
  • "tags": [
    ],
  • "features": [
    ],
  • "couponSettings": {
    },
  • "referralSettings": {
    },
  • "limits": [
    ],
  • "campaignGroups": [
    ],
  • "type": "advanced",
  • "linkedStoreIds": [
    ],
  • "budgets": [
    ],
  • "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,
  • "frontendState": "running",
  • "storesImported": true,
  • "revisionFrontendState": "revised",
  • "activeRevisionId": 6,
  • "activeRevisionVersionId": 6,
  • "version": 6,
  • "currentRevisionId": 6,
  • "currentRevisionVersionId": 6,
  • "stageRevision": false
}

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

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

campaignId
required
integer
Example: 18

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

Authorizations:
manager_authmanagement_key
path Parameters
applicationId
required
integer
Example: 42

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

campaignId
required
integer
Example: 18

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

Request Body schema: application/json
required

body

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.

evaluationGroupId
integer

The ID of the campaign evaluation group the campaign belongs to.

Responses

Request samples

Content type
application/json
{
  • "name": "Copy of Summer promotions",
  • "applicationIds": [
    ],
  • "description": "Campaign for all summer 2021 promotions",
  • "startTime": "2021-06-01T09:00:27.993483Z",
  • "endTime": "2021-09-10T01:00:00.993483Z",
  • "tags": [
    ],
  • "evaluationGroupId": 2
}

Response samples

Content type
application/json
{
  • "totalResultSize": 1,
  • "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
Example: 42

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

query Parameters
pageSize
integer [ 1 .. 1000 ]
Default: 1000
Example: pageSize=1000

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

sort
string
Example: sort=name

The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with -.

Note: This parameter works only with numeric fields.

campaignState
string
Enum: "enabled" "disabled" "archived" "scheduled" "running" "expired" "staged"
Example: campaignState=enabled

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.
Request Body schema: application/json
required

body

attributes
required
object

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "totalResultSize": 1,
  • "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
Example: 42

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

campaignId
required
integer
Example: 18

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

query Parameters
pageSize
integer [ 1 .. 1000 ]
Default: 1000
Example: pageSize=1000

The number of items in the response.

skip
integer
Example: skip=100

The number of items to skip when paging through large result sets.

sort
string
Example: sort=name

The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with -.

Note: This parameter works only with numeric fields.

Responses

Response samples

Content type
application/json
{
  • "totalResultSize": 1,
  • "data": [