Skip to main content

Integration API reference docs

Download OpenAPI specification:Download

Use the Integration API to push data to and retrieve data from Talon.One in real time. For more background information about this API, see Integration API overview

For example, use this API to share shopping cart information as a session with Talon.One and evaluate promotion rules. You can also create custom events to track specific actions that do not fit into the session data model.

Ensure you authenticate to make requests to the API.

Are you looking for a different API?

If you need the API to:

Authentication

api_key_v1

To authenticate to use the Integration API, generate an API key in the Campaign Manager then prefix it with ApiKey-v1.

To generate an API key:

  1. Log into the Campaign Manager and open the Application of your choice, or create one.
  2. Click Settings > Developer settings.
  3. Click Create API Key and give it a name and an expiration date, then click Create API Key.

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

Authorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3

Or use it inside an SDK, for example, with the JAVA SDK:

iApi.getApiClient().setApiKeyPrefix("ApiKey-v1");
iApi.getApiClient().setApiKey("dbc644d33aa74d582bd9479c59e16f970fe13bf3");
Security Scheme Type: API Key
Header parameter name: Authorization

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.

Create audience

Create an audience. The audience can be created directly from scratch or can come from third party platforms.

Note: Audiences can also be created from scratch via the Campaign Manager. See the docs.

To create an audience from an existing audience from a technology partner:

  1. Set the integration property to mparticle, segment etc., depending on a third-party platform.
  2. Set integrationId to the ID of this audience in a third-party platform.

To create an audience from an existing audience in another platform:

  1. Do not use the integration property.
  2. Set integrationId to the ID of this audience in the 3rd-party platform.

To create an audience from scratch:

  1. Only set the name property.

Once you create your first audience, audience-specific rule conditions are enabled in the Rule Builder.

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

The human-friendly display name for this audience.

sandbox
boolean

Indicates if this is a live or sandbox Application.

description
string

A description of the audience.

integration
string

The Talon.One-supported 3rd-party platform that this audience was created in.

For example, mParticle, Segment, Selligent, Braze, or Iterable.

Note: If you do not integrate with any of these platforms, do not use this property.

integrationId
string [ 1 .. 1000 ] characters

The ID of this audience in the third-party integration.

Note: To create an audience that doesn't come from a 3rd party platform, do not use this property.

createdIn3rdParty
boolean

Determines if this audience is a 3rd party audience or not.

lastUpdate
string <date-time>

The last time that the audience memberships changed.

Responses

Request samples

Content type
application/json
{
  • "name": "Travel audience",
  • "sandbox": true,
  • "description": "Travel audience 18-25",
  • "integration": "mparticle",
  • "integrationId": "382370BKDB946",
  • "createdIn3rdParty": false,
  • "lastUpdate": "2022-04-26T11:02:38.000Z"
}

Response samples

Content type
application/json
{
  • "accountId": 3886,
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "name": "Travel audience",
  • "sandbox": true,
  • "description": "Travel audience 18-25",
  • "integration": "mparticle",
  • "integrationId": "382370BKDB946",
  • "createdIn3rdParty": false,
  • "lastUpdate": "2022-04-26T11:02:38.000Z"
}

Delete audience

Delete an audience created by a third-party integration.

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

Note: Audiences can also be deleted via the Campaign Manager. See the docs.

path Parameters
audienceId
required
integer

The ID of the audience. You get it via the id property when creating an audience.

Responses

Response samples

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

Update audience name

Update the name of the given audience created by a third-party integration. Sending a request to this endpoint does not trigger the rule engine.

To update the audience's members, use the Update customer profile endpoint.

Authorizations:
api_key_v1
path Parameters
audienceId
required
integer

The ID of the audience. You get it via the id property when creating an audience.

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

The human-friendly display name for this audience.

Responses

Request samples

Content type
application/json
{
  • "name": "Travel audience"
}

Response samples

Content type
application/json
{
  • "accountId": 3886,
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "name": "Travel audience",
  • "sandbox": true,
  • "description": "Travel audience 18-25",
  • "integration": "mparticle",
  • "integrationId": "382370BKDB946",
  • "createdIn3rdParty": false,
  • "lastUpdate": "2022-04-26T11:02:38.000Z"
}

Delete audience memberships

Remove all members from this audience.

path Parameters
audienceId
required
integer

The ID of the audience. You get it via the id property when creating an audience.

Responses

Response samples

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

Update multiple customer profiles' audiences

Update the specified customer profiles with the specified audiences. Use this endpoint when customers join or leave audiences.

