Core Loyalty APIs

With the launch of APIs for the SessionM Offers, Loyalty, Catalog and Transactions domains, these Core Loyalty APIs are no longer supported for new integrations. Use the Offers, Loyalty, Catalog and Transactions domain APIs for new integrations.

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:

Copy
JSON Response Object with Loyalty Settings Enabled
{
    "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:

Copy
JSON Response Object with Loyalty Settings Enabled
{
  "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

With the launch of APIs for the SessionM Offers, Incentives, Catalog and Transactions domains, this Rewards Store API is no longer supported for new integrations. Use the Offers, Incentives, Catalog and Transactions domain APIs for new integrations.

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.

API Contingencies and Combinations:
Since rewards reflect a customer's ability to redeem points or other loyalty currency for a reward, you must create the customers first. Use the Standard Profile API to create customers and specify the attributes for their standard profiles.
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:

Copy
REST 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:

Copy
JSON Response
{
   "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

With the launch of APIs for the SessionM Offers, Incentives, Catalog and Transactions domains, this Skills Test Challenge API is no longer supported for new integrations. Use the Offers, Incentives, Catalog and Transactions domain APIs for new integrations.

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.

API Contingencies and Combinations:
Since skills test challenges are designed for customers, you must create customers to engage in the challenge. Use the Standard Profile API to create customers and specify the attributes for their standard profiles.
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:

Copy
REST 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:

Copy
JSON Response
{
  "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:

Copy
REST 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:

Copy
JSON Request
{
  "challenge": {
    "skills_test_question": {
      "response": "1"
    }
  }
}

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:

Copy
JSON Response
{
  "status": "ok",
  "challenge": {
    "id": 1111111,
    "status": "valid"
  }
}

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

With the launch of APIs for the SessionM Offers, Incentives, Catalog and Transactions domains, this Referrals API is no longer supported for new integrations. Use the Offers, Incentives, Catalog and Transactions domain APIs for new integrations.

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.

API Contingencies and Combinations:
People that are referred through a refer-a-friend program appear as customers in request and response objects managed by the Standard Profile API.
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:

Copy
REST 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:

Copy
JSON Request
{
  "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.
email 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:

Copy
JSON Response
{
  "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.
email 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:

Copy
REST 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:

Copy
JSON Response
{
  "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:

Copy
REST 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:

Copy
JSON Response
{
  "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

With the launch of APIs for the SessionM Offers, Incentives, Catalog and Transactions domains, this Loyalty Card API is no longer supported for new integrations. Use the Offers, Incentives, Catalog and Transactions domain APIs for new integrations.

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.

API Contingencies and Combinations:
This API requires that the client has a Saving Star account for purchase attribution.
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

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:

Copy
REST 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:

Copy
JSON Response
{
  "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.

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:

Copy
REST 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:

Copy
JSON Request
{
   "loyalty_card":{
      "retailer_id":"54777321",
      "card_number":"12345"
   }
}

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.
Copy
JSON Response
{
   "status":"ok",
   "loyalty_card":{
      "id":12345
   }
}
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:

Copy
REST 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:

Copy
JSON Response
{
  "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:

Copy
REST 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:

Copy
JSON Response
{
   "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:

Copy
REST 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:

Copy
JSON Response
{
   "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.

Deletes the link between a loyalty card and a standard customer profile.

Endpoints

This method offers the following endpoints:

Copy
REST 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:

Copy
JSON Response
{
   "status":"ok"
}
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:

Copy
REST Endpoints
GET /priv/v1/apps/:api_key/loyalty_cards/:card_number

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:

Copy
JSON Response
{
  "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.