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

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.

property name*
additional property
any

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.

property name*
additional property
any

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 display this information from the Settings of an Application, in the Developer Settings menu. 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.

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.

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.

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

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

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

rulesetId
required
integer
Example: 29

The ID of the ruleset.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "userId": 388,
  • "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
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
rangeStart
required
string <date-time>
Example: rangeStart=2024-05-29T15:04:05Z07:00

Only return results from after this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
rangeEnd
required
string <date-time>
Example: rangeEnd=2024-05-29T15:04:05Z07:00

Only return results from before this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
granularity
string
Enum: "1 hour" "1 day" "1 week" "1 month" "1 year"
Example: granularity=1 hour

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

Responses

Response samples

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

Catalogs

Represents a catalog of cart items with unique SKUs. Cart item catalogs allow you to synchronize your entire inventory with Talon.One.

See the docs.

List items in a catalog

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 a paginated list of cart items in the given catalog.

Authorizations:
manager_authmanagement_key
path Parameters
catalogId
required
integer
Example: 30

The ID of the catalog. You can find the ID in the Campaign Manager in Account > Tools > Cart item catalogs.

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.

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.
sku
Array of strings
Example: sku=SKU-1,SKU-2

Filter results by one or more SKUs. Must be exact match.

productNames
Array of strings
Example: productNames=product1,product2

Filter results by one or more product names. Must be exact match.

Responses

Response samples

