8th May 2019

API Reference

The Integration API is how you push data into the Talon.One environment. You can create profiles for your customers, sessions to group their activity, and custom events to track specific actions that do not fit into the session data model.

You will need Authentication to make requests to the API.

#

Update a Customer Profile

PUT  /v1/customer_profiles/{integrationId}

Update (or create) a Customer Profile. This profile information can then be matched and/or updated by campaign Rules.

The integrationId may be any identifier that will remain stable for the customer. For example, you might use a database ID, an email, or a phone number as the integrationId. It is vital that this ID not change over time, so don't use any identifier that the customer can update themselves. E.g. if your application allows a customer to update their e-mail address, you should instead use a database ID.

Updating a customer profile will return a response with the full integration state. This includes the current state of the customer profile, the customer session, the event that was recorded, and an array of effects that took place.

Example

Request Schema

URL Parameter

integrationId
string required

The custom identifier for this profile, must be unique within the account.

Body Parameter

attributes
object

Arbitrary properties associated with this item

Response Schema

session
object

Customer Session

integrationId
string required format: string

The ID used for this entity in the application system.

created
string required format: date-time

The exact moment this entity was created.

applicationId
integer required

The ID of the application that owns this entity.

profileId
string required

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

coupon
string required

Any coupon code entered.

referral
string required

Any referral code entered.

state
string required default: open

Indicates the current state of the session. All sessions must start in the "open" state, after which valid transitions are...

  1. open -> closed
  2. open -> cancelled
  3. closed -> cancelled
cartItems
array required

Serialized JSON representation.

name
string required minlength: 1

Serialized JSON representation.

sku
string required minlength: 1

Serialized JSON representation.

quantity
integer required format: 1

Serialized JSON representation.

price
number required

Serialized JSON representation.

category
string required

Serialized JSON representation.

weight
number required

Weight of item in mm

height
number required

Height of item in mm

width
number required

Width of item in mm

length
number required

Length of item in mm

position
number required

Position of the Cart Item in the Cart (calculated internally)

attributes
object required

Arbitrary properties associated with this item

adjustment
array required

Serialized JSON representation.

total
number required

The total sum of the cart in one session.

attributes
object required

A key-value map of the sessions attributes. The potentially valid attributes are configured in your accounts developer settings.

firstSession
boolean required

Indicates whether this is the first session for the customer's profile. Will always be true for anonymous sessions.

discounts
object required

A map of labelled discount values, values will be in the same currency as the application associated with the session.

profile
object

Customer Profile

integrationId
string required format: string

The ID used for this entity in the application system.

created
string required format: date-time

The exact moment this entity was created.

attributes
object required

Arbitrary properties associated with this item

accountId
integer required

The ID of the Talon.One account that owns this profile.

closedSessions
integer required

The total amount of closed sessions by a customer. A closed session is a successful purchase.

totalSales
number required

Sum of all purchases made by this customer

loyaltyMemberships
array required

A list of loyalty programs joined by the customer

joined
string required format: date-time

The moment in which the loyalty program was joined.

loyaltyProgramId
integer required

The ID of the loyalty program belonging to this entity.

lastActivity
string required format: date-time

Timestamp of the most recent event received from this customer

event
object

Event

id
integer required

Unique ID for this entity.

created
string required format: date-time

The exact moment this entity was created.

applicationId
integer required

The ID of the application that owns this entity.

profileId
string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

sessionId
string required minlength: 1

The ID of the session that this event occurred in.

type
string required minlength: 1

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

attributes
object required

Arbitrary additional JSON data associated with the event.

effects
array required

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

effects
array required

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

ledgerEntries
array required

Ledger entries for the event.

meta
object

Event

campaigns
object

Maps each evaluated campaign ID to a key-value list of that campaigns attributes. Campaigns without attributes will be omitted.

coupons
object

Maps the coupon value to a key-value list of that coupons attributes.

couponRejectionReason
object

Event

warnings
object

Event

loyalty
object optional

Loyalty program information

programs
object required optional

A map holding information about the loyalty programs balance

#

Update a Customer Session

PUT  /v1/customer_sessions/{customerSessionId}

Update (or create) a Customer Session. For example, the items in a customers cart are part of a session.

The Talon.One platform supports multiple simultaneous sessions for the same profile, so if you have multiple ways of accessing the same application you have the option of either tracking multiple independent sessions or using the same session across all of them. You should share sessions when application access points share other state, such as the users cart. If two points of access to the application have independent state (e.g. a user can have different items in their cart across the two) they should use independent customer session ID's.

The profileId parameter in the request body should correspond to an integrationId for a customer profile, to track an anonymous session use the empty string ("") as the profileId. Note that you do not need to create a customer profile first: if the specified profile does not yet exist, an empty profile will be created automatically.