The limit of customer profiles per request is 1000.

Authorizations:
api_key_v1
Request Body schema: application/json
Array of objects <= 1000
Array
action
required
string
Enum: "add" "delete"

Defines the action to perform:

  • add: Adds the customer profile to the audience.
  • delete: Removes the customer profile from the audience.
profileIntegrationId
required
string <= 1000 characters

The ID of this customer profile in the third-party integration.

audienceId
required
integer

The ID of the audience. You get it via the id property when creating an audience.

Responses

Request samples

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

Response samples

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

Update profile attributes for all customers in audience

Update the specified profile attributes to the provided values for all customers in the specified audience.

Authorizations:
api_key_v1
path Parameters
audienceId
required
integer

The ID of the audience. You get it via the id property when creating an audience.

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

Responses

Request samples

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

Response samples

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

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.

Sync cart item catalog

Perform one or more of the following sync actions on this cart item catalog, up to 1000 actions:

  • Add an item to the catalog.
  • Edit the attributes of an item in the catalog.
  • Edit the attributes of more than one item in the catalog.
  • Remove an item from the catalog.
  • Remove more than one item from the catalog.

Note: For more information, see our documentation on managing cart item catalogs.

Filtering cart items

Use cart item attributes to filter items and select the ones you want to edit or delete when editing or deleting more than one item at a time.

The filters object contains the following properties:

  • attr: A cart item attribute connected to the catalog. It is applied to all items in the catalog.

  • op: The filtering operator indicating the relationship between the value of each cart item in the catalog and the value of the value property for the attribute selected in attr.

    The value of op can be one of the following:

    • EQ: Equal to value
    • LT: Less than value
    • LE: Less than or equal to value
    • GT: Greater than value
    • GE: Greater than or equal to value
    • IN: One of the comma-separated values that value is set to.

    Note: GE, LE, GT, LT are for numeric values only.

  • value: The value of the attribute selected in attr.

Payload examples

Synchronization actions are sent as PUT requests. See the structure for each action:

Adding an item to the catalog
{
  "actions": [
    {
      "payload": {
        "attributes": {
          "color": "Navy blue",
          "type": "shoe"
        },
        "replaceIfExists": true,
        "sku": "SKU1241028",
        "price": 100
      },
      "type": "ADD"
    }
  ]
}
Editing the attributes of an item in the catalog
{
  "actions": [
    {
      "payload": {
        "attributes": {
          "age": 11,
          "origin": "germany"
        },
        "createIfNotExists": false,
        "sku": "SKU1241028"
      },
      "type": "PATCH"
    }
  ]
}
Editing the attributes of several items at once
{
  "actions": [
    {
      "payload": {
        "attributes": {
          "color": "red"
        },
        "filters": [
          {
            "attr": "color",
            "op": "EQ",
            "value": "blue"
          }
        ]
      },
      "type": "PATCH_MANY"
    }
  ]
}
Removing an item from the catalog
{
  "actions": [
    {
      "payload": {
        "sku": "SKU1241028"
      },
      "type": "REMOVE"
    }
  ]
}
Removing several items from the catalog at once
{
  "actions": [
    {
      "payload": {
        "filters": [
          {
            "attr": "color",
            "op": "EQ",
            "value": "blue"
          }
        ]
      },
      "type": "REMOVE_MANY"
    }
  ]
}
Removing shoes of sizes above 45 from the catalog

Let's imagine that we have a shoe store and we have decided to stop selling shoes larger than size 45. We can remove from the catalog all the shoes of sizes above 45 with a single action:

{
  "actions": [
    {
      "payload": {
        "filters": [
          {
            "attr": "size",
            "op": "GT",
            "value": "45"
          }
        ]
      },
      "type": "REMOVE_MANY"
    }
  ]
}
path Parameters
catalogId
required
integer
Request Body schema: application/json
required
Array of objects [ 1 .. 1000 ] items
version
integer

The version number of the catalog to apply the actions on.

Responses

Request samples

Content type
application/json
{
  • "actions": [
    ],
  • "version": 244
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "modified": "2021-09-12T10:12:42Z",
  • "name": "seafood",
  • "description": "seafood catalog",
  • "subscribedApplicationsIds": [
    ],
  • "version": 6,
  • "createdBy": 6
}

Coupons

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

Create coupon reservation

Create a coupon reservation for specified customer profiles on the specified coupon. You can also create a reservation via the Campaign Manager using the Create coupon code reservation effect.