Content type
application/json
{
  • "hasMore": true,
  • "totalResultSize": 1,
  • "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 account-level collections in 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.

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
Example: name=collection1

Filter by collection name.

Responses

Response samples

Content type
application/json
{
  • "hasMore": true,
  • "totalResultSize": 1,
  • "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 an account-level collection.

Authorizations:
manager_authmanagement_key
Request Body schema: application/json
required

body

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

The ID of the collection. You can get it with the List collections 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 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 a given account-level collection and enable or disable the collection in the specified Applications.

Authorizations:
manager_authmanagement_key
path Parameters
collectionId
required
integer
Example: 22

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

Request Body schema: application/json
required

body

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

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 a given account-level collection.

Authorizations:
manager_authmanagement_key
path Parameters
collectionId
required
integer
Example: 22

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

Responses

Response samples

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

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 items from a given collection.

You can retrieve items from both account-level collections and campaign-level collections using this endpoint.

Authorizations:
manager_authmanagement_key
path Parameters
collectionId
required
integer
Example: 22

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

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.

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 campaign-level collections from all campaigns in a given 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.

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

Filter by collection name.

Responses

Response samples

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

List collections in 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.

List collections in a 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.

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

Filter by collection name.

Responses

Response samples

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

Create campaign-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 a campaign-level collection in a 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.

Request Body schema: application/json
required

body

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 campaign-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 campaign-level collection.

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.

collectionId
required
integer
Example: 44

The ID of the collection. You can get it with the List collections in Application 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 campaign-level collection's 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 a given campaign-level collection.

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.

collectionId
required
integer
Example: 44

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

Request Body schema: application/json
required

body

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 campaign-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 a given campaign-level collection.

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.

collectionId
required
integer
Example: 44

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

Responses

Response samples

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

Import data into 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
Example: 22

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

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
}

Import data into existing campaign-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
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.

collectionId
required
integer
Example: 44

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

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 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 a given account-level collection.

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

Authorizations:
manager_authmanagement_key
path Parameters
collectionId
required
integer
Example: 22

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

Responses

Response samples

Content type
application/csv
item
SKU1
SKU2
SKU3

Export campaign-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 a given campaign-level collection.

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

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.

collectionId
required
integer
Example: 44

The ID of the collection. You can get it with the List collections in Application 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.

See the docs.

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
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
silent
string
Default: "yes"
Example: silent=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
required

body

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 total discount value that the code can give. Typically used to represent a gift card value.

reservationLimit
integer [ 0 .. 999999 ]

The number 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

Expiration date of the coupon. Coupon never expires if this is omitted.

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

An indication of whether the code can be redeemed only if it has been reserved first.

implicitlyReserved
boolean

An indication of whether the coupon is implicitly reserved for all customers.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "totalResultSize": 1,
  • "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, or a specific batch of coupons in the given campaign. You can find the batchId in the Coupons view of your Application in the Campaign Manager, or you can use 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
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

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 total discount value that the code can give. Typically used to represent a gift card value.

reservationLimit
integer [ 0 .. 999999 ]

The number 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

Expiration date of the coupon. Coupon never expires if this is omitted.

object

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

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

batchID
string

The ID of the batch the coupon(s) belong to.

Responses

Request samples

Content type
application/json
{
  • "usageLimit": 100,
  • "discountLimit": 30,
  • "reservationLimit": 45,
  • "startDate": "2020-01-24T14:15:22Z",
  • "expiryDate": "2023-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
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
value
string
Example: value=SUMMER10

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

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon 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 coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.

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

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

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

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

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

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

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

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

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

Filter results by batches of coupons

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

Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code.

recipientIntegrationId
string
Example: recipientIntegrationId=customer1

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

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
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
silent
string
Default: "yes"
Example: silent=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
required

body

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 total discount value that the code can give. Typically used to represent a gift card value.

reservationLimit
integer [ 0 .. 999999 ]

The number 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

Expiration date of the coupon. Coupon never expires if this is omitted.

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": "2020-01-24T14:15:22Z",
  • "expiryDate": "2023-08-24T14:15:22Z",
  • "attributes": {
    },
  • "recipientsIntegrationIds": [
    ],
  • "validCharacters": [
    ],
  • "couponPattern": "SUMMER-#####"
}

Response samples

Content type
application/json
{
  • "totalResultSize": 1,
  • "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 up to 5,000,000 coupons asynchronously. You should typically use this enpdoint when you create at least 20,001 coupons. You receive an email when the creation is complete.

If you want to create less than 20,001 coupons, you can use the Create coupons endpoint.

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

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 total discount value that the code can give. Typically used to represent a gift card value.

reservationLimit
integer [ 0 .. 999999 ]

The number 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

Expiration date of the coupon. Coupon never expires if this is omitted.

object

Responses

Request samples

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

Response samples

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

Creates a coupon deletion job

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.

This endpoint handles creating a job to delete coupons asynchronously.

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

required
object
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 time zone setting. 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 time zone setting. 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 time zone setting. 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 time zone setting. Talon.One will convert to UTC internally.

valid
string
Enum: "expired" "validNow" "validFuture"
  • expired: Matches coupons in which the expiration date is set and in the past.
  • validNow: Matches coupons in which the start date is null or in the past and the expiration date is null or in the future.
  • validFuture: Matches coupons in which the start date is set and in the future.
usable
boolean
  • true: only coupons where usageCounter < usageLimit will be returned.
  • false: only coupons where usageCounter >= usageLimit will be returned.
  • This field cannot be used in conjunction with the usable query parameter.
redeemed
boolean
  • true: only coupons where usageCounter > 0 will be returned.
  • false: only coupons where usageCounter = 0 will be returned.

Note: This field cannot be used in conjunction with the usable query parameter.

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

value
string
Default: false

Filter results by the coupon code

batchId
string

Filter results by batches of coupons

referralId
integer

Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code.

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 time zone setting. 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 time zone setting. Talon.One will convert to UTC internally.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": 6
}

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

value
string
Example: value=SUMMER10

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

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon 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 coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.

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

Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiration date is set and in the past. The second matches coupons in which start date is null or in the past and expiration 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"
Example: usable=false

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

redeemed
string
Enum: "true" "false"
Example: redeemed=false
  • true: only coupons where usageCounter > 0 will be returned.
  • false: only coupons where usageCounter = 0 will be returned.
  • This field cannot be used in conjunction with the usable query parameter.
referralId
integer
Example: referralId=47

Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code.

recipientIntegrationId
string
Example: recipientIntegrationId=customer1

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

batchId
string
Example: batchId=nfinccze

Filter results by batches of coupons

exactMatch
boolean
Default: false

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

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

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

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

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

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

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

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

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

valuesOnly
boolean
Default: false

Filter results to only return the coupon codes (value column) without the associated coupon data.

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.

Important

With this PUT endpoint alone, if you do not explicitly set a value for the startDate, expiryDate, and recipientIntegrationId properties in your request, it is automatically set to null.

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.

couponId
required
string
Example: 1194

The internal ID of the coupon code. You can find this value in the id property from the List coupons endpoint response.

Request Body schema: application/json
required

body

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 total discount value that the code can give. Typically used to represent a gift card value.

reservationLimit
integer [ 0 .. 999999 ]

The number 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

Expiration date of the coupon. Coupon never expires if this is omitted.

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

An indication of whether the code can be redeemed only if it has been reserved first.

implicitlyReserved
boolean

An indication of whether the coupon is implicitly reserved for all customers.

Responses

Request samples

Content type
application/json
{
  • "usageLimit": 100,
  • "discountLimit": 30,
  • "reservationLimit": 45,
  • "startDate": "2020-01-24T14:15:22Z",
  • "expiryDate": "2023-08-24T14:15:22Z",
  • "limits": [
    ],
  • "recipientIntegrationId": "URNGV8294NV",
  • "attributes": { },
  • "isReservationMandatory": false,
  • "implicitlyReserved": 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": "2020-01-24T14:15:22Z",
  • "expiryDate": "2023-08-24T14:15:22Z",
  • "limits": [
    ],
  • "usageCounter": 10,
  • "discountCounter": 10,
  • "discountRemainder": 5,
  • "reservationCounter": 1,
  • "attributes": { },
  • "referralId": 326632952,
  • "recipientIntegrationId": "URNGV8294NV",
  • "importId": 4,
  • "reservation": false,
  • "batchId": "32535-43255",
  • "isReservationMandatory": false,
  • "implicitlyReserved": 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
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.

couponId
required
string
Example: 1194

The internal ID of the coupon code. You can find this value in the id property from the List coupons endpoint response.

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

value
string
Example: value=SUMMER10

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

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon 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 coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.

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

Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiration date is set and in the past. The second matches coupons in which start date is null or in the past and expiration 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"
Example: usable=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
Example: referralId=47

Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code.

recipientIntegrationId
string
Example: recipientIntegrationId=customer1

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
Example: batchId=nfinccze

Filter results by batches of coupons

Request Body schema: application/json
required

body

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

value
string
Example: value=SUMMER10

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

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon 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 coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.

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

Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiration date is set and in the past. The second matches coupons in which start date is null or in the past and expiration 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"
Example: usable=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
Example: referralId=47

Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code.

recipientIntegrationId
string
Example: recipientIntegrationId=customer1

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

batchId
string
Example: batchId=nfinccze

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

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 contains 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 recipient of the coupon. Only the customer with this integration ID can redeem this code. Available only for personal codes.

  • limitval: The maximum number of redemptions of this code. For unlimited redemptions, use 0. Defaults to 1 when not provided.

  • discountlimit: The total discount value that the code can give. This is typically used to represent a gift card value.

  • attributes: A JSON object describing custom coupon attribute names and their values, enclosed with double quotation marks.

    For example, if you created a custom attribute called category associated with the coupon entity, the object in the CSV file, when opened in a text editor, must be: "{"category": "10_off"}".

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

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

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
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
skipDuplicates
boolean

An indicator of whether to skip duplicate coupon values instead of causing an error. Duplicate values are ignored when skipDuplicates=true.

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

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

The CSV file can contain the following columns:

  • accountid: The ID of your deployment.
  • applicationid: The ID of the Application this coupon is related to.
  • attributes: A json object describing custom referral attribute names and their values.
  • batchid: The ID of the batch this coupon is part of.
  • campaignid: The ID of the campaign this coupon is related to.
  • counter: The number of times this coupon has been redeemed.
  • created: The creation date of the coupon code.
  • deleted: Whether the coupon code is deleted.
  • deleted_changelogid: The ID of the delete event in the logs.
  • discount_counter: The amount of discount given by this coupon.
  • discount_limitval: The maximum discount amount that can be given be this coupon.
  • expirydate: The end date in RFC3339 of the code redemption period.
  • id: The internal ID of the coupon code.
  • importid: The ID of the import job that created this coupon.
  • is_reservation_mandatory: Whether this coupon requires a reservation to be redeemed.
  • limits: The limits set on this coupon.
  • limitval: The maximum number of redemptions of this code.
  • recipientintegrationid: The integration ID of the recipient of the coupon. Only the customer with this integration ID can redeem this code. Available only for personal codes.
  • referralid: The ID of the referral code that triggered the creation of this coupon (create coupon effect).
  • reservation: Whether the coupon can be reserved for multiple customers.
  • reservation_counter: How many times this coupon has been reserved.
  • reservation_limitval: The maximum of number of reservations this coupon can have.
  • startdate: The start date in RFC3339 of the code redemption period.
  • value: The coupon code.
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.

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.

value
string
Example: value=SUMMER10

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

Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon 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 coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.

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

Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiration date is set and in the past. The second matches coupons in which start date is null or in the past and expiration 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"
Example: usable=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
Example: referralId=47

Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code.

recipientIntegrationId
string
Example: recipientIntegrationId=customer1

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

batchId
string
Example: batchId=nfinccze

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"
Example: dateFormat=excel

Determines the format of dates in the export document.

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.
valuesOnly
boolean
Default: false

Filter results to only return the coupon codes (value column) without the associated coupon data.

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

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

query Parameters
integrationId
string
Example: integrationId=customer1

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

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.

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

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
required

body

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,
  • "totalResultSize": 0,
  • "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 ]
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.

sandbox
boolean
Default: false

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

Request Body schema: application/json
required

body

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

Get customer profile

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 the specified customer profile.

Performance tips

You can retrieve the same information via the Integration API, which can save you extra API requests. consider these options:

Authorizations:
manager_authmanagement_key
path Parameters
customerId
required
integer
Example: 3778

The value of the id property of a customer profile. Get it with the List Application's customers endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-02-07T08:15:22Z",
  • "integrationId": "URNGV8294NV",
  • "attributes": {
    },
  • "accountId": 31,
  • "closedSessions": 3,
  • "totalSales": 299.99,
  • "loyaltyMemberships": [
    ],
  • "audienceMemberships": [
    ],
  • "lastActivity": "2020-02-08T14:15:20Z",
  • "sandbox": false
}

List customer profiles

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

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.

sandbox
boolean
Default: false

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

Responses

Response samples

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

Get application's customer

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 customers of the specified 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.

customerId
required
integer
Example: 3778

The value of the id property of a customer profile. Get it with the List Application's customers endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-02-07T08:15:22Z",
  • "integrationId": "URNGV8294NV",
  • "attributes": {
    },
  • "accountId": 0,
  • "closedSessions": 3,
  • "totalSales": 299.99,
  • "loyaltyMemberships": [
    ],
  • "audienceMemberships": [
    ],
  • "lastActivity": "2020-02-08T14:15:20Z",
  • "sandbox": false,
  • "advocateIntegrationId": "string"
}

Get Activity Reports for Application 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.

Fetch summary reports for all application customers based on a time range. Instead of having the total number of results in the response, this endpoint only mentions whether there are more results.

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
rangeStart
required
string <date-time>
Example: rangeStart=2024-05-29T15:04:05Z07:00

Only return results from after this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
rangeEnd
required
string <date-time>
Example: rangeEnd=2024-05-29T15:04:05Z07:00

Only return results from before this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
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.

name
string
Example: name=customer1

Only return reports matching the customer name.

integrationId
string
Example: integrationId=customer1

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

campaignName
string
Example: campaignName=campaign1

Only return reports matching the campaign name.

advocateName
string
Example: advocateName=advocate1

Only return reports matching the current customer referrer name.

Responses

Response samples

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

Get customer's activity report

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.

Fetch the summary report of a given customer in the given application, in a time range.

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.

customerId
required
integer
Example: 3778

The value of the id property of a customer profile. Get it with the List Application's customers endpoint.

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

Only return results from after this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
rangeEnd
required
string <date-time>
Example: rangeEnd=2024-05-29T15:04:05Z07:00

Only return results from before this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
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.

Responses

Response samples