Updating a customer profile will return a response with the full integration state. This includes the current state of the customer profile, the customer session, the event that was recorded, and an array of effects that took place.

The currency for the session and the cart items in the session is the same as that of the application with which the session is associated.

Example

Request Schema

URL Parameter

customerSessionId
string required

The custom identifier for this session, must be unique within the account.

Body Parameter

profileId
string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

coupon
string

Any coupon code entered.

referral
string

Any referral code entered.

state
string default: open open,closed,cancelled

Indicates the current state of the session. All sessions must start in the "open" state, after which valid transitions are...

  1. open -> closed
  2. open -> cancelled
  3. closed -> cancelled
cartItems
array

Serialized JSON representation.

name
string required minlength: 1

Serialized JSON representation.

sku
string required minlength: 1

Serialized JSON representation.

quantity
integer required format: 1

Serialized JSON representation.

price
number required

Serialized JSON representation.

category
string

Serialized JSON representation.

weight
number

Weight of item in mm

height
number

Height of item in mm

width
number

Width of item in mm

length
number

Length of item in mm

position
number

Position of the Cart Item in the Cart (calculated internally)

attributes
object

Arbitrary properties associated with this item

adjustment
array

Serialized JSON representation.

total
number

The total sum of the cart in one session.

attributes
object

A key-value map of the sessions attributes. The potentially valid attributes are configured in your accounts developer settings.

Response Schema

session
object

Customer Session

integrationId
string required format: string

The ID used for this entity in the application system.

created
string required format: date-time

The exact moment this entity was created.

applicationId
integer required

The ID of the application that owns this entity.

profileId
string required

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

coupon
string required

Any coupon code entered.

referral
string required

Any referral code entered.

state
string required default: open

Indicates the current state of the session. All sessions must start in the "open" state, after which valid transitions are...

  1. open -> closed
  2. open -> cancelled
  3. closed -> cancelled
cartItems
array required

Serialized JSON representation.

name
string required minlength: 1

Serialized JSON representation.

sku
string required minlength: 1

Serialized JSON representation.

quantity
integer required format: 1

Serialized JSON representation.

price
number required

Serialized JSON representation.

category
string required

Serialized JSON representation.

weight
number required

Weight of item in mm

height
number required

Height of item in mm

width
number required

Width of item in mm

length
number required

Length of item in mm

position
number required

Position of the Cart Item in the Cart (calculated internally)

attributes
object required

Arbitrary properties associated with this item

adjustment
array required

Serialized JSON representation.

total
number required

The total sum of the cart in one session.

attributes
object required

A key-value map of the sessions attributes. The potentially valid attributes are configured in your accounts developer settings.

firstSession
boolean required

Indicates whether this is the first session for the customer's profile. Will always be true for anonymous sessions.

discounts
object required

A map of labelled discount values, values will be in the same currency as the application associated with the session.

profile
object

Customer Profile

integrationId
string required format: string

The ID used for this entity in the application system.

created
string required format: date-time

The exact moment this entity was created.

attributes
object required

Arbitrary properties associated with this item

accountId
integer required

The ID of the Talon.One account that owns this profile.

closedSessions
integer required

The total amount of closed sessions by a customer. A closed session is a successful purchase.

totalSales
number required

Sum of all purchases made by this customer

loyaltyMemberships
array required

A list of loyalty programs joined by the customer

joined
string required format: date-time

The moment in which the loyalty program was joined.

loyaltyProgramId
integer required

The ID of the loyalty program belonging to this entity.

lastActivity
string required format: date-time

Timestamp of the most recent event received from this customer

event
object

Event

id
integer required

Unique ID for this entity.

created
string required format: date-time

The exact moment this entity was created.

applicationId
integer required

The ID of the application that owns this entity.

profileId
string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

sessionId
string required minlength: 1

The ID of the session that this event occurred in.

type
string required minlength: 1

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

attributes
object required

Arbitrary additional JSON data associated with the event.

effects
array required

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

effects
array required

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

ledgerEntries
array required

Ledger entries for the event.

meta
object

Event

campaigns
object

Maps each evaluated campaign ID to a key-value list of that campaigns attributes. Campaigns without attributes will be omitted.

coupons
object

Maps the coupon value to a key-value list of that coupons attributes.

couponRejectionReason
object

Event

warnings
object

Event

loyalty
object optional

Loyalty program information

programs
object required optional

A map holding information about the loyalty programs balance

#

Track an Event

POST  /v1/events

Records an arbitrary event in a customer session. For example, an integration might record an event when a user updates their payment information.

The sessionId body parameter is required, an event is always part of a session. Much like updating a customer session, if either the profile or the session do not exist, a new empty one will be created. Note that if the specified session already exists, it must belong to the same profileId or an error will be returned.

As with customer sessions, you can use an empty string for profileId to indicate that this is an anonymous session.

Updating a customer profile will return a response with the full integration state. This includes the current state of the customer profile, the customer session, the event that was recorded, and an array of effects that took place.

Example

Request Schema

Body Parameter

profileId
string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

sessionId
string required minlength: 1

The ID of the session that this event occurred in.

type
string required minlength: 1

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

attributes
object required

Arbitrary additional JSON data associated with the event.

Response Schema

session
object

Customer Session

integrationId
string required format: string

The ID used for this entity in the application system.

created
string required format: date-time

The exact moment this entity was created.

applicationId
integer required

The ID of the application that owns this entity.

profileId
string required

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

coupon
string required

Any coupon code entered.

referral
string required

Any referral code entered.

state
string required default: open

Indicates the current state of the session. All sessions must start in the "open" state, after which valid transitions are...

  1. open -> closed
  2. open -> cancelled
  3. closed -> cancelled
cartItems
array required

Serialized JSON representation.

name
string required minlength: 1

Serialized JSON representation.

sku
string required minlength: 1

Serialized JSON representation.

quantity
integer required format: 1

Serialized JSON representation.

price
number required

Serialized JSON representation.

category
string required

Serialized JSON representation.

weight
number required

Weight of item in mm

height
number required

Height of item in mm

width
number required

Width of item in mm

length
number required

Length of item in mm

position
number required

Position of the Cart Item in the Cart (calculated internally)

attributes
object required

Arbitrary properties associated with this item

adjustment
array required

Serialized JSON representation.

total
number required

The total sum of the cart in one session.

attributes
object required

A key-value map of the sessions attributes. The potentially valid attributes are configured in your accounts developer settings.

firstSession
boolean required

Indicates whether this is the first session for the customer's profile. Will always be true for anonymous sessions.

discounts
object required

A map of labelled discount values, values will be in the same currency as the application associated with the session.

profile
object

Customer Profile

integrationId
string required format: string

The ID used for this entity in the application system.

created
string required format: date-time

The exact moment this entity was created.

attributes
object required

Arbitrary properties associated with this item

accountId
integer required

The ID of the Talon.One account that owns this profile.

closedSessions
integer required

The total amount of closed sessions by a customer. A closed session is a successful purchase.

totalSales
number required

Sum of all purchases made by this customer

loyaltyMemberships
array required

A list of loyalty programs joined by the customer

joined
string required format: date-time

The moment in which the loyalty program was joined.

loyaltyProgramId
integer required

The ID of the loyalty program belonging to this entity.

lastActivity
string required format: date-time

Timestamp of the most recent event received from this customer

event
object

Event

id
integer required

Unique ID for this entity.

created
string required format: date-time

The exact moment this entity was created.

applicationId
integer required

The ID of the application that owns this entity.

profileId
string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

sessionId
string required minlength: 1

The ID of the session that this event occurred in.

type
string required minlength: 1

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

attributes
object required

Arbitrary additional JSON data associated with the event.

effects
array required

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

effects
array required

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

ledgerEntries
array required

Ledger entries for the event.

meta
object

Event

campaigns
object

Maps each evaluated campaign ID to a key-value list of that campaigns attributes. Campaigns without attributes will be omitted.

coupons
object

Maps the coupon value to a key-value list of that coupons attributes.

couponRejectionReason
object

Event

warnings
object

Event

loyalty
object optional

Loyalty program information

programs
object required optional

A map holding information about the loyalty programs balance

#

Create a referral code for an advocate

POST  /v1/referrals

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.

Example

Request Schema

Body Parameter

campaignId
integer required

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

advocateProfileIntegrationId
string required

The Integration Id of the Advocate's Profile

friendProfileIntegrationId
string

An optional Integration ID of the Friend's Profile

startDate
string format: date-time

Timestamp at which point the referral code becomes valid.

expiryDate
string format: date-time

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

Response Schema

id
integer

Unique ID for this entity.

created
string format: date-time

The exact moment this entity was created.

campaignId
integer

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

advocateProfileIntegrationId
string

The Integration Id of the Advocate's Profile

friendProfileIntegrationId
string optional

An optional Integration ID of the Friend's Profile

startDate
string optional format: date-time

Timestamp at which point the referral code becomes valid.

expiryDate
string optional format: date-time

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

code
string minlength: 4

The actual referral code.

usageCounter
integer

The number of times this referral code has been successfully used.

usageLimit
integer

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.

#

Delete the personal data of a customer.

DELETE  /v1/customer_data/{integrationId}

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

Example

Request Schema

URL Parameter

integrationId
string required

The custom identifier for this profile, must be unique within the account.

Response Schema

Still need help? Get in touch!
Last updated on 8th May 2019

Was this article helpful?

Thank you! You have already voted

If you’d like a member of our support team to respond to you, please send a note to support@talon.one