Reserving a coupon allows you to associate a coupon code to a given customer(s). You can then list the reserved coupons of a given customer with the List customer data endpoint.

If a coupon gets created for a specific user, it will automatically appear in their coupons.

When a user redeems a coupon, a reservation is automatically created after the redemption and the used coupon will be returned in the List customer data endpoint.

For example, you can use this endpoint and List customer data to create a coupon wallet by reserving coupon codes for a customer, and then displaying their coupon wallet when they visit your store.

Important

This endpoint creates a soft reservation. Any customer can use a reserved coupon code and proceed to checkout.

To create a hard reservation, you can:

To delete a reservation, use the Delete reservation endpoint.

Authorizations:
api_key_v1
path Parameters
couponValue
required
string

The code of the coupon.

Request Body schema: application/json
integrationIDs
required
Array of strings <= 1000 items

List of customer integration IDs.

Responses

Request samples

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

Response samples

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

Delete coupon reservations

Remove all the coupon reservations from the provided customer profile integration IDs and the provided coupon code.

Authorizations:
api_key_v1
path Parameters
couponValue
required
string

The code of the coupon.

Request Body schema: application/json
integrationIDs
required
Array of strings <= 1000 items

List of customer integration IDs.

Responses

Request samples

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

Response samples

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

List customers that have this coupon reserved

Return all customers that have this coupon marked as reserved.

Coupons are reserved in the following ways:

Authorizations:
api_key_v1
path Parameters
couponValue
required
string

The code of the coupon.

Responses

Response samples

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

Customer profiles

Represents the customer's information. For instance, their contact information.

Update customer profile

Update or create a Customer Profile. This endpoint triggers the Rule Builder.

You can use this endpoint to:

  • Set attributes on the given customer profile. Ensure you create the attributes in the Campaign Manager, first.
  • Modify the audience the customer profile is a member of.

Performance tips

Updating a customer profile returns a response with the requested integration state.

You can use the responseContent property to save yourself extra API calls. For example, you can get the customer profile details directly without extra requests.

Authorizations:
api_key_v1
path Parameters
integrationId
required
string

The integration identifier for this customer profile. Must be:

  • Unique within the deployment.
  • Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

Once set, you cannot update this identifier.

query Parameters
runRuleEngine
boolean
Default: false

Indicates whether to run the Rule Engine.

If true, the response includes:

  • The effects generated by the triggered campaigns are returned in the effects property.
  • The created coupons and referral objects.

If false:

  • The rules are not executed and the effects property is always empty.
  • The response time improves.
  • You cannot use responseContent in the body.
dry
boolean

Indicates whether to persist the changes. Changes are ignored when dry=true.

This property only works when runRuleEngine=true.

Request Body schema: application/json
object

Arbitrary properties associated with this item.

object
responseContent
Array of strings
Items Enum: "customerProfile" "triggeredCampaigns" "loyalty" "event" "awardedGiveaways" "ruleFailureReasons"

Optional list of extra data that you want to get in the response. Use this property to get as much data as you need in one request instead of sending extra requests to other endpoints.

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    },
  • "audiencesChanges": {
    },
  • "responseContent": [
    ]
}

Response samples

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

Update multiple customer profiles

Update (or create) up to 1000 customer profiles in 1 request.

The integrationId must be any identifier that remains stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

A customer profile can be linked to one or more sessions.

Authorizations:
api_key_v1
query Parameters
silent
string
Default: "yes"

Possible values: yes or no.

  • yes: Increases the perfomance of the API call by returning a 204 response.
  • no: Returns a 200 response that contains the updated customer profiles.
Request Body schema: application/json
Array of objects
Array
integrationId
required
string <= 1000 characters

The identifier of this profile, set by your integration layer. It must be unique within the account.

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

object

Arbitrary properties associated with this item.

Responses

Request samples

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

Response samples

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

Delete customer's personal data

Delete all attributes on the customer profile and on entities that reference this customer profile.

Important: To preserve performance, we recommend avoiding deleting customer data during peak-traffic hours.

Authorizations:
api_key_v1
path Parameters
integrationId
required
string

The integration ID of the customer profile. You can get the integrationId of a profile using:

Responses

Response samples

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

List customer data

Return the customer inventory regarding entities referencing this customer profile's integrationId.

Typical entities returned are: customer profile information, referral codes, loyalty points, loyalty cards and reserved coupons. Reserved coupons also include redeemed coupons.

You can also use this endpoint to get the projected loyalty balances in order to notify your customers about points that are about to expire, or to remind them how many points they have.