Content type
application/json
{
  • "integrationId": "URNGV8294NV",
  • "created": "2020-02-07T08:15:22Z",
  • "name": "string",
  • "customerId": 0,
  • "lastActivity": "2019-08-24T14:15:22Z",
  • "couponRedemptions": 0,
  • "couponUseAttempts": 0,
  • "couponFailedAttempts": 0,
  • "accruedDiscounts": 0,
  • "accruedRevenue": 0,
  • "totalOrders": 0,
  • "totalOrdersNoCoupon": 0,
  • "campaignName": "string"
}

Get customer's analytics report

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.

Fetch analytics for a given customer in the given 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.

customerId
required
integer
Example: 3778

The value of the id property of a customer profile. Get it with the List Application's customers endpoint.

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
{
  • "acceptedCoupons": 0,
  • "createdCoupons": 0,
  • "freeItems": 0,
  • "totalOrders": 0,
  • "totalDiscountedOrders": 0,
  • "totalRevenue": 0,
  • "totalDiscounts": 0
}

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

List all the sessions of the specified 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.

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.

profile
string
Example: profile=customer1

Profile integration ID filter for sessions. Must be exact match.

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

Filter by sessions with this state. Must be exact match.

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

Only return events created before this date. 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

Only return events created after this date. You can use any time zone setting. Talon.One will convert to UTC internally.

coupon
string
Example: coupon=SUMMER10

Filter by sessions with this coupon. Must be exact match.

referral
string
Example: referral=WPCNAQ5C

Filter by sessions with this referral. Must be exact match.

integrationId
string
Example: integrationId=customer1

Filter by sessions with this integration ID. Must be exact match.

storeIntegrationId
string
Example: storeIntegrationId=store1

The integration ID of the store. You choose this ID when you create a store.

Responses

Response samples

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

Get Application session

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 the given session. You can list the sessions with the List Application sessions endpoint.

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.

sessionId
required
integer
Example: 2533

The internal ID of the session. You can get the ID with the List Application sessions endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-02-07T08:15:22Z",
  • "integrationId": "URNGV8294NV",
  • "storeIntegrationId": "STORE-001",
  • "applicationId": 322,
  • "profileId": 138,
  • "profileintegrationid": "382370BKDB946",
  • "coupon": "BKDB946",
  • "referral": "BKDB946",
  • "state": "closed",
  • "cartItems": [
    ],
  • "discounts": {
    },
  • "totalDiscounts": 100,
  • "total": 200,
  • "attributes": { }
}

List Applications events

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.

Lists all events recorded for an application. Instead of having the total number of results in the response, this endpoint only mentions whether there are more results.

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.

type
string
Example: type=talon_session_created,talon_session_updated

Comma-separated list of types by which to filter events. Must be exact match(es).

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

Only return events created before this date. 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

Only return events created after this date. You can use any time zone setting. Talon.One will convert to UTC internally.

session
string
Example: session=session1

Session integration ID filter for events. Must be exact match.

profile
string
Example: profile=profile1

Profile integration ID filter for events. Must be exact match.

customerName
string >= 2 characters
Example: customerName=customer1

Customer name filter for events. Will match substrings case-insensitively.

customerEmail
string >= 2 characters
Example: customerEmail=john@doe.com

Customer e-mail address filter for events. Will match substrings case-insensitively.

couponCode
string
Example: couponCode=SUMMER10

Coupon code

referralCode
string
Example: referralCode=WPCNAQ5C

Referral code

ruleQuery
string
Example: ruleQuery=rule1

Rule name filter for events

campaignQuery
string
Example: campaignQuery=campaign1

Campaign name filter for events

Responses

Response samples

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

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

Get all of the distinct values of the Event type property for events recorded in the application.

See also: Track an event

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.

Responses

Response samples

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

Events

Represents a single occurrence of a specific customer action, for example, updating the cart or signing up for a newsletter.

There are 2 types of events:

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

Fetch all event type definitions for your account.

Authorizations:
manager_authmanagement_key
query Parameters
name
string
Example: name=event1

Filter results to event types with the given name. This parameter implies includeOldVersions.

includeOldVersions
boolean
Default: false

Include all versions of every event type.

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

Giveaways

Represents a program that rewards customers with giveaways, such as free gift cards.

See the docs.

Import giveaway codes into a giveaway pool

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 giveaway codes that should be created. Send the file as multipart data.

The CSV file contains the following columns:

  • code (required): The code of your giveaway, for instance, a gift card redemption code.

  • startdate: The start date in RFC3339 of the code redemption period.

  • enddate: The last date in RFC3339 of the code redemption period.

  • attributes: A JSON object describing custom giveaway attribute names and their values, enclosed with double quotation marks.

    For example, if you created a custom attribute called provider associated with the giveaway entity, the object in the CSV file, when opened in a text editor, must be: "{"provider": "myPartnerCompany"}".

The startdate and enddate have nothing to do with the validity of the codes. They are only used by the Rule Engine to award the codes or not. You can use the time zone setting of your choice. The values are converted to UTC internally by Talon.One.

Note:

  • We recommend limiting your file size to 500MB.
  • You can import the same code multiple times. Duplicate codes are treated and distributed to customers as unique codes.

Example:

code,startdate,enddate,attributes
GIVEAWAY1,2020-11-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"": ""Amazon""}"
GIVEAWAY2,2020-11-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"": ""Amazon""}"
GIVEAWAY3,2021-01-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"": ""Aliexpress""}"
Authorizations:
manager_authmanagement_key
path Parameters
poolId
required
integer
Example: 8

The ID of the pool. You can find it in the Campaign Manager, in the Giveaways section.

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 giveaway codes of a giveaway pool

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 giveaway codes of a specific giveaway pool.

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

The CSV file contains the following columns:

  • id: The internal ID of the giveaway.
  • poolid: The internal ID of the giveaway pool.
  • code: The giveaway code.
  • startdate: The validity start date in RFC3339 of the giveaway (can be empty).
  • enddate: The validity end date in RFC3339 of the giveaway (can be empty).
  • attributes: Any custom attributes associated with the giveaway code (can be empty).
  • used: An indication of whether the giveaway is already awarded.
  • importid: The ID of the import which created the giveaway.
  • created: The creation time of the giveaway code.
  • profileintegrationid: The third-party integration ID of the customer profile that was awarded the giveaway. Can be empty if the giveaway was not awarded.
  • profileid: The internal ID of the customer profile that was awarded the giveaway. Can be empty if the giveaway was not awarded or an internal ID does not exist.
Authorizations:
manager_authmanagement_key
path Parameters
poolId
required
integer
Example: 8

The ID of the pool. You can find it in the Campaign Manager, in the Giveaways section.

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

Timestamp that filters the results to only contain giveaways created before this date. Must be an RFC3339 timestamp string.

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

Timestamp that filters the results to only contain giveaways created after this date. Must be an RFC3339 timestamp string.

Responses

Response samples

Content type
application/csv
id,poolid,code,startdate,enddate,attributes,used,importid,created,profileintegrationid,profileid
1,7,af18bc3839799451fb6d6b6467cf4c25e,2023-04-11T12:47:47Z,2024-04-11T12:47:47Z,"{""attribute"": ""value""}",true,2,2023-04-11T12:47:47Z,R195412,35

Logs

Operations to query the Talon.One logs. They contain all incoming and outgoing requests.

Get access logs for 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.

Retrieve the list of API calls sent to the specified 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.

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

Only return results from after this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
rangeEnd
required
string <date-time>
Example: rangeEnd=2024-05-29T15:04:05Z07:00

Only return results from before this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
path
string
Example: path=pattern1

Only return results where the request path matches the given regular expression.

method
string
Enum: "get" "put" "post" "delete" "patch"
Example: method=get

Only return results where the request method matches the given regular expression.

status
string
Enum: "success" "error"
Example: status=success

Filter results by HTTP status codes.

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

List access logs

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.

Fetches the access logs for the entire account. Sensitive requests (logins) are always filtered from the logs.

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

Only return results from after this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
rangeEnd
string <date-time>
Example: rangeEnd=2024-05-29T15:04:05Z07:00

Only return results from before this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
path
string
Example: path=pattern1

Only return results where the request path matches the given regular expression.

method
string
Enum: "get" "put" "post" "delete" "patch"
Example: method=get

Only return results where the request method matches the given regular expression.

