Core Loyalty APIs
The APIs featured in this grouping enable organizations to incentivize customers to stay engaged with long-term and expanding customer loyalty programs. Services manage a variety of entities that are critical to building consumer loyalty, including APIs for the following:
All of the sections that follow document these APIs, except for the first. The section below details how enabling loyalty settings can influence response objects returned by many APIs.
Effects of Loyalty Settings on Response Objects
As an organization builds out its SessionM implementation, a powerful interdependence develops between the data served by loyalty APIs and the data that expresses information about customers.
When loyalty settings are enabled and loyalty data exists, additional attributes are introduced to response objects across the platform. Many of these objects contain attributes that correspond to a customer's access and redemption of credit, which often manifests as points.
For example, the Rewards Store API exposes a method that retrieves all rewards for an organization or with respect to a specified customer, and the Orders API contains a method for creating orders for those rewards. In accord with these activities, the Points API tracks the history of a customer accumulating and redeeming these points. Over time, a variety of transactions can occur, and, as they do, the associated customer's points balance increases and decreases.
Since these balances belong to customers, many of the JSON responses that reflect express customer data contain attributes related to loyalty balances. Whether or not such data displays in the JSON responses is governed by the enable_mpoints_info_in_customers_api setting, which is accessed via the SessionM Admin Portal. For more information, consult your Customer Success contact.
The sections below discuss the conditional attributes that can be enabled for each of the relevant APIs.
Loyalty Data in Customer Objects
Loyalty data can augment customer objects within JSON responses returned by the following APIs:
- Standard Profile API
- Custom Profile API
- Events API
When the enable_mpoints_info_in_users_api setting is enabled, the customer data in response objects can be augmented by two attributes: available_points, an integer that specifies the number of points available to the customer; and unclaimed_achievement_count, an integer that specifies the number of unclaimed points currently available to the customer.
One example of this condition is the response object shown below, which is returned when retrieving an authorization token with a custom profile:
{
"status": "ok",
"user": {
"account_status": "good",
"auth_token": "v2--5W8kaVGHoUpxcm98nrmtp287KVHZChE9hXWaagYeXJw=--hUvxfLBwMdTBUCwiYLSi7YNv6gMOYQYsOZJyxM1OjemkAR0K9dqRj6f-hvei1K8MNA==",
"available_points": 0,
"created_at": "2016-10-21 18:12:22",
"dob": "1980-01-01",
"email": "john.smith@fake.email.addr",
"external_id": "654321",
"gender": "m",
"id": "e9c2bbfe-97b9-11e6-9663-271bc1d29f66",
"proxy_ids": [],
"registered_at": "2016-10-21 18:12:22",
"suspended": false,
"unclaimed_achievement_count": 0,
"updated_at": "2016-10-21 18:12:22",
"user_profile": {
"_version": 1,
"user_title":"mr",
"program_tier":4,
"locale":"fr-ca"
}
}
}
The following table provides details on each of the conditions for which a user object in a JSON response contains loyalty data:
API | Endpoints | Description |
---|---|---|
Standard Profile | POST /priv/v1/apps/:api_key/users
GET /priv/v1/apps/:api_key/users/:user_id GET /priv/v1/apps/:api_key/external/users/:external_id GET /priv/v1/apps/:api_key/users/ PUT /priv/v1/apps/:api_key/users/:user_id PUT /priv/v1/apps/:api_key/external/users/:external_id DELETE /priv/v1/apps/:api_key/users/:user_id GET /priv/v1/apps/:api_key/users/search?email=test@example.com |
Loyalty data resides in JSON response objects returned by endpoints that create, retrieve, update, delete or search standard profiles. |
Custom Profile | PUT /priv/v1/apps/:api_key/users/:user_id
GET /priv/v1/apps/:api_key/users/:user_id?user[user_profile]=true |
Loyalty data resides in JSON response objects returned by endpoints that retrieve or update combined standard and custom profiles. |
Places | POST /priv/v1/apps/:api_key/places/:place_id/check_ins
POST /priv/v1/apps/:api_key/users/:user_id/places/:place_id/check_ins |
Loyalty data resides in JSON response objects returned by endpoints that check a user into a place. |
Events | POST /priv/v1/apps/:api_key/users/:user_id/events
POST /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/events POST /priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/events POST /priv/v1/apps/:api_key/external/users/:external_id/events POST /priv/v1/apps/:api_key/external/users/:external_id/external/campaigns/:permalink/events POST /priv/v1/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/events |
Loyalty data resides in JSON response objects returned by endpoints that create basic activity and purchase events. |
Loyalty Data in Eligible Campaigns Objects
Loyalty data can augment JSON responses returned by the Eligible Campaigns API.
Provided there are points-related activities (points orders) in the system, the points array is part of the returned activities object; if no activities exist, the data for that section is omitted. The points array contains objects with the following attributes: behavior_id, an integer that specifies the action identifier; campaign_id, an integer for the internal campaign identifier; points, an integer that specifies any existing point values; transaction_id, a string that specifies an identifier for the transaction that triggered the action; and type, a string that specifies the type of action.
This condition applies to the response object shown below, which is returned when retrieving a customer's completed activities:
{
"activities": {
"points": [
{
"behavior_id": 8591,
"campaign_id": 4197,
"points": 0,
"transaction_id": "30114377",
"type": "points"
} ],
"orders": [
{
"id": 2343,
"campaign_id": 4198,
"receipt_id": 3453,
"behavior_id": 3234,
"type": "offer",
"header": "offer header",
"subheader": "offer subheader",
"description": "this is an offer description",
"icon_url": "http://www.aniconhere.com",
"image_url": "http://www.animagehere.com",
"redeem_url": "http://www.aredeemhere.com",
"state": "reviewed",
"offer_id": 235
} ]
}
}
The following table provides details on the condition for which an activities object in a JSON response contains loyalty data:
API | Endpoints | Description |
---|---|---|
Eligible Campaigns | GET /priv/v1/apps/:api_key/users/:user_id/activities
GET /priv/v1/apps/:api_key/external/users/:external_id/activities |
Loyalty data resides in JSON response objects returned by endpoints that retrieve completed activities for a customer. |
Rewards Store API
In the SessionM Platform, the Rewards Store API contains a few endpoints for retrieving a list of rewards (represented by offer objects) available either across an organization or to a specific customer. Individual customers can purchase items in a client's digital rewards store by redeeming points or other loyalty currency.
While rewards can be made available to an organization, whether or not a specific customer can redeem points or other loyalty currency for a reward is subject to several factors such as a customer's age and point balance. For example, if the customer has insufficient points for the redemption, the reward will not be redeemable for them, though they can still see it in the store view. For information on how this API's endpoints determine how the response object is structured, see "Endpoint Parameters" section below.
Reward types largely match incentive types, as both, at their core, are simply things of value. Incentive types include:
- Offers - A digital coupon for a predetermined deal such as 15% off a particular item. For instance, if a Client sells clothing, an offer could be “15% off any sweater” or “a free t-shirt.”
- Gift cards - A preset denomination of currency (e.g., “$25”) for a specific retailer (e.g. Amazon) tied to a unique code that can be entered during an online checkout.
- Physical prizes - A tangible good that a fulfillment vendor will ship to the customer, such as a t-shirt or kid’s toy.
- Sweepstakes entries - An entry into a contest where winners are drawn at random from the total entrant pool to determine who wins the advertised prize.
- Charity donations - A monetary gift to a specified non-profit organization.
This assortment of reward types allows clients to design reward stores that motivate customers to complete those actions that earn them points, while SessionM can provide all the services necessary to fulfill orders for any of these reward types. Note that SessionM can provide several services: reporting that details customer order histories, and internationalization so that orders can be in multiple languages and countries.
Used for rewards stores, this API can reward customers in some type of loyalty program in which they can earn points. The act of redeeming points or other loyalty currency for a reward boosts engagement in promotional programs.
Rewards are tied closely to orders. The Orders API can be employed to place an order against a reward; the Orders API also supports fraud tracking and analysis for these transactions.
Reward redemptions can be tied to incentives as part of campaigns to drive desired actions in an application. Note that campaigns are not built using the Campaigns API but rather are configured in the platform via the SessionM Administration Portal.
The platform supports an “options" function, which allows you to create rewards that share a common data structure. As such, a reward can be standalone with no options, or it can be built with options so that it can contain nested reward variants. Alternatively, the Rewards Store API supports custom data structures, which are supported on a per-client basis. This is useful if your reward store has fields that are specific to your use case.
This API provides a method that returns a list of rewards available to either an organization's customer base or to a specific customer. Note that rewards are created via the SessionM Administration Portal, not via this API.
Retrieve a List of Rewards for an Eligible Customer
Retrieves a list of rewards available to either an organization's customer base or to a specific customer. Note that the endpoints that utilize only the api_key and a locale, with (or without) a user_id or an external_id, are available for registered customers (users); however, GET /api/v1/apps/:api_key/offers?auth_token=xxxxx applies to unregistered, anonymous customers.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/offers?locale=en-us
GET /priv/v1/apps/:api_key/users/:user_id/offers?locale=es-us
GET /priv/v1/apps/:api_key/external/users/:external_id/offers?locale=en-ca
GET /api/v1/apps/:api_key/offers?auth_token=xxxxx
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
locale | Used for internationalization. |
If you choose to specify only the api_key parameter in the endpoint, this method returns all of the rewards defined for the organization.
If you choose to supplement the api_key with either the user_id or external_id parameter in the endpoint, this method returns the rewards as they correspond to a specific customer. The reward's availability is shown in the response object (featured below) returned by the method; in particular, its availability displays in the offer object's status attribute. For more information on the offer object in a response and its status attribute, see the "Response Object" section below along with Reward Statuses.
Request Object
Not applicable.
Response Object
In addition to a status value-pair for the transaction, the response object returned by the method contains an offer object, as shown below:
{
"status": "ok",
"offer":
{
"id":4321,
"name":"Name of offer",
"type":"merchandise",
"description":"a description",
"points":100,
"start_time":"2016-02-02T17:08:29Z",
"end_time":"2016-03-02T17:08:29Z",
"weight": 100,
"featured": true,
"tier":"gold",
"status":"verification_required",
"requires_skills_test":false,
"logo":"http://content.sessionm.com/offers/2/logo.png",
"data":{ "example" : "example" },
"options":[
{
"id":2,
"name":"Name of offer variant A",
"type":"offer",
"description":"A high level description",
"points":100,
"start_time":"2016-02-02T17:08:29Z",
"end_time":"2016-03-02T17:08:29Z",
"weight": 100,
"featured": true,
"tier":"gold",
"status":"verification_required",
"requires_skills_test":false,
"logo":"http://content.sessionm.com/offers/2/logo.png",
"data":{ "example" : "example" }
},
{
"id":3,
"name":"Name of offer variant B",
"type":"offer",
"description":"A high-level description",
"points":100,
"start_time":"2016-02-02T17:08:29Z",
"end_time":"2016-03-02T17:08:29Z",
"weight": 200,
"featured": true,
"tier":"gold",
"status":"verification_required",
"requires_skills_test":false,
"logo":"http://content.sessionm.com/offers/2/logo.png",
"data":{ "example" : "example" }
}
]
}
}
The following table documents this object:
Response Attributes for Reward (Formerly Offer)
Attribute | Type | Description |
---|---|---|
id | string | Internal reward identifier. |
name | string | Name of the reward. |
type | string | Available reward types. Default ones include: offer, prize, coupon, instant reward, and contest entries. However, free-form attributes can contain others. |
description | string | Description of reward. |
points | integer | Amount of points, or other loyalty currency, associated with reward. |
start_time | string | Datetime at which reward begins. ISO 8601 format. For example: 2016-02-02T17:08:29Z. |
end_time | string | Datetime at which reward ends. ISO 8601 format. For example: 2016-02-02T17:08:29Z. |
weight | integer | Arbitrary numeric value which allows for sorting items. |
featured | boolean | Used to identify a prominent reward for display. |
tier | string | Tiers within a tier system. |
tier_system | string | Tier systems in enterprise client. |
status | string | Status of reward with respect to customer. For more information on reward statuses, see the table below. |
requires_skills_test | boolean | Required for Canadian contests. |
logo | string | An image-based URL for reward. |
terms | string | Terms of reward agreement. |
data | object | Free form hash for client-specific needs. |
options | array | Child rewards. For example small, medium, large sizes. |
Reward Statuses
The following status values can be returned in the offer object within a response representing a reward:
Code | Reason |
---|---|
available | Reward is available for redemption by the customer. |
verification_required | Customer is not yet verified and verification is needed prior to redemption. |
not_qualified | The customer does not meet the qualification requirement for the reward - for example the customer might be a minor. |
insufficient_points | The reward redemption value is higher than the current available points for the customer. |
user_required | Cannot determine the status of this reward against a customer without a customer ID. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
Code | Reason |
---|---|
invalid_api_key | API key sent in cannot be found. |
user_not_found | Customer ID sent in cannot be found. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Skills Test Challenge API
Challenge objects allow jurisdictions to require that a sweepstakes entry be gated by a skills test. A reward can employ this logic to require a skills test that approves mental ability or competency. For example, the laws governing Canadian contests require that a skills test be used to qualify customers redeeming a reward. Skills test challenge questions are selected randomly from a pool of questions.
The requirement to use a skills test challenge is part of the metadata for an Rewards Store API. The Skills Test Challenge API can be used to both create and retrieve one.
When an reward requires a skills test challenge, the customer's response is reflected in the request and response objects returned by the Orders API.
If the customer answers with the wrong answer, no error is returned; the customer is not entered in the sweepstakes and the points used to enter the challenge for the sweepstakes are forfeited.
This API provides the following methods:
Retrieve a Skills Test Challenge Question
Retrieves a skills test challenge question.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/users/:user_id/challenges/skills_test_question
GET /priv/v1/apps/:api_key/external/users/:external_id/challenges/skills_test_question
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
Not applicable.
Response Object
In addition to a status value-pair for the transaction, the response object returned by the method contains a challenge object, which in turn contains a skills_test_question object, as shown below:
{
"status": "ok",
"challenge": {
"skills_test_question": {
"id": 100,
"question": "(2+2) + (2-2)"
}
}
}
This object is detailed in the following table:
Response Attributes for Skills Test Question
Attribute | Type | Description |
---|---|---|
id | integer | Skills test ID. |
question | string | Skill test question. |
response | string | Skill test question response. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
Code | Reason |
---|---|
invalid | Skills test question was answered incorrectly |
skills_test_not_found | Skills test ID sent in was not found |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Create a Skills Test Challenge Question
Specifies a skills test challenge question.
Endpoints
This method offers the following endpoints:
POST /priv/v1/apps/:api_key/users/:user_id/offers/:offer_id/challenges/skills_test_questions/:skills_test_question_id
POST /priv/v1/apps/:api_key/external/users/:external_id/offers/:offer_id/challenges/skills_test_questions/:skills_test_question_id
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
offer_id | Identifier for reward associated with skills test challenge. |
skills_test_challenge_id | Identifier for skills test challenge question. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
When this method runs, it passes in a request object that contains a challenge object, which contains a skills_test_question object, shown below:
These objects are detailed in the following tables:
Request Attributes for Challenge
Attribute | Type Required/Optional |
Description |
---|---|---|
skills_test_question | object required |
Skills test question, which contains a response attribute detailed in the next table. |
Request Attributes for Skill Test Question
Attribute | Type Required/Optional |
Description |
---|---|---|
response | integer required |
Skills test question response. |
Response Object
In addition to a status value-pair for the transaction, the response object returned by the method contains a challenge object, as shown below:
This object is detailed in the following table:
Response Attributes for Challenge
Attribute | Type | Description |
---|---|---|
id | integer | Challenge ID. |
status | string | Skills test challenge result: valid or invalid. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.
Referrals API
Referral objects provide the means to run a refer-a-friend program. These programs must be set up initially in the platform before you can begin using the Referrals API to add incentives to them. Each refer-a-friend program can implement a set of custom rules.
Bonus points obtained through a refer-a-friend program appear as conversion points in response objects returned by the Referrals API.
Metadata such as a description, points totals, and record identifiers for a referral program are visible in the response objects returned by the Points API.
Referrals objects allow an enterprise client to create referrals and retrieve their details. Each referral requires a referrer and at least one referee. A referrer is an existing SessionM customer that wants to notify other people about a promotion; a referee is the person (or people) receiving the referral.
A referral object includes the referrer, along with their email, telephone number, and the name of their associated referee(s).
This API provides the following methods:
Create Referrals
Builds referrals for one or multiple referees based on a referrer. The data entered for the referrer attribute will determine how the referrer is referenced by the referee. The referee is addressed in a greeting with the data contained in the referee attribute.
Endpoints
This method offers the following endpoints:
POST /priv/v1/apps/:api_key/users/:user_id/referrals
POST /priv/v1/apps/:api_key/external/users/:external_id/referrals
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
When this method runs, it passes in a request object that contains the referrer attribute (required string), along with a referrals array, as shown below:
This array is detailed in the following table:
{
"referrer": "referrer name/id shown to the referee",
"referrals": [
{
"referee": "referee name/id for greeting (optional)",
"email": "example1@example.com",
"tel": "617-555-1212"
},
{
"referee": "referee name/id for greeting (optional)",
"email": "example21@example.com",
"tel": "617-555-1213"
}
]
}
This object is detailed in the following table:
Request Attributes for Referrals
Attribute | Type Required/Optional |
Description |
---|---|---|
referee | string required |
Referee name/ID for the greeting. |
string required |
Email address of referee. Data is encrypted for storage on the disk. | |
tel | string required |
Telephone number of referee. |
Response Object
In addition to a status key-value pair, the response object returned by the method contains the referrals object, as shown below:
{
"status": "ok",
"referrals": [
{
"id": "identifier for the created referral",
"referee": "referee name/id for greeting (optional)",
"email": "example1@example.com",
"tel": "617-555-1212",
"origin": "",
"source": "12345",
"client_data": "opaque client data",
"status": "pending",
"pending_at": "2017-01-01T02:04:55.126Z",
"engaged_at": null,
"registered_at": null,
"converted_at": null,
"voided_at": null,
"conversion_points": 0
},
{
"id": "identifier for the created referral",
"referee": "referee name/id for greeting (optional)",
"email": "example21@example.com",
"tel": "617-555-1213",
"origin": "",
"source": "12345",
"client_data": "opaque client data",
"status": "pending",
"pending_at": "2017-01-01T02:04:55.126Z",
"engaged_at": null,
"registered_at": null,
"converted_at": null,
"voided_at": null,
"conversion_points": 0
}
]
}
The following table documents this object:
Response Attributes for Referrals
Attribute | Type | Description |
---|---|---|
id | integer | Identifier for the referral. |
referee | string | Referee name/ID for greeting. |
string | Referee's email address. Data is encrypted for storage on the disk. | |
tel | string | Referee's telephone number. |
client_data | string | Opaque client data. |
status | string | Status of the initial referral is pending, but could be any of the following: pending, engaged, registered, converted, limit_period, limit_lifetime, and voided. |
pending_at | datetime | Time the referral became pending. |
engaged_at | datetime | Time the referral became engaged. |
registered_at | datetime | Time the referral became registered. |
converted_at | datetime | Time the referral became converted. |
voided_at | datetime | Time the referral became voided. |
conversions_points | integer | Identifier for the referral. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
Code | Reason |
---|---|
referral_email_required | Email is required. |
referral_registered_email | Email already in use. |
missing_data | No referrals specified. |
validation | Limit for referrals in a month exceeded. |
referral_duplicate_email | Limit for referrals for the customer exceeded. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Retrieve All Referrals
Returns all referrals a customer has made, based customer ID or the enterprise client’s external ID.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/users/:user_id/referrals
GET /priv/v1/apps/:api_key/external/users/:external_id/referrals
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
Not applicable.
Response Object
This method returns a response object that begins with status and cursor key-value pairs, both of which are strings. When the cursor value is null, there is no more data.
Then the response shows a referral array, as shown below:
{
"status": "ok",
"cursor": "cursor value (null means no more data)",
"referral": [
{
"id": "identifier for the referral",
"referee": "referee name/id for greeting (optional)",
"email": "example1@example.com",
"tel": "555 1212",
"origin": "",
"source": "12345",
"client_data": "opaque client data",
"status": "pending|engaged|registered|converted|limit_period|limit_lifetime|voided",
"pending_at": "2017-01-01T02:04:55.126Z",
"engaged_at": "2017-01-01T02:04:55.126Z",
"registered_at": "2017-01-01T02:04:55.126Z",
"converted_at": "2017-01-01T02:04:55.126Z",
"voided_at": "2017-01-01T02:04:55.126Z",
"conversion_points": 10
},
{
"id": "identifier for the referral",
"referee": "referee name/id for greeting (optional)",
"email": "example1@example.com",
"tel": "555 1212",
"origin": "",
"source": "12345",
"client_data": "opaque client data",
"status": "pending|engaged|registered|converted|limit_period|limit_lifetime|voided",
"pending_at": "2017-01-01T02:04:55.126Z",
"engaged_at": "2017-01-01T02:04:55.126Z",
"registered_at": "2017-01-01T02:04:55.126Z",
"converted_at": "2017-01-01T02:04:55.126Z",
"voided_at": "2017-01-01T02:04:55.126Z",
"conversion_points": 10
}
]
}
For information on this object, see the referrals object.
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.
Retrieve a Single Referral
Retrieves information for a single referral based on customer ID and referral ID or the enterprise client customer’s external ID and referral ID.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/users/:user_id/referrals/:referral_id
GET /priv/v1/apps/:api_key/external/users/:external_id/referrals/:referral_id
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
referral_id | Identifier for the referral. |
Request Object
Not applicable.
Response Object
In addition to a status key-value pair, the response object returned by the method contains a referral object, as shown below:
{
"status": "ok",
"referral": {
"id": "identifier for the referral",
"referee": "referee name/id for greeting (optional)",
"email": "example@example.com",
"tel": "555 1212",
"origin": "",
"source": "12345",
"client_data": "opaque client data",
"status": "pending|engaged|registered|converted|limit_period|limit_lifetime|voided",
"pending_at": "2017-01-01T02:04:55.126Z",
"engaged_at": "2017-01-01T02:04:55.126Z",
"registered_at": "2017-01-01T02:04:55.126Z",
"converted_at": "2017-01-01T02:04:55.126Z",
"voided_at": "2017-01-01T02:04:55.126Z",
"conversion_points": 10
}
}
For information on this object, see the referrals object.
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
Code | Reason |
---|---|
referral_not_found | Referral doesn't exist; referral ID not found. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Loyalty Card API
The Loyalty Card API offers Loyalty Card and Retailers objects to allow third-party systems to link their loyalty cards to an enterprise client standard customer profile, which is often called a customer account. Many retailers issue loyalty cards to their customers that are then swiped at the register for point of sale discounts on select products.
The API offers a way to read loyalty card transactions and in turn award points that correspond with what the customer purchases.
The workflow resembles the point of sale transactions managed by the Events API. Just as the Events API offers a purchase event type, the Loyalty Card API treats transactions from loyalty card providers as purchase events run against - or processed against - active campaigns.
Loyalty cards can be linked to campaigns. Within a campaign, incentives and different types of messaging can be outcomes of specific purchase actions. This type of link must be configured via the Administration Portal in advance, as they are not managed by the Campaigns API.
Loyalty card programs can generate points that appear as balances in response objects returned by both Standard Profile and Custom Profile APIs. Note that the standard profile provides support for actually creating the customers in the system.
Endpoints available with the Points API support the ability to query loyalty card transactions.
This API provides the following methods:
- Create an on-demand loyalty card
- Create a link between a loyalty card and a standard profile
- Retrieve a list of participating retailers
- Retrieve a list of linked loyalty cards
- Retrieve loyalty card transactions
- Delete the link between a loyalty card and a standard profile
- Scan a loyalty card
Create an On-demand Loyalty Card
Creates a digital loyalty card identifier and associates it to a customer in real time. This method is executed for a single customer, one at a time and on-demand.
Endpoints
This method offers the following endpoints:
POST /priv/v1/apps/:api_key/users/:user_id/loyalty_cards
POST /priv/v1/apps/:api_key/external/users/:external_id/loyalty_cards
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
Not applicable.
Response Object
In addition to a status key-value pair, the response object returned by the method contains a loyalty_card object, as shown below:
{
"status": "ok",
"loyalty_card": {
"id": 23,
"user": {
"id": "4f5b82c0-07c8-11e6-8d84-624132d14633"
},
"card_type": "digital_card",
"last_activated_at": "2016-12-06T20:45:16Z",
"number": "DBEDTFK6DD"
}
}
This object is detailed in the following table:
Response Attributes for Loyalty Card
Attribute | Type | Description |
---|---|---|
id | integer | Loyalty card identifier. |
user | object | Contains id, which identifies a customer; or external_id, which identifies a customer in an external system. Can include available_points attribute when the customer has accumulated loyalty points. |
card_type | string | Loyalty card type. For these endpoints, digital_card, which is a purely digital loyalty card number. |
last_activated_at | datetime | Most recent activation or linkage. Complies with ISO8601 datetime. |
last_scanned_at | datetime | Most recent scan. Complies with ISO8601 datetime. |
number | string | Loyalty card decrypted number. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
Code | Reason |
---|---|
card_type_is_not_ondemand | The generation attribute in the loyalty card policy is not on-demand. |
alphabet_contains_duplicates_characters_for_policy | The alphabet attribute in the loyalty card policy has duplicate characters. |
max_iterations_reached | Maximum number of loyalty cards have been connected for the given customer. |
no_alphabet_available_for_policy | General catch-all validation error. |
invalid_card_type_for_policy | Maximum number of iterations has been reached for generating the unique on-demand card. |
max_cards_exceeded_for_player | The customer has exceeded the maximum number of active cards that a customer may have at one time. |
no_max_active_cards_per_player_available_for_policy | The max_active_cards_per_player attribute in the loyalty card policy is not defined. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Create a Link between a Loyalty Card and a Standard Profile
Specifies a link between a retailer’s loyalty card and a customer’s standard profile, often called a customer account.
Endpoints
This method offers the following endpoints:
POST /priv/v1/apps/:api_key/users/:user_id/loyalty_links
POST /priv/v1/apps/:api_key/external/users/:external_id/loyalty_links
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
When this method runs, it passes in a request object that contains a loyalty_card object, as shown below:
This object is detailed in the following table:
Request Attributes for Loyalty Card
Attribute | Type Required/Optional |
Description |
---|---|---|
retailer_id | string required |
Unique retailer identifier. |
card_number | string required |
Unique loyalty card identifier. |
Response Object
In addition to a status key-value pair, the response object returned by the method contains a loyalty_card object.
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
Code | Reason |
---|---|
card_not_found | The passed in loyalty card number could not be located. |
retailer_code_invalid | US zip codes are currently supported. |
card_limit_reached | Max number of cards have been connected for the given customer. |
validation | General catch all validation error. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Retrieve a List of Participating Retailers
Returns a list of retailers that can be linked to a standard profile for a customer. If using an endpoint with user_id, it will return retailers linked to a specific customer’s standard profile. You can also set an endpoint parameter that retrieves all retailers for the specified zip code. Note that the endpoints that utilize anonymous_index, user_id or external_id, are available for registered customers (users); however, GET /api/v1/apps:/api_key/loyalty_retailers?auth_token=xxxxx applies to unregistered, anonymous customers.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/loyalty_retailers/anonymous_index?zip=12345
GET /priv/v1/apps/:api_key/users/:user_id/loyalty_retailers?zip=12345
GET /priv/v1/apps/:api_key/external/users/:external_id/loyalty_retailers?zip=12345
GET /api/v1/apps:/api_key/loyalty_retailers?auth_token=xxxxx
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
zip | Returns retailers within zip or postal code; returns all retailers by default. For example, zip=12345. |
Request Object
Not applicable.
Response Object
In addition to a status key-value pair, the response object returned by the method contains a retailers object, as shown below:
{
"status": "ok",
"retailers": [
{
"id": 111111,
"name": "ACME",
"card": "ACME Card",
"icon": "https://....",
"image": "https://....",
"linked": true,
"barcode_scannable": true
},
{
"id":222222,
"name": "Rx Inc.",
"card": "Rx Card",
"icon": "https://....",
"image" : "https://....",
"linked": false
}
]
}
This object is detailed in the following table:
Response Attributes for Retailers
Attribute | Type | Description |
---|---|---|
id | integer | Loyalty retailer ID. |
name | string | Retailer name. |
card | string | Loyalty card name. |
icon | string | Retailer icon URL. Dimensions can vary. |
image | string | Retailer feature image URL. Dimensions can vary. |
linked | boolean | If the retailers endpoint is requested with a customer or external ID, linked indicates if the customer has a loyalty card linked against this retailer. |
barcode_scannable | boolean | If the barcode is set by the retailer (on the LoyaltyRetailer object) and is scannable, the value can be sent back to the API. true if the barcode is scannable; false if it's not. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
Code | Reason |
---|---|
retailer_code_invalid | When an invalid zip or postal code is entered. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Retrieve a List of Linked Loyalty Cards
Retrieves a list of loyalty cards linked to a specific standard customer profile.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/users/:user_id/loyalty_links
GET /priv/v1/apps/:api_key/external/users/:external_id/loyalty_links
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
Not applicable.
Response Object
In addition to a status key-value pair, the response object returned by the method contains a loyalty_cards array, which includes a set of loyalty_card objects, as shown below:
{
"status":"ok",
"loyalty_cards":[
{
"id":12345,
"card_number":"12345",
"retailer":{
"id":"54321",
"name":"ACME",
"icon":"https://....",
"image":"https://...."
}
},
{
"id":12345,
"card_number":"456789",
"retailer":{
"id":"54321",
"name":"Rx Inc.",
"icon":"https://....",
"image":"https://...."
}
}
]
}
This array is detailed in the following table:
Response Attributes for Loyalty Cards
Attribute | Type | Description |
---|---|---|
id | integer | Loyalty Card ID. |
card_number | string | Loyalty card number. |
retailer | object | For more information, see the retailers array. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.
Retrieve Loyalty Card Transactions
Retrieves loyalty card transactions.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/users/:user_id/loyalty_transactions
GET /priv/v1/apps/:api_key/external/users/:external_id/loyalty_transactions
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
limit | Default is 100. |
page | Default is 1. |
Request Object
Not applicable.
Response Object
In addition to a status key-value pair, the response object returned by the method contains a loyalty_transactions array, as shown below:
{
"status":"ok",
"loyalty_transactions":[
{
"id":201,
"name":"3600000011",
"description":"Product 3600000011",
"price":10.0,
"quantity":1,
"transaction_datetime":"2016-05-26 17:23:46",
"points":10,
"created_at":"2016-05-26 17:23:46",
"updated_at":"2016-05-26 17:23:46"
},
{
"id":206,
"name":"3600000016",
"description":"Product 3600000016",
"price":10.0,
"quantity":1,
"transaction_datetime":"2016-05-26 17:23:46",
"points":10,
"created_at":"2016-05-26 17:23:46",
"updated_at":"2016-05-26 17:23:46"
}
]
}
This array is detailed in the following table:
Response Attributes for Loyalty Transactions
Attribute | Type | Description |
---|---|---|
id | integer | Loyalty transaction ID. |
name | string | UPC/SKU code or product description. |
description | string | Product description. |
price | float | Price payed in the transaction. |
quantity | integer | Number of product purchased. |
transaction_datetime | string | Purchase date time in UPC. |
points | integer | Points earned for the transaction. |
created_at | string | Loyalty transaction creation UTC date time. |
updated_at | string | Loyalty transaction last updated UTC date time. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
Code | Reason |
---|---|
requires_registered_user | Registed customers are required for this request. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Delete the Link between a Loyalty Card and a Standard Profile
Deletes the link between a loyalty card and a standard customer profile.
Endpoints
This method offers the following endpoints:
DELETE /priv/:api_version/apps/:api_key/users/:user_id/loyalty_links/:id
DELETE /priv/v1/apps/:api_key/external/users/:external_id/loyalty_links/:id
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_version | Internal parameter that supports API versioning. |
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
id | Loyalty Card ID. |
Request Object
Not applicable.
Response Object
This method returns a response object that contains a status key-value pair, as shown below:
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
Code | Reason |
---|---|
card_not_found | When an invalid loyalty_card ID is entered. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Scan a Loyalty Card
Scan a loyalty card. For example, a customer scanning their digital loyalty card with their mobile phone at a point-of-sale device in a retail coffee shop. A client application could then implement a workflow in which the action of scanning a card results in a discount being applied to a particular reward.
Endpoints
This method offers the following endpoints:
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
card_number | Loyalty card number. |
Request Object
Not applicable.
Response Object
Since this method’s response object is similar to what is returned for the method that creates an on-demand loyalty card, see the loyalty_card object for more information on the object which is shown below:
{
"status": "ok",
"loyalty_card": {
"id": 29,
"user": {
"external_id": "N/A",
"available_points": 394160
},
"card_type": "digital_card",
"last_activated_at": "2016-12-08T16:44:31Z",
"last_scanned_at": "2016-12-08T19:20:25Z",
"number": "D1QMCP2R2O"
}
}
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
Code | Reason |
---|---|
unknown_loyalty_card | Loyalty card number does not exist. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.