Authorizations:
api_key_v1
path Parameters
integrationId
required
string

The integration ID of the customer profile. You can get the integrationId of a profile using:

query Parameters
profile
boolean

Set to true to include customer profile information in the response.

referrals
boolean

Set to true to include referral information in the response.

coupons
boolean

Set to true to include coupon information in the response.

loyalty
boolean

Set to true to include loyalty information in the response.

giveaways
boolean

Set to true to include giveaways information in the response.

loyaltyProjectionEndDate
string <date-time>

Set an end date to query the projected loyalty balances. You can project results up to 31 days from today.

Responses

Response samples

Content type
application/json
{
  • "profile": {
    },
  • "loyalty": {
    },
  • "referrals": [
    ],
  • "coupons": [
    ],
  • "giveaways": [
    ]
}

Customer sessions

Represents the data related to a customer session. Typically, a customer session is the value and content of the customer's cart.

Sessions can be anonymous or linked to a customer profile and they have a life cycle from open to closed. In general, a session is closed when the customer completes the checkout step.

Sessions are a key concept of Talon.One. We strongly recommend you read the documentation about customer sessions.

Update customer session

Update or create a customer session. For example, use this endpoint to share the content of a customer's cart with Talon.One. The endpoint responds with the potential promotion rules that match the current cart.

Note: The currency for the session and the cart items in the session is the same as the Application that owns this session.

Session management

The Talon.One platform supports multiple simultaneous sessions for the same profile. If you have multiple ways of accessing the same Application you can either:

  • Track multiple independent sessions or,
  • Use the same session across all of them.

You should share sessions when application access points share other state, such as the user's cart. If two points of access to the application have independent states, for example a user can have different items in their cart across the two) they should use independent customer session ID's.

For more information, see the docs.

Sessions and customer profiles

  • To link a session to a customer profile, set the profileId parameter in the request body to a customer profile's integrationId.
  • While you can create an anonymous session with profileId="", we recommend you use a guest ID instead.

Note: You do not have to create a customer profile first. If the specified profile does not exist, an empty profile is created automatically.

Performance tips

Updating a customer session returns a response with the requested integration state. Use the responseContent property to save yourself extra API calls. For example, you can get the customer profile details directly without extra requests.

For more information, see the integration tutorial.

Authorizations:
api_key_v1
path Parameters
customerSessionId
required
string

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

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

query Parameters
dry
boolean

Indicates whether to persist the changes. Changes are ignored when dry=true.

Request Body schema: application/json
required
object
responseContent
Array of strings
Items Enum: "customerSession" "customerProfile" "coupons" "triggeredCampaigns" "referral" "loyalty" "event" "awardedGiveaways" "ruleFailureReasons" "previousReturns"

Optional list of extra data that you want to get in the response. Use this property to get as much data as you need in one request instead of sending extra requests to other endpoints.

Responses

Request samples

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

Response samples

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

Get customer session

Get the details of the given customer session.

You can get the same data via other endpoints that also apply changes, which can help you save requests and increase performance. See:

Authorizations:
api_key_v1
path Parameters
customerSessionId
required
string

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

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

Responses

Response samples

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

Return cart items

Create a new return request for the specified cart items.

This endpoint automatically changes the session state from closed to partially_returned.

Its behavior depends on whether cart item flattening is enabled for the Application.

Note: This will roll back any effects associated with these cart items. For more information, see our documentation on session states and this tutorial.

Authorizations:
api_key_v1
path Parameters
customerSessionId
required
string

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

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

query Parameters
dry
boolean

Indicates whether to persist the changes. Changes are ignored when dry=true.

Request Body schema: application/json
required
object
responseContent
Array of strings
Items Enum: "customerSession" "customerProfile" "coupons" "triggeredCampaigns" "referral" "loyalty" "event" "previousReturns"

Optional list of extra data that you want to get in the response. Use this property to get as much data as you need in one request instead of sending extra requests to other endpoints.

Responses

Request samples

Content type
application/json
{
  • "return": {
    },
  • "responseContent": [
    ]
}

Response samples

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

Events

Represents a single occurrence of various customer actions. There are 2 versions:

  • For V1 events, each customer session contains one or more events. For example, updating a customer session records a talon_session_updated event.
  • For V2 events, each customer profile contains one or more events. For example, updating a customer session records a talon_session_updated event linked to the profile in question.

Track event

Deprecation warning

This endpoint is DEPRECATED and will be sunset on Dec 31st 2022. Use Track Event V2 instead.