status
string
Enum: "success" "error"
Example: status=success

Filter results by HTTP status codes.

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

List webhook activation log entries

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.

Webhook activation log entries are created as soon as an integration request triggers a webhook effect. See the docs.

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.

integrationRequestUuid
string
Example: integrationRequestUuid=c987c53d-48d7-4a3b-a2a7-fb6b8f015610

Filter results by integration request UUID.

webhookId
number
Example: webhookId=29

Filter results by webhook id.

applicationId
number
Example: applicationId=19

Filter results by Application ID.

campaignId
number
Example: campaignId=49

Filter results by campaign ID.

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

Only return events created before this date. 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

Only return events created after this date. You can use any time zone setting. Talon.One will convert to UTC internally.

Responses

Response samples

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

List webhook log entries

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 webhook log entries.

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.

status
string
Enum: "success" "error"
Example: status=success

Filter results by HTTP status codes.

webhookId
number
Example: webhookId=29

Filter results by webhook id.

applicationId
number
Example: applicationId=19

Filter results by Application ID.

campaignId
number
Example: campaignId=49

Filter results by campaign ID.

requestUuid
string
Example: requestUuid=c987c53d-48d7-4a3b-a2a7-fb6b8f015610

Filter results by request UUID.

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

Filter results where request and response times to return entries before 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 where request and response times to return entries after parameter value, expected to be an RFC3339 timestamp string. You can use any time zone setting. Talon.One will convert to UTC internally.

Responses

Response samples

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

Get audit logs for an 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 the audit logs displayed in Accounts > Audit logs.

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.

applicationId
number
Example: applicationId=19

Filter results by Application ID.

entityPath
string
Example: entityPath=example/url/path

Filter results on a case insensitive matching of the url path of the entity

userId
integer
Example: userId=34

Filter results by user 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, to the change 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 change creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.

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.
managementKeyId
integer
Example: managementKeyId=16

Filter results that match the given management key ID.

includeOld
boolean

When this flag is set to false, the state without the change will not be returned. The default value is true.

Responses

Response samples

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

Get exports

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 past exports

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.

applicationId
number
Example: applicationId=19

Filter results by Application ID.

campaignId
integer
Example: campaignId=8

Filter by the campaign ID on which the limit counters are used.

entity
string
Enum: "Coupon" "Referral" "Effect" "CustomerSession" "LoyaltyLedger" "LoyaltyLedgerLog" "Collection" "AudienceMembership"
Example: entity=Coupon

The name of the entity type that was exported.

Responses

Response samples

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

Loyalty

Represents loyalty programs or concepts related to them.

Loyalty programs can be profile-based or card-based, depending on whether loyalty points are linked to customer profiles or loyalty cards.

See the Product docs for more information.

List loyalty programs

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 loyalty programs of the account.

Authorizations:
manager_authmanagement_key

Responses

Response samples

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

Get loyalty program

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 specified loyalty program. To list all loyalty programs in your Application, use List loyalty programs.

To list the loyalty programs that a customer profile is part of, use the List customer data

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 8

Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": 139,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "title": "Point collection",
  • "description": "Customers collect 10 points per 1$ spent",
  • "subscribedApplications": [
    ],
  • "defaultValidity": "2W_U",
  • "defaultPending": "immediate",
  • "allowSubledger": false,
  • "usersPerCardLimit": 111,
  • "sandbox": true,
  • "programJoinPolicy": "not_join",
  • "tiersExpirationPolicy": "tier_start_date",
  • "tierCycleStartDate": "2021-09-12T10:12:42Z",
  • "tiersExpireIn": "27W_U",
  • "tiersDowngradePolicy": "one_down",
  • "cardCodeSettings": {
    },
  • "accountID": 1,
  • "name": "my_program",
  • "tiers": [
    ],
  • "timezone": "Europe/Berlin",
  • "cardBased": true,
  • "canUpdateTiers": true,
  • "canUpdateJoinPolicy": true,
  • "canUpdateTierExpirationPolicy": true,
  • "canUpgradeToAdvancedTiers": true,
  • "canUpdateSubledgers": true
}

Import loyalty points

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 loyalty points you want to import into a given loyalty program. Send the file as multipart data.

Depending on the type of loyalty program, you can import points into a given customer profile or loyalty card.

The CSV file contains the following columns:

  • customerprofileid (optional): For profile-based loyalty programs, the integration ID of the customer profile where the loyalty points are imported.

  • identifier (optional): For card-based loyalty programs, the identifier of the loyalty card where the loyalty points are imported.

  • amount: The amount of points to award to the customer profile.

  • startdate (optional): The earliest date when the points can be redeemed. The points are active from this date until the expiration date.

    Note: It must be an RFC3339 timestamp string or string immediate. Empty or missing values are considered immediate.

  • expirydate (optional): The latest date when the points can be redeemed. The points are expired after this date.

    Note: It must be an RFC3339 timestamp string or string unlimited. Empty or missing values are considered unlimited.

  • subledgerid (optional): The ID of the subledger that should received the points.

  • reason (optional): The reason why these points are awarded.

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

Note: For existing customer profiles and loyalty cards, the imported points are added to any previous active or pending points, depending on the value provided for startdate. If startdate matches the current date, the imported points are active. If it is later, the points are pending until the date provided for startdate is reached.

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

Example for profile-based programs:

customerprofileid,amount,startdate,expirydate,subledgerid,reason
URNGV8294NV,100,2009-11-10T23:00:00Z,2009-11-11T23:00:00Z,subledger1,appeasement

Example for card-based programs:

identifier,amount,startdate,expirydate,subledgerid,reason
summer-loyalty-card-0543,100,2009-11-10T23:00:00Z,2009-11-11T23:00:00Z,subledger1,appeasement
Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 8

Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint.

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
}

Import customers into loyalty tiers

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 existing customers to be assigned to existing tiers. Send the file as multipart data.

Important: This endpoint only works with loyalty programs with advanced tiers (with expiration and downgrade policy) feature enabled.

The CSV file should contain the following columns:

  • subledgerid (optional): The ID of the subledger. If this field is empty, the main ledger will be used.
  • customerprofileid: The integration ID of the customer profile to whom the tier should be assigned.
  • tiername: The name of an existing tier to assign to the customer.
  • expirydate: The expiration date of the tier when the tier is reevaluated. It should be a future date.

About customer assignment to a tier:

  • If the customer isn't already in a tier, the customer is assigned to the specified tier during the tier import.
  • If the customer is already in the tier that's specified in the CSV file, only the expiration date is updated.

Note: We recommend not using this endpoint to update the tier of a customer. To update a customer's tier, you can add or deduct their loyalty points.

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

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

Example:

subledgerid,customerprofileid,tiername,expirydate
SUB1,alexa,Gold,2024-03-21T07:32:14Z
,george,Silver,2025-04-16T21:12:37Z
SUB2,avocado,Bronze,2026-05-03T11:47:01Z
Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 8

Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint.

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
}

Get customer's full loyalty ledger

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 loyalty ledger for this profile integration ID.

To get the integrationId of the profile from a sessionId, use the Update customer session endpoint.

Important: To get loyalty transaction logs for a given Integration ID in a loyalty program, we recommend using the Integration API's Get customer's loyalty logs.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
string
Example: 45

The identifier for the loyalty program.

integrationId
required
string
Example: customer1

The identifier of the profile.

Responses

Response samples

Content type
application/json
{
  • "ledger": {
    },
  • "subLedgers": {
    }
}

Add points to customer profile

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.

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

To get the integrationId of the profile from a sessionId, use the Update customer session endpoint.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
string
Example: 45

The identifier for the loyalty program.

integrationId
required
string
Example: customer1

The identifier of the profile.

Request Body schema: application/json
required

body

points
required
number ( 0 .. 999999999999.99 ]

Amount of loyalty points.

name
string

Name / reason for the point addition.

validityDuration
string

The time format is either:

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

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

Available units:

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

You can round certain units up or down:

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

If passed, validUntil should be omitted.

validUntil
string <date-time>

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

pendingDuration
string

The amount of time before the points are considered valid.

The time format is either:

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

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

Available units:

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

You can round certain units up or down:

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

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

subledgerId
string

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

applicationId
integer

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

Responses

Request samples

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

Response samples

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

Deduct points from customer profile

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.

Deduct points from the specified loyalty program and specified customer profile.

Important:

  • Only active points can be deducted.
  • Only pending points are rolled back when a session is cancelled or reopened.

To get the integrationId of the profile from a sessionId, use the Update customer session endpoint.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
string
Example: 45

The identifier for the loyalty program.

integrationId
required
string
Example: customer1

The identifier of the profile.

Request Body schema: application/json
required

body

points
required
number ( 0 .. 999999999999.99 ]

Amount of loyalty points.

name
string

Name / reason for the point deduction.

subledgerId
string

ID of the subledger the points are deducted from.

applicationId
integer

ID of the Application that is connected to the loyalty program.

Responses

Request samples

Content type
application/json
{
  • "points": 300,
  • "name": "Penalty",
  • "subledgerId": "sub-123",
  • "applicationId": 322
}

Response samples

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

Export customer's transaction logs

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 customer's transaction logs in the loyalty program.

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:

  • customerprofileid: The ID of the profile.
  • customersessionid: The ID of the customer session.
  • rulesetid: The ID of the rule set.
  • rulename: The name of the rule.
  • programid: The ID of the loyalty program.
  • type: The transaction type, such as addition or subtraction.
  • name: The reason for the transaction.
  • subledgerid: The ID of the subledger, when applicable.
  • startdate: The start date of the program.
  • expirydate: The expiration date of the program.
  • id: The ID of the transaction.
  • created: The timestamp of the creation of the loyalty program.
  • amount: The number of points in that transaction.
  • archived: Whether the session related to the transaction is archived.
  • campaignid: The ID of the campaign.
Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
string
Example: 45

The identifier for the loyalty program.

integrationId
required
string
Example: customer1

The identifier of the profile.

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

Only return results from after this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
rangeEnd
required
string <date-time>
Example: rangeEnd=2024-05-29T15:04:05Z07:00

Only return results from before this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
dateFormat
string
Enum: "excel" "ISO8601"
Example: dateFormat=excel

Determines the format of dates in the export document.

Responses

Response samples

Content type
application/csv
customerprofileid,customersessionid,rulesetid,rulename,programid,type,name,subledgerid,startdate,expirydate,id,created,amount,archived,campaignid
8NHOS78H,06b0fafb-ccbf-42c7-b44b-d858e8b525022,1691,test,37,subtraction,10% of current total,,immediate,unlimited,60803,2022-11-29 16:16:10,100.00,false,5
EB780RDN,06b0fafb-ccbf-42c7-b44b-d858e8b525022,1691,test,37,addition,Reimbursed loyalty points,,immediate,unlimited,60804,2022-11-29 16:16:23,100.00,false,5

Export customers' tier 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 the tier information for customers of the specified loyalty program.

The generated file contains the following columns:

  • programid: The identifier of the loyalty program. It is displayed in your Talon.One deployment URL.
  • subledgerid: The ID of the subledger associated with the loyalty program. This column is empty if the loyalty program has no subledger. In this case, refer to the export file name to get the ID of the loyalty program.
  • customerprofileid: The ID used to integrate customer profiles with the loyalty program.
  • tiername: The name of the tier.
  • startdate: The tier start date in RFC3339.
  • expirydate: The tier expiry date in RFC3339.

You can filter the results by providing the following optional input parameters:

  • subledgerIds (optional): Filter results by an array of subledger IDs. If no value is provided, all subledger data for the specified loyalty program will be exported.
  • tierNames (optional): Filter results by an array of tier names. If no value is provided, all tier data for the specified loyalty program will be exported.
Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
string
Example: 45

The identifier for the loyalty program.

query Parameters
subledgerIds
Array of strings
Example: subledgerIds=subledger1,subledger2

An array of subledgers IDs to filter the export by.

tierNames
Array of strings
Example: tierNames=tier1,tier2

An array of tier names to filter the export by.

Responses

Response samples

Content type
application/csv
programid,subledgerid,customerprofileid,tiername,startdate,expirydate
1,SUB1,Dinesh,Golden,2023-08-02T15:04:05Z07:00,2024-08-02T15:04:05Z07:00
1,SUB2,Gilfoyle,Silver,2023-03-21T03:45:12Z05:00,2026-03-21T03:45:12Z05:00

Get loyalty program statistics

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 statistics of the specified loyalty program such as the total active points, pending points, spent points, and expired points.

Important: The returned data does not include the current day. All statistics are updated daily at 11:59 PM in the loyalty program time zone.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 8

Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint.

Responses

Response samples

Content type
application/json
{
  • "date": "2019-08-24T14:15:22Z",
  • "totalActivePoints": 9756,
  • "totalPendingPoints": 548,
  • "totalSpentPoints": 25668,
  • "totalExpiredPoints": 1156,
  • "totalMembers": 2582,
  • "newMembers": 3,
  • "spentPoints": {
    },
  • "earnedPoints": {
    }
}

Export customer loyalty balances

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 balance of each customer in the loyalty program.

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:

  • loyaltyProgramID: The ID of the loyalty program.
  • loyaltySubledger: The name of the subdleger, when applicatble.
  • profileIntegrationID: The integration ID of the customer profile.
  • currentBalance: The current point balance.
  • pendingBalance: The number of pending points.
  • expiredBalance: The number of expired points.
  • spentBalance: The number of spent points.
  • currentTier: The tier that the customer is in at the time of the export.
Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
string
Example: 45

The identifier for the loyalty program.

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

Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.

Responses

Response samples

Content type
application/csv
loyaltyProgramID,loyaltySubledger,profileIntegrationID,currentBalance,pendingBalance,expiredBalance,spentBalance,currentTier
40,,8786NTHSAO8,10.00,0.00,0.00,0.00,First
40,,2735HATHOH8,20.00,0.00,0.00,0.00,First

Export customer loyalty balance to CSV Deprecated

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.

⚠️ Deprecation notice: Support for requests to this endpoint will end soon. To export customer loyalty balances to CSV, use the Export customer loyalty balances to CSV endpoint.

Download a CSV file containing the balance of each customer in the loyalty program.

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

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
string
Example: 45

The identifier for the loyalty program.

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

Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.

Responses

List loyalty program transactions

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 loyalty program transaction logs in a given loyalty program with filtering options applied. Manual and imported transactions are also included. Note: If no filters are applied, the last 50 loyalty transactions for the given loyalty program are returned.

Important: To get loyalty transaction logs for a given Integration ID in a loyalty program, we recommend using the Integration API's Get customer's loyalty logs.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 8

Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint.

query Parameters
loyaltyTransactionType
string
Enum: "manual" "session" "import"
Example: loyaltyTransactionType=manual

Filter results by loyalty transaction type:

  • manual: Loyalty transaction that was done manually.
  • session: Loyalty transaction that resulted from a customer session.
  • import: Loyalty transaction that was imported from a CSV file.
subledgerId
string
Example: subledgerId=subledger1

The ID of the subledger by which we filter the data.

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

Date and time from which results are returned. Results are filtered by transaction creation date.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
endDate
string <date-time>
Example: endDate=2024-05-29T15:04:05Z07:00

Date and time by which results are returned. Results are filtered by transaction creation date.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
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.

Responses

Response samples

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

Loyalty cards

Represents loyalty cards.

Loyalty cards allow your customers to collect and spend loyalty points within a card-based loyalty program.

Import loyalty cards

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 loyalty cards that you want to use in your card-based loyalty program. Send the file as multipart data.

It contains the following columns for each card:

  • identifier (required): The alphanumeric identifier of the loyalty card.
  • state (required): The state of the loyalty card. It can be active or inactive.
  • customerprofileids (optional): An array of strings representing the identifiers of the customer profiles linked to the loyalty card.

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

Example:

identifier,state,customerprofileids
123-456-789AT,active,Alexa001;UserA
Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

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
}

Create loyalty cards

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 batch of loyalty cards in a specified card-based loyalty program.

Customers can use loyalty cards to collect and spend loyalty points.

Important:

  • The specified card-based loyalty program must have a defined card code format that is used to generate the loyalty card codes.
  • Trying to create more than 20,000 loyalty cards in a single request returns an error message with a 400 status code.
Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

Request Body schema: application/json
required

body

numberOfCards
required
integer

Number of loyalty cards in the batch.

batchId
string [ 4 .. 20 ] characters ^[A-Za-z0-9_-]*$

ID of the loyalty card batch.

status
string
Default: "active"
Enum: "active" "inactive"

Status of the loyalty cards in the batch.

object

Responses

Request samples

Content type
application/json
{
  • "numberOfCards": 5000,
  • "batchId": "hwernpjz",
  • "status": "active",
  • "cardCodeSettings": {
    }
}

Response samples

Content type
application/json
{
  • "numberOfCardsGenerated": 5000,
  • "batchId": "hwernpjz"
}

Export all card transaction logs

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 balances of all cards in the loyalty program.

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

The CSV file contains the following columns:

  • loyaltyProgramID: The ID of the loyalty program.
  • loyaltySubledger: The name of the subdleger, when applicatble.
  • cardIdentifier: The alphanumeric identifier of the loyalty card.
  • cardState:The state of the loyalty card. It can be active or inactive.
  • currentBalance: The current point balance.
  • pendingBalance: The number of pending points.
  • expiredBalance: The number of expired points.
  • spentBalance: The number of spent points.
Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

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

Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.

Responses

Response samples

Content type
application/csv
loyaltyProgramID,loyaltySubledger,cardIdentifier,cardState,currentBalance,pendingBalance,expiredBalance,spentBalance
40,,111,active,10,0,0,0,5

List loyalty cards

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 card-based loyalty program, list the loyalty cards that match your filter criteria.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

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.

identifier
string >= 4 characters
Example: identifier=summer-loyalty-card-054

The card code by which to filter loyalty cards in the response.

profileId
integer >= 1
Example: profileId=44

Filter results by customer profile ID.

batchId
string
Example: batchId=UY83CTT4

Filter results by loyalty card batch ID.

Responses

Response samples

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

Export loyalty cards

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 loyalty cards from a specified loyalty program.

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

The CSV file contains the following columns:

  • identifier: The unique identifier of the loyalty card.
  • created: The date and time the loyalty card was created.
  • status: The status of the loyalty card.
  • userpercardlimit: The maximum number of customer profiles that can be linked to the card.
  • customerprofileids: Integration IDs of the customer profiles linked to the card.
  • blockreason: The reason for transferring and blocking the loyalty card.
  • generated: An indicator of whether the loyalty card was generated.
  • batchid: The ID of the batch the loyalty card is in.
Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

query Parameters
batchId
string
Example: batchId=UY83CTT4

Filter results by loyalty card batch ID.

Responses

Response samples

Content type
application/csv
identifier,created,status,userpercardlimit,customerprofileids,blockreason,generated,batchid
CARD-1234,2020-06-10T09:05:27.993483Z,active,3,['profile1'],card limit reached,false,gwedcbfp

Delete loyalty card

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

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

loyaltyCardId
required
string <= 108 characters
Example: summer-loyalty-card-0543

Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint.

Responses

Response samples

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

Update loyalty card status

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 status of the given loyalty card. A card can be active or inactive.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

loyaltyCardId
required
string <= 108 characters
Example: summer-loyalty-card-0543

Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint.

Request Body schema: application/json
required

body

status
required
string

Status of the loyalty card. Can be active or inactive.

blockReason
string

Reason for transferring and blocking the loyalty card.

Responses

Request samples

Content type
application/json
{
  • "status": "active",
  • "blockReason": "Current card lost. Customer needs a new card."
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "programID": 125,
  • "status": "active",
  • "blockReason": "Current card lost. Customer needs a new card.",
  • "identifier": "summer-loyalty-card-0543",
  • "usersPerCardLimit": 111,
  • "profiles": [
    ],
  • "ledger": {
    },
  • "subledgers": {
    },
  • "modified": "2021-09-12T10:12:42Z",
  • "oldCardIdentifier": "summer-loyalty-card-0543",
  • "newCardIdentifier": "summer-loyalty-card-0543",
  • "batchId": "wdefpov"
}

Get loyalty card

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 given loyalty card.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

loyaltyCardId
required
string <= 108 characters
Example: summer-loyalty-card-0543

Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "programID": 125,
  • "status": "active",
  • "blockReason": "Current card lost. Customer needs a new card.",
  • "identifier": "summer-loyalty-card-0543",
  • "usersPerCardLimit": 111,
  • "profiles": [
    ],
  • "ledger": {
    },
  • "subledgers": {
    },
  • "modified": "2021-09-12T10:12:42Z",
  • "oldCardIdentifier": "summer-loyalty-card-0543",
  • "newCardIdentifier": "summer-loyalty-card-0543",
  • "batchId": "wdefpov"
}

Add points to card

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.

Add points to the given loyalty card in the specified card-based loyalty program.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

loyaltyCardId
required
string <= 108 characters
Example: summer-loyalty-card-0543

Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint.

Request Body schema: application/json
required

body

points
required
number ( 0 .. 999999999999.99 ]

Amount of loyalty points.

name
string

Name / reason for the point addition.

validityDuration
string

The time format is either:

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

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

Available units:

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

You can round certain units up or down:

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

If passed, validUntil should be omitted.

validUntil
string <date-time>

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

pendingDuration
string

The amount of time before the points are considered valid.

The time format is either:

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

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

Available units:

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

You can round certain units up or down:

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

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

subledgerId
string

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

applicationId
integer

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

Responses

Request samples

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

Response samples

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

Deduct points from card

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.

Deduct points from the given loyalty card in the specified card-based loyalty program.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

loyaltyCardId
required
string <= 108 characters
Example: summer-loyalty-card-0543

Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint.

Request Body schema: application/json
required

body

points
required
number ( 0 .. 999999999999.99 ]

Amount of loyalty points.

name
string

Name / reason for the point deduction.

subledgerId
string

ID of the subledger the points are deducted from.

applicationId
integer

ID of the Application that is connected to the loyalty program.

Responses

Request samples

Content type
application/json
{
  • "points": 300,
  • "name": "Penalty",
  • "subledgerId": "sub-123",
  • "applicationId": 322
}

Response samples

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

Export card's ledger log

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 loyalty card ledger log of the loyalty program.

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

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

loyaltyCardId
required
string <= 108 characters
Example: summer-loyalty-card-0543

Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint.

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

Only return results from after this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
rangeEnd
required
string <date-time>
Example: rangeEnd=2024-05-29T15:04:05Z07:00

Only return results from before this timestamp.

Note:

  • This must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
dateFormat
string
Enum: "excel" "ISO8601"
Example: dateFormat=excel

Determines the format of dates in the export document.

Responses

List card's transactions

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 transaction logs for the given loyalty card within the specified card-based loyalty program with filtering options applied. If no filtering options are applied, the last 50 loyalty transactions for the given loyalty card are returned.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

loyaltyCardId
required
string <= 108 characters
Example: summer-loyalty-card-0543

Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint.

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

Date and time from which results are returned. Results are filtered by transaction creation date.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
endDate
string <date-time>
Example: endDate=2024-05-29T15:04:05Z07:00

Date and time by which results are returned. Results are filtered by transaction creation date.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
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.

subledgerId
string
Example: subledgerId=subledger1

The ID of the subledger by which we filter the data.

Responses

Response samples

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

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

Transfer loyalty card data, such as linked customers, loyalty balances and transactions, from a given loyalty card to a new, automatically created loyalty card.

Important:

  • The original card is automatically blocked once the new card is created, and it cannot be activated again.
  • The default status of the new card is active.
Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint.

loyaltyCardId
required
string <= 108 characters
Example: summer-loyalty-card-0543

Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint.

Request Body schema: application/json
required

body

newCardIdentifier
required
string <= 108 characters

The alphanumeric identifier of the loyalty card.

blockReason
string

Reason for transferring and blocking the loyalty card.

Responses

Request samples

Content type
application/json
{
  • "newCardIdentifier": "summer-loyalty-card-0543",
  • "blockReason": "Current card lost. Customer needs a new card."
}

Response samples

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

Notifications

Represents the notifications that customers can create about various events. See Application notifications.

Activate or deactivate notification

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.

Activate or deactivate the given notification. When enabled is false, updates will no longer be sent for the given notification.

Authorizations:
manager_authmanagement_key
path Parameters
notificationId
required
integer
Example: 26

The ID of the notification. Get it with the appropriate List notifications endpoint.

Request Body schema: application/json
required

body

enabled
required
boolean

Indicates whether the notification is activated.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Create notification about added or deducted loyalty points

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 notification about added or deducted loyalty points in a given profile-based loyalty program. A notification for added or deducted loyalty points is different from regular webhooks in that it is loyalty program-scoped and has a predefined payload.

For more information, see Loyalty notifications.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the profile-based loyalty program. You can get the ID with the List loyalty programs endpoint.

Request Body schema: application/json
required

body

required
ExpiringCouponsNotificationPolicy (object) or CardExpiringPointsNotificationPolicy (object) or ExpiringPointsNotificationPolicy (object) or AddedDeductedPointsNotificationPolicy (object) or CardAddedDeductedPointsNotificationPolicy (object) or CouponsNotificationPolicy (object) or CatalogsStrikethroughNotificationPolicy (object) or PendingPointsNotificationPolicy (object) or CampaignNotificationPolicy (object) or TierDowngradeNotificationPolicy (object) or TierUpgradeNotificationPolicy (object) or TierWillDowngradeNotificationPolicy (object)

Indicates which notification properties to apply.

required
object
enabled
boolean
Default: true

Indicates whether the notification is activated.

Responses

Request samples

Content type
application/json
{
  • "policy": {
    },
  • "enabled": true,
  • "webhook": {
    }
}

Response samples

Content type
application/json
{
  • "policy": {
    },
  • "enabled": true,
  • "webhook": {
    },
  • "id": 6,
  • "type": "loyalty_added_deducted_points"
}

Create notification about pending loyalty points

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 notification about pending loyalty points for a given profile-based loyalty program. For more information, see Loyalty notifications.

Authorizations:
manager_authmanagement_key
path Parameters
loyaltyProgramId
required
integer
Example: 33

Identifier of the profile-based loyalty program. You can get the ID with the List loyalty programs endpoint.

Request Body schema: application/json
required

body

required
ExpiringCouponsNotificationPolicy (object) or CardExpiringPointsNotificationPolicy (object) or ExpiringPointsNotificationPolicy (object) or AddedDeductedPointsNotificationPolicy (object) or CardAddedDeductedPointsNotificationPolicy (object) or CouponsNotificationPolicy (object) or CatalogsStrikethroughNotificationPolicy (object) or PendingPointsNotificationPolicy (object) or CampaignNotificationPolicy (object) or TierDowngradeNotificationPolicy (object) or TierUpgradeNotificationPolicy (object) or TierWillDowngradeNotificationPolicy (object)

Indicates which notification properties to apply.

required
object
enabled
boolean
Default: true

Indicates whether the notification is activated.

Responses

Request samples

Content type
application/json
{
  • "policy": {
    },
  • "enabled": true,
  • "webhook": {
    }
}

Response samples

Content type
application/json
{
  • "policy": {
    },
  • "enabled": true,
  • "webhook": {
    },
  • "id": 6,
  • "type": "loyalty_added_deducted_points"
}

Create strikethrough notification

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 notification for the in the given Application. For more information, see Application notifications.

See the payload you will receive.

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

required
ExpiringCouponsNotificationPolicy (object) or CardExpiringPointsNotificationPolicy (object) or ExpiringPointsNotificationPolicy (object) or AddedDeductedPointsNotificationPolicy (object) or CardAddedDeductedPointsNotificationPolicy (object) or CouponsNotificationPolicy (object) or CatalogsStrikethroughNotificationPolicy (object) or PendingPointsNotificationPolicy (object) or CampaignNotificationPolicy (object) or TierDowngradeNotificationPolicy (object) or TierUpgradeNotificationPolicy (object) or TierWillDowngradeNotificationPolicy (object)

Indicates which notification properties to apply.

required
object
enabled
boolean
Default: true

Indicates whether the notification is activated.

Responses

Request samples

Content type
application/json
{
  • "policy": {
    },
  • "enabled": true,
  • "webhook": {
    }
}

Response samples

Content type
application/json
{
  • "policy": {
    },
  • "enabled": true,
  • "webhook": {
    },
  • "id": 6,
  • "type": "loyalty_added_deducted_points"
}

Referrals

A referral is a code shared between a customer and a prospect.

A referral is defined by:

  • an advocate: person who invited their friend via referral program.
  • a friend: person who receives the invite from an advocate.
  • a referral code: code to be redeemed by the advocate(s) once they referred their friend.

See the docs.

Delete referral

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

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.

referralId
required
string
Example: 2154

The ID of the referral code.

Responses

Update referral

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

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.

referralId
required
string
Example: 2154

The ID of the referral code.

Request Body schema: application/json
required

body

friendProfileIntegrationId
string <= 1000 characters

An optional Integration ID of the Friend's Profile.

startDate
string <date-time> >= 0

Timestamp at which point the referral code becomes valid.

expiryDate
string <date-time> >= 0

Expiration date of the referral code. Referral never expires if this is omitted.

usageLimit
integer [ 0 .. 999999 ]

The number of times a referral code can be used. This can be set to 0 for no limit, but any campaign usage limits will still apply.

object

Arbitrary properties associated with this item.

Responses

Request samples

Content type
application/json
{
  • "friendProfileIntegrationId": "BZGGC2454PA",
  • "startDate": "2020-11-10T23:00:00Z",
  • "expiryDate": "2021-11-10T23:00:00Z",
  • "usageLimit": 1,
  • "attributes": { }
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "startDate": "2020-11-10T23:00:00Z",
  • "expiryDate": "2021-11-10T23:00:00Z",
  • "usageLimit": 1,
  • "campaignId": 78,
  • "advocateProfileIntegrationId": "URNGV8294NV",
  • "friendProfileIntegrationId": "BZGGC2454PA",
  • "attributes": {
    },
  • "importId": 4,
  • "code": "27G47Y54VH9L",
  • "usageCounter": 1,
  • "batchId": "tqyrgahe"
}

List referrals

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 referrals of the specified 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 .. 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.

code
string
Example: code=JVM8JH8F

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

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 referral 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 referral creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.

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

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

usable
string
Enum: "true" "false"
Example: usable=false

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

advocate
string
Example: advocate=customer1

Filter results by match with a profile ID specified in the referral's AdvocateProfileIntegrationId field.

Responses

Response samples

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

List friends referred by customer profile

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 friends referred by the specified customer profile in this 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.

integrationId
required
string
Example: advocate1

The Integration ID of the Advocate's Profile.

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

Export referrals

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 referrals that match the given parameters.

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

The CSV file contains the following columns:

  • code: The referral code.
  • advocateprofileintegrationid: The profile ID of the advocate.
  • startdate: The start date in RFC3339 of the code redemption period.
  • expirydate: The end date in RFC3339 of the code redemption period.
  • limitval: The maximum number of redemptions of this code. Defaults to 1 when left blank.
  • attributes: A json object describing custom referral attribute names and their values.
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, to the referral 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 referral creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.

valid
string
Enum: "expired" "validNow" "validFuture"
Example: valid=validNow
  • expired: Matches referrals in which the expiration date is set and in the past.
  • validNow: Matches referrals in which start date is null or in the past and expiration date is null or in the future.
  • validFuture: Matches referrals in which start date is set and in the future.
usable
string
Enum: "true" "false"
Example: usable=true
  • true, only referrals where usageCounter < usageLimit will be returned.
  • false, only referrals where usageCounter >= usageLimit will be returned.
batchId
string
Example: batchId=nfinccze

Filter results by batches of referrals

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

Determines the format of dates in the export document.

Responses

Response samples

Content type
application/csv
id,created,campaignid,advocateprofileintegrationid,friendprofileintegrationid,startdate,expirydate,code,importid,attributes,batchid,counter,limitval
687,2021-09-10 09:21:06,3882,UGAV4628K,,,,3LFC-4BPC,,"{}",pimcxobg,0,9999

Import referrals

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 referrals that should be created. The file should be sent as multipart data.

The CSV file contains the following columns:

  • code (required): The referral code.

  • advocateprofileintegrationid (required): The profile ID of the advocate.

  • startdate: The start date in RFC3339 of the code redemption period.

  • expirydate: The end date in RFC3339 of the code redemption period.

  • limitval: The maximum number of redemptions of this code. Defaults to 1 when left blank.

  • attributes: A JSON object describing custom referral attribute names and their values, enclosed with double quotation marks.

    For example, if you created a custom attribute called category associated with the referral entity, the object in the CSV file, when opened in a text editor, must be: "{"category": "10_off"}".

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

Important: When you import a CSV file with referrals, a customer profile is not automatically created for each advocateprofileintegrationid column value. Use the Update customer profile endpoint or the Update multiple customer profiles endpoint to create the customer profiles.

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

Example:

code,startdate,expirydate,advocateprofileintegrationid,limitval,attributes
REFERRAL_CODE1,2020-11-10T23:00:00Z,2021-11-11T23:00:00Z,integid_4,1,"{""my_attribute"": ""10_off""}"
REFERRAL_CODE2,2020-11-10T23:00:00Z,2021-11-11T23:00:00Z,integid1,1,"{""my_attribute"": ""20_off""}"
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: 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
}

Roles

Represents a set of permissions assigned to a user.

See the docs.

List roles

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

Authorizations:
manager_authmanagement_key

Responses

Response samples

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

Get role

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 role. To see all the roles, use the List roles endpoint.

Authorizations:
manager_authmanagement_key
path Parameters
roleId
required
integer
Example: 9

The ID of role.

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

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": "Campaign and campaign access group manager",
  • "description": "Allows you to create and edit campaigns for specific Applications, delete specific campaign access groups, and view loyalty programs.",
  • "permissions": {
    },
  • "members": [
    ]
}

Update role

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 a specific role.

Authorizations:
manager_authmanagement_key
path Parameters
roleId
required
integer
Example: 9

The ID of role.

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

Request Body schema: application/json
required

body

name
string

Name of the role.

description
string

Description of the role.

object
members
Array of integers

A list of user IDs the role is assigned to.

Responses

Request samples

Content type
application/json
{
  • "name": "Campaign and campaign access group manager",
  • "description": "Allows you to create and edit campaigns for specific Applications, delete specific campaign access groups, and view loyalty programs.",
  • "permissions": {
    },
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "modified": "2021-09-12T10:12:42Z",
  • "accountId": 3886,
  • "name": "Campaign and campaign access group manager",
  • "description": "Allows you to create and edit campaigns for specific Applications, delete specific campaign access groups, and view loyalty programs.",
  • "permissions": {
    },
  • "members": [
    ]
}

Sessions

Represents a session used for authentication purposes. Create one with the Create session endpoint.

Create session

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 session to use the Management API endpoints. Use the value of the token property provided in the response as bearer token in other API calls.

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.

This endpoint has a rate limit of 3 to 6 requests per second per account, depending on your setup.

Granular API key

Instead of using a session, you can also use the Management API key feature in the Campaign Manager to decide which endpoints can be used with a given key.
Authorizations:
manager_authmanagement_key
Request Body schema: application/json
required

body

email
required
string <email>

The email address associated with the user profile.

password
required
string

The password for your account.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "userId": 109,
  • "token": "dy_Fa_lQ4iDAnqldJFvVEmnsN8xDTxej19l0LZDBJhQ",
  • "created": "2021-07-20T22:00:00Z"
}

Destroy session

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.

Destroys the session.

Authorizations:
manager_authmanagement_key

Responses

Stores

Represents physical or digital stores, branches, and franchises.

List stores

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

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.
campaignId
number
Example: campaignId=49

Filter results by campaign ID.

name
string
Example: name=store1

The name of the store.

integrationId
string
Example: integrationId=storeId1

The integration ID of the store.

query
string
Example: query=name

Filter results by name or integrationId.

Responses

Response samples

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

Create store

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 store in a specific 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.

Request Body schema: application/json
required

body

name
required
string [ 1 .. 200 ] characters

The name of the store.

description
required
string

The description of the store.

integrationId
required
string <string> [ 1 .. 1000 ] characters

The integration ID of the store. You choose this ID when you create a store.

Note: You cannot edit the integrationId after the store has been created.

object

The attributes of the store.

Responses

Request samples

Content type
application/json
{
  • "name": "South US store",
  • "description": "This is the description of the store in south US.",
  • "attributes": {
    },
  • "integrationId": "STORE-001"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-02-07T08:15:22Z",
  • "name": "South US store",
  • "description": "This is the description of the store in south US.",
  • "attributes": {
    },
  • "integrationId": "STORE-001",
  • "applicationId": 322,
  • "updated": "2021-09-23T10:12:42Z",
  • "linkedCampaignIds": [
    ]
}

Get store

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 store details for a specific store 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.

storeId
required
string
Example: 17

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

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-02-07T08:15:22Z",
  • "name": "South US store",
  • "description": "This is the description of the store in south US.",
  • "attributes": {
    },
  • "integrationId": "STORE-001",
  • "applicationId": 322,
  • "updated": "2021-09-23T10:12:42Z",
  • "linkedCampaignIds": [
    ]
}

Update store

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 store details for a specific store 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.

storeId
required
string
Example: 17

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

Request Body schema: application/json
required

body

name
required
string [ 1 .. 200 ] characters

The name of the store.

description
required
string

The description of the store.

integrationId
required
string <string> [ 1 .. 1000 ] characters

The integration ID of the store. You choose this ID when you create a store.

Note: You cannot edit the integrationId after the store has been created.

object

The attributes of the store.

Responses

Request samples

Content type
application/json
{
  • "name": "South US store",
  • "description": "This is the description of the store in south US.",
  • "attributes": {
    },
  • "integrationId": "STORE-001"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-02-07T08:15:22Z",
  • "name": "South US store",
  • "description": "This is the description of the store in south US.",
  • "attributes": {
    },
  • "integrationId": "STORE-001",
  • "applicationId": 322,
  • "updated": "2021-09-23T10:12:42Z",
  • "linkedCampaignIds": [
    ]
}

Delete store

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

storeId
required
string
Example: 17

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

Responses

Response samples

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

Export stores

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 stores linked to a specific campaign.

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

The CSV file contains the following column:

  • store_integration_id: The identifier of the 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.

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/csv
store_integration_id
STORE-001
STORE-002
STORE-003

Disconnect stores

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.

Disconnect the stores linked to 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.

Responses

Response samples

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

Import stores

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 stores you want to link to a specific campaign.

Send the file as multipart data.

The CSV file must only contain the following column:

  • store_integration_id: The identifier of the store.

The import replaces the previous list of stores linked to the 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: 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
}

Webhooks

A way to send information from Talon.One to the URI of your choice.

See the docs.

List webhooks

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

Authorizations:
manager_authmanagement_key
query Parameters
applicationIds
string
Example: applicationIds=33

Checks if the given catalog or its attributes are referenced in the specified Application ID.

Note: If no Application ID is provided, we check for all connected Applications.

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.

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.

creationType
string
Enum: "templateWebhooks" "webhooks"
Example: creationType=webhooks

Filter results by creation type.

visibility
string
Enum: "visible" "hidden"
Example: visibility=visible

Filter results by visibility.

outgoingIntegrationsTypeId
integer
Example: outgoingIntegrationsTypeId=15

Filter results by outgoing integration type ID.

title
string
Example: title=title1

Filter results performing case-insensitive matching against the webhook title.

Responses

Response samples

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

Get webhook

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 a webhook by its id.

Authorizations:
manager_authmanagement_key
path Parameters
webhookId
required
integer
Example: 11

The ID of the webhook. You can find the ID in the Campaign Manager's URL when you display the details of the webhook in Account > Webhooks.

Responses

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "modified": "2021-09-12T10:12:42Z",
  • "applicationIds": [
    ],
  • "title": "Send message",
  • "description": "A webhook to send a coupon to the user.",
  • "verb": "POST",
  • "url": "www.my-company.com/my-endpoint-name",
  • "headers": [
    ],
  • "payload": "{\n\t\"message\": \"${message}\"\n}",
  • "params": [ ],
  • "enabled": true
}