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:

• Rewards Stores (formerly called Offers)
• Skill Test Challenges
• Referrals
• Loyalty Cards

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:

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:

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:

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:

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.

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 for Retrieve a List of Rewards for an Eligible Customer

This method offers the following endpoints:

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 for Retrieve a List of Rewards for an Eligible Customer

The following parameters are available when specifying the endpoint for this method:

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 for Retrieve a List of Rewards for an Eligible Customer

Not applicable.

Response Object for Retrieve a List of Rewards for an Eligible Customer

In addition to a status value-pair for the transaction, the response object returned by the method contains an offer object, as shown below:

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)

Reward Statuses

The following status values can be returned in the offer object within a response representing a reward:

Statuses and Errors for Retrieve a List of Rewards for an Eligible Customer

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:

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.

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
• Create a skills test challenge question

Retrieve a Skills Test Challenge Question

Retrieves a skills test challenge question.

Endpoints for Retrieve a Skills Test Challenge Question

This method offers the following endpoints:

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 for Retrieve a Skills Test Challenge Question

The following parameters are available when specifying the endpoint for this method:

Request Object for Retrieve a Skills Test Challenge Question

Not applicable.

Response Object for Retrieve a Skills Test Challenge Question

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:

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

Statuses and Errors for Retrieve a Skills Test Challenge Question

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:

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 for Create a Skills Test Challenge Question

This method offers the following endpoints:

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 for Create a Skills Test Challenge Question

The following parameters are available when specifying the endpoint for this method:

Request Object for Create a Skills Test Challenge Question

When this method runs, it passes in a request object that contains a challenge object, which contains a skills_test_question object, shown below:

JSON Request

{
  "challenge": {
    "skills_test_question": {
      "response": "1"
    }
  }
}

These objects are detailed in the following tables:

Request Attributes for Challenge

Request Attributes for Skill Test Question

Response Object for Create a Skills Test Challenge Question

In addition to a status value-pair for the transaction, the response object returned by the method contains a challenge object, as shown below:

JSON Response

{
  "status": "ok",
  "challenge": {
    "id": 1111111,
    "status": "valid"
  }
}

This object is detailed in the following table:

Response Attributes for Challenge

Statuses and Errors for Create a Skills Test Challenge Question

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.

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
• Retrieve all referrals
• Retrieve a single referral

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 for Create Referrals

This method offers the following endpoints:

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 for Create Referrals

The following parameters are available when specifying the endpoint for this method:

Request Object for Create Referrals

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:

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

Response Object for Create Referrals

In addition to a status key-value pair, the response object returned by the method contains the referrals object, as shown below:

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

Statuses and Errors for Create Referrals

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:

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 for Retrieve All Referrals

This method offers the following endpoints:

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 for Retrieve All Referrals

The following parameters are available when specifying the endpoint for this method:

Request Object for Retrieve All Referrals

Not applicable.

Response Object for Retrieve All Referrals

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:

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 for Retrieve All Referrals

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 for Retrieve a Single Referral

This method offers the following endpoints:

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 for Retrieve a Single Referral

The following parameters are available when specifying the endpoint for this method:

Request Object for Retrieve a Single Referral

Not applicable.

Response Object for Retrieve a Single Referral

In addition to a status key-value pair, the response object returned by the method contains a referral object, as shown below:

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 for Retrieve a Single Referral

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:

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.

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 for Create an On-demand Loyalty Card

This method offers the following endpoints:

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 for Create an On-demand Loyalty Card

The following parameters are available when specifying the endpoint for this method:

Request Object for Create an On-demand Loyalty Card

Not applicable.

Response Object for Create an On-demand Loyalty Card

In addition to a status key-value pair, the response object returned by the method contains a loyalty_card object, as shown below:

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

Statuses and Errors for Create an On-demand Loyalty Card

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:

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 for Create a Link between a Loyalty Card and a Standard Profile

This method offers the following endpoints:

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 for Create a Link between a Loyalty Card and a Standard Profile

The following parameters are available when specifying the endpoint for this method:

Request Object for Create a Link between a Loyalty Card and a Standard Profile

When this method runs, it passes in a request object that contains a loyalty_card object, as shown below:

JSON Request

{
   "loyalty_card":{
      "retailer_id":"54777321",
      "card_number":"12345"
   }
}

This object is detailed in the following table:

Request Attributes for Loyalty Card

JSON Response

{
   "status":"ok",
   "loyalty_card":{
      "id":12345
   }
}

Response Object for Create a Link between a Loyalty Card and a Standard Profile

In addition to a status key-value pair, the response object returned by the method contains a loyalty_card object.

Statuses and Errors for Create a Link between a Loyalty Card and a Standard Profile

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:

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 for Retrieve a List of Participating Retailers

This method offers the following endpoints:

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 for Retrieve a List of Participating Retailers

The following parameters are available when specifying the endpoint for this method:

Request Object for Retrieve a List of Participating Retailers

Not applicable.

Response Object for Retrieve a List of Participating Retailers

In addition to a status key-value pair, the response object returned by the method contains a retailers object, as shown below:

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

Statuses and Errors for Retrieve a List of Participating Retailers

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:

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 for Retrieve a List of Linked Loyalty Cards

This method offers the following endpoints:

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 for Retrieve a List of Linked Loyalty Cards

The following parameters are available when specifying the endpoint for this method:

Request Object for Retrieve a List of Linked Loyalty Cards

Not applicable.

Response Object for Retrieve a List of Linked Loyalty Cards

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:

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

Statuses and Errors for Retrieve a List of Linked Loyalty Cards

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 for Retrieve Loyalty Card Transactions

This method offers the following endpoints:

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 for Retrieve Loyalty Card Transactions

The following parameters are available when specifying the endpoint for this method:

Request Object for Retrieve Loyalty Card Transactions

Not applicable.

Response Object for Retrieve Loyalty Card Transactions

In addition to a status key-value pair, the response object returned by the method contains a loyalty_transactions array, as shown below:

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

Statuses and Errors for Retrieve Loyalty Card Transactions

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:

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 for Delete the Link between a Loyalty Card and a Standard Profile

This method offers the following endpoints:

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 for Delete the Link between a Loyalty Card and a Standard Profile

The following parameters are available when specifying the endpoint for this method:

Request Object for Delete the Link between a Loyalty Card and a Standard Profile

Not applicable.

Response Object for Delete the Link between a Loyalty Card and a Standard Profile

This method returns a response object that contains a status key-value pair, as shown below:

JSON Response

{
   "status":"ok"
}

Statuses and Errors for Delete the Link between a Loyalty Card and a Standard Profile

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:

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 for Scan a Loyalty Card

This method offers the following endpoints:

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 for Scan a Loyalty Card

The following parameters are available when specifying the endpoint for this method:

Request Object for Scan a Loyalty Card

Not applicable.

Response Object for Scan a Loyalty Card

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:

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 for Scan a Loyalty Card

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:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.