See Migrating to V2.

Triggers a custom event in a customer session. You can then check this event in your rules.

Before using this endpoint, create your event as a custom attribute of type event.

An event is always part of a session. If either the profile or the session does not exist, a new empty profile/session is created. If the specified session already exists, it must belong to the same profileId or an error will be returned.

Authorizations:
api_key_v1
query Parameters
dry
boolean

Indicates whether to persist the changes. Changes are ignored when dry=true.

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

A string representing the event. Must not be a reserved event name.

required
object

Arbitrary additional JSON data associated with the event.

sessionId
required
string non-empty

The ID of the session that this event occurred in.

profileId
string

ID of the customer profile set by your integration layer.

Note: If the customer does not yet have a known profileId, we recommend you use a guest profileId.

Responses

Request samples

Content type
application/json
{
  • "profileId": "URNGV8294NV",
  • "type": "pageViews",
  • "attributes": {
    },
  • "sessionId": "175KJPS947296"
}

Response samples

Content type
application/json
{
  • "session": {
    },
  • "profile": {
    },
  • "event": {
    },
  • "loyalty": {
    },
  • "coupon": {
    }
}

Track event V2

Triggers a custom event. You can build a condition around this event in your rules.

Talon.One offers a set of built-in events. Ensure you do not create a custom event when you can use a built-in event.

For example, use this endpoint to trigger an event when a customer shares a link to a product. See the tutorial.

Important:

  • profileId is required. An event V2 is associated with a customer profile.
  • Before using this endpoint, create your event as a custom attribute of type event. See the Developer docs.
Authorizations:
api_key_v1
query Parameters
silent
string
Default: "yes"

Possible values: yes or no.

  • yes: Increases the perfomance of the API call by returning a 204 response.
  • no: Returns a 200 response that contains the updated customer profiles.
dry
boolean

Indicates whether to persist the changes. Changes are ignored when dry=true.

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

A string representing the event. Must not be a reserved event name.

profileId
string

ID of the customer profile set by your integration layer.

Note: If the customer does not yet have a known profileId, we recommend you use a guest profileId.

object

Arbitrary additional JSON data associated with the event.

responseContent
Array of strings
Items Enum: "customerProfile" "triggeredCampaigns" "loyalty" "event" "awardedGiveaways" "ruleFailureReasons"

Optional list of requested information to be present on the response related to the tracking custom event.

Responses

Request samples

Content type
application/json
{
  • "profileId": "URNGV8294NV",
  • "type": "email_opened",
  • "attributes": {
    },
  • "responseContent": [
    ]
}

Response samples

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

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.

Get loyalty ledger balances

Retrieve loyalty ledger balances for the given Integration ID in the specified loyalty program. You can filter balances by date. If no filtering options are applied, you retrieve all loyalty balances on the current date for the given integration ID.

Loyalty balances are calculated when Talon.One receives your request using the points stored in our database, so retrieving a large number of balances at once can impact performance.

Note: For more information, see our documentation on managing loyalty data.

Authorizations:
api_key_v1
path Parameters
loyaltyProgramId
required
integer

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

integrationId
required
string

The integration identifier for this customer profile. Must be:

  • Unique within the deployment.
  • Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

Once set, you cannot update this identifier.

query Parameters
endDate
string <date-time>

Only return results older than this timestamp. It must be an RFC3339 timestamp string.

Responses

Response samples

Content type
application/json
{
  • "balance": {
    },
  • "subledgerBalances": {
    }
}

Get loyalty ledger transaction logs

Retrieve paginated results of loyalty transaction logs for the given Integration ID in the specified loyalty program. You can filter transactions by date. If no filters are applied, the last 50 loyalty transactions for the given integration ID are returned.

Authorizations:
api_key_v1
path Parameters
loyaltyProgramId
required
integer

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

integrationId
required
string

The integration identifier for this customer profile. Must be:

  • Unique within the deployment.
  • Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

Once set, you cannot update this identifier.

query Parameters
subledgerId
string

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

startDate
string <date-time>

Time from which results are returned. It must be an RFC3339 timestamp string.

endDate
string <date-time>

Only return results older than this timestamp. It must be an RFC3339 timestamp string.

pageSize
integer [ 1 .. 1000 ]

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

skip
integer

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

Responses

Response samples

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

Loyalty cards

Represents loyalty cards.

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

Link customer profile to loyalty card

Loyalty cards allow customers to collect and spend loyalty points within a card-based loyalty program. They are useful to gamify loyalty programs and can be used with or without customer profiles linked to them.

Link a customer profile to a given loyalty card for the card to be set as Registered. This affects how it can be used. See the docs.

Note: You can link as many customer profiles to a given loyalty card as the card user limit allows.

path Parameters
loyaltyProgramId
required
integer

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

loyaltyCardIdentifier
required
string <= 108 characters

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

Request Body schema: application/json
integrationId
required
string

The integrationId of the customer profile.

Responses

Request samples

Content type
application/json
{
  • "integrationId": "R195412"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "programID": 125,
  • "status": "active",
  • "identifier": "summer-loyalty-card-0543",
  • "usersPerCardLimit": 111,
  • "profiles": [
    ],
  • "ledger": {
    },
  • "subledgers": {
    },
  • "modified": "2021-09-12T10:12:42Z"
}

Get loyalty balances for a loyalty card

Retrieve loyalty balances for the given loyalty card in the specified loyalty program with filtering options applied. If no filtering options are applied, all loyalty balances for the given loyalty card are returned.

Authorizations:
api_key_v1
path Parameters
loyaltyProgramId
required
integer

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

loyaltyCardIdentifier
required
string <= 108 characters

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

query Parameters
endDate
string <date-time>

Only return results older than this timestamp. It must be an RFC3339 timestamp string.

Responses

Response samples

Content type
application/json
{
  • "balance": {
    },
  • "subledgerBalances": {
    }
}

Get loyalty card transaction logs

Retrieve loyalty transaction logs for the given loyalty card in the specified 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:
api_key_v1
path Parameters
loyaltyProgramId
required
integer

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

loyaltyCardIdentifier
required
string <= 108 characters

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

query Parameters
subledgerId
string

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

startDate
string <date-time>

Time from which results are returned. It must be an RFC3339 timestamp string.

endDate
string <date-time>

Only return results older than this timestamp. It must be an RFC3339 timestamp string.

pageSize
integer [ 1 .. 1000 ]

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

skip
integer

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

Responses

Response samples

Content type
application/json
{
  • "created": "2022-01-02T15:04:05Z07:00",
  • "programId": 324,
  • "cardIdentifier": "summer-loyalty-card-0543",
  • "customerSessionId": "05c2da0d-48fa-4aa1-b629-898f58f1584d",
  • "type": "addition",
  • "name": "Reward 10% points of a purchase's current total",
  • "startDate": "2022-01-02T15:04:05Z07:00",
  • "expiryDate": "2022-01-02T15:04:05Z07:00",
  • "subledgerId": "sub-123",
  • "amount": 10.25,
  • "id": 123,
  • "rulesetId": 11,
  • "ruleName": "Add 2 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.

Create referral code for an advocate

Creates a referral code for an advocate. The code will be valid for the referral campaign for which is created, indicated in the campaignId parameter, and will be associated with the profile specified in the advocateProfileIntegrationId parameter as the advocate's profile.

Authorizations:
api_key_v1
Request Body schema: application/json
campaignId
required
integer

ID of the campaign from which the referral received the referral code.

advocateProfileIntegrationId
required
string <= 1000 characters

The Integration ID of the Advocate's Profile.

startDate
string <date-time> >= 0

Timestamp at which point the referral code becomes valid.

expiryDate
string <date-time> >= 0

Expiry date of the referral code. Referral never expires if this is omitted, zero, or negative.

usageLimit
integer [ 0 .. 999999 ]

The number of times a referral code can be used. 0 means no limit but any campaign usage limits will still apply.

friendProfileIntegrationId
string

An optional Integration ID of the Friend's Profile.

object

Arbitrary properties associated with this item.

Responses

Request samples

Content type
application/json
{
  • "startDate": "2020-11-10T23:00:00Z",
  • "expiryDate": "2021-11-10T23:00:00Z",
  • "usageLimit": 1,
  • "campaignId": 78,
  • "advocateProfileIntegrationId": "URNGV8294NV",
  • "friendProfileIntegrationId": "BZGGC2454PA",
  • "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": 0,
  • "code": "27G47Y54VH9L",
  • "usageCounter": 1,
  • "batchId": "tqyrgahe"
}

Create referral codes for multiple advocates

Creates unique referral codes for multiple advocates. The code will be valid for the referral campaign for which it is created, indicated in the campaignId parameter, and one referral code will be associated with one advocate using the profile specified in the advocateProfileIntegrationId parameter as the advocate's profile.

Authorizations: