Reward Optimizer API solution

Introduction

The Loyalty Bay Reward Optimizer API is a REST API callable over HTTPs, which returns JSON data. It allows you to integrate user rewards into your site easily, whilst giving you control of how they are rendered.

Definitions

There are a few basic concepts to understand. A website owner (publisher) can display Loyalty Bay rewards on their website (the publisher website). Their users can select which reward they would like and the publisher website can then send the reward to the user, all via API calls. Rewards are available as sets called reward campaigns . You can have many different reward campaigns associated with your api key, so you could have different reward campaigns for different parts of your website. Rewards contain all of the assets (e.g. description, reward image etc.) necessary to display the reward to the user.
Reward campaign explanation
Relationship between Loyalty Bay publisher and rewards

Usage Examples

1 - Separate choice and conversion

This describes a typical way that the API can be used to integrate rewards into your site. It works well when there is a single 'flow' through your web app, like a signup process, during which you want to reward an action.

Steps

  1. Call the retrieve reward campaign API method call to get all reward data for one of your reward campaigns
  2. Then use the reward data to render a form to the user allowing them to choose one of the rewards. When the form is posted back to your server it should send the chosen reward identifier to be used in the create choice API call.
  3. Call the create choice API method call to record which reward the user chose, passing the reward identifier returned in the previous step.
  4. Once the user has completed your process, call the create conversion API method call. This triggers sending of the user reward.

2 - Combined choice / conversion

This usage scenario is good for when there is no real separation between the 'choice' and 'conversion' steps, i.e. you wish to send the reward to the user as soon as they have chosen.

Steps

  1. Call the retrieve reward campaign API method call to get all reward data for one of your reward campaigns
  2. Then use the reward data to render a form to the user allowing them to choose one of the rewards. When the form is posted back to your servers it should send the chosen reward identifier to be used in the create conversion API call.
  3. Call the create conversion API method call to record which reward the user chose, passing both the reward campaign identifier and the reward identifier returned in the previous step.

3 - Deferred conversion

Sometimes you might have a split online/offline process where you can't identify the user with a user id at the end of the process. An example of this could be when a user signs up for broadband online, chooses a reward, but isn't sent the reward until 30 days after their broadband has been installed.

In these cases, you often have a further offline process which needs to run in order to confirm the user's conversion (e.g. some sort of database query, followed by processing of that data). The deferred conversion api call allows you to link up the online user choice data with the offline conversion data by 'tagging' the online choice data with a 'reconciliation ID'.

An example of a good reconciliation ID might be an order number, since it is likely that you have access to it both online and offline.

Steps

  1. As in Usage example 1, use the retrieve reward campaign to show the user rewards and the create choice to register the user's reward choice
  2. Then call the defer conversion API method call with the appropriate reconciliation ID to signal that the user has completed the process online but that there is some sort of period to wait before full completion (e.g. 30-day cooling off period)
  3. After the cooling off period, call the complete deferred conversion API method call with the correct reconciliation ID to trigger sending of the reward.

4 - Create and use claim link

If all you want to do is directly reward one of your users, then you can create a claim link for a reward (e.g. Amazon £10). Then you can do whatever you want with it (display on a webpage, send via email etc.). The claim link is unique for each user.

Steps

  1. Call the create claim link API method call to get a unique claim link for one of your rewards. Optionally store the returned claim link identifier so you can check whether the user has collected the link later on.
  2. Communicate the claim link to your user in whatever way works best for you.
  3. (Optionally) check whether the user has collected the claim link by calling the claim link report API method

5 - Send reward choice email

Instead of showing a set of rewards and collecting a user's choice via the API, you can instead allow Loyalty Bay to do all of the work. Just make a single call to the send reward choice API method, and we will send the user a link to a page on our site that allows them to choose and claim a reward.

API Basics

All requests should include your API key passed as an http header (details below). Request parameters are sent as standard HTTP parameters. The response will be sent with a content type of "application/json" and will have http status headers set appropriately (e.g. 200 status code for successful requests, 401 for not authorized etc).

API response codes

The HTTP response code will tell you whether the request succeeded or not. Any code other than 200 means something went wrong, and you can inspect the JSON structure to get more details.
code status interpretation
200 Success Everything's cool
401 Unauthorized Something was wrong with the API key you passed. Check the JSON response for more details.
400 Bad request You probably missed a required parameter. Check the JSON response for more details.
500 Server error Something totally unexpected happened, contact us!

API response JSON

The response body will be a JSON string with a predictable structure. It will always consist of a root JSON Object with a 'status' attribute along with other optional attributes.
Response attribute always present? description allowed/example values
status Y denotes the outcome of the request
"success"
"error"
message N gives additional information in case of "error" status "api key required"
data N a JSON object containing data keyed by the resource name that was requested. Can be missing e.g. if request was a post that created something JSON object (see specific API calls for examples)

Example successful JSON response structure

{
  "status": "success",
  "data": {
    "things_you_asked_for": [
      {
        "id": 1,
        "name": "hello"
      },
      {
        "id": 2,
        "name": "world"
      }
    ]
  }
}

Example unsuccessful JSON response structure

{
  "status": "error",
  "message": "API key not recognised"
}

Reward campaigns

A reward campaign is a collection of rewards which you would like to offer to your users. For example a reward campaign could consist of 4 rewards, from which you will allow your user to choose one. You can have more than one reward campaign associated with a single API key.

Retrieve reward campaign

GET https://api.loyaltybay.co.uk/api/v1/reward_campaigns/REWARD_CAMPAIGN_IDENTIFIER
Returns a single reward campaign with it's associated rewards. You can then use this data to e.g. render a form with the rewards as options so your user can choose one. Note that you need to pass the identifier for the reward campaign of interest in the url as shown above.

Request parameters

name type required description
uuid string Y ID of the current website user. This needs to be used in most of the subsequent API calls, so should be consistent throughout the process. Ideally it would be a real user id, consistent across logins. However if there is no logged in user available a session id will do.

Response fields

This method call will return active flags for both campaign and rewards within the campaign. It is up to the API consumer (i.e. you!) to decide whether or not to use inactive campaigns and/or rewards.
name type always present? description
status string Y whether the call succeeded
message string N (present if error) additional information in case of "error" status
data object N (missing if error) contains the requested or created object
data['reward_campaign'] object N (missing if error) representation of the requested reward campaign and associated rewards
response fields when data['reward_campaign'] is present
data['reward_campaign']['name'] string Y campaign short name
data['reward_campaign']['active'] boolean Y whether the campaign is on or off
data['reward_campaign']['identifier'] string Y campaign identifier
data['reward_campaign']['rewards'] array Y array of objects representing the rewards for this campaign
reward object keys
data['reward_campaign']['rewards'][index]['name'] string Y reward short name e.g. Amazon $10
data['reward_campaign']['rewards'][index]['active'] boolean Y whether the reward is on or off
data['reward_campaign']['rewards'][index]['identifier'] string Y reward identifier
data['reward_campaign']['rewards'][index]['description'] string Y short-form brand description of the reward e.g. $10 Amazon.com Gift Card
data['reward_campaign']['rewards'][index]['details'] string Y long-form reward details e.g. You can use this gift card to purchase any Amazon.com product
data['reward_campaign']['rewards'][index]['img_url'] string Y URL of the thumbnail image for the reward

Example API call

curl -X GET -H "Authorization: Token token=YOUR_API_KEY" https://api.loyaltybay.co.uk/api/v1/reward_campaigns/REWARD_CAMPAIGN_IDENTIFIER -d uuid=SOME_UNIQUE_USER_ID

Example JSON response

{
  "status": "success",
  "data": {
    "reward_campaign": {
      "name": "Demo conversion optimizer",
      "active": true,
      "identifier": "3eaf974f82668c1b39c9393e0bdb4c0bcc857171",
      "rewards": [
        {
          "name": "Pizza Express £10",
          "identifier": "42c5b38c25f1725363b39c484969dcb2",
          "active": true,
          "description": "£10 Pizza Express eGift Voucher",
          "details": "",
          "img_url": "https://loyaltybay-production.s3.amazonaws.com/reward_products/18/product_logos/api/pizza-express150x150.jpg?1444127986"
        },
        {
          "name": "Amazon £10",
          "identifier": "62c7b02ac196ffe4da452686cae91d9c",
          "active": true,
          "description": "£10 Amazon.co.uk Gift Card",
          "details": "You can use this gift card to purchase any Amazon.co.uk product",
          "img_url": "https://loyaltybay-production.s3.amazonaws.com/reward_products/1/product_logos/api/amazon-150x150.png?1444127977"
        },
        {
          "name": "iTunes £10",
          "identifier": "73217ecb96cd0814b33a4e13ebee680d",
          "active": true,
          "description": "£10 iTunes Code",
          "details": "Give the gift of one-stop entertainment. Each code is redeemable for music, films, TV programmes, games, apps and more on the iTunes Store, the iBookstore, the App Store and the Mac App Store. Recipients can access their content on an iPod, iPad or iPhone, and watch or listen on a computer-Mac or PC.",
          "img_url": "https://loyaltybay-production.s3.amazonaws.com/reward_products/2/product_logos/api/itunes-150x150.png?1444127978"
        },
        {
          "name": "M&S £10",
          "identifier": "ee2624655555076799b4f75346001aa3",
          "active": true,
          "description": "£10 M&S e-gift card",
          "details": "John Lewis electronic gift vouchers can be used for online shopping at johnlewis.com for fashion, home ware, sports and electrical items.",
          "img_url": "https://loyaltybay-production.s3.amazonaws.com/reward_products/4/product_logos/api/marks-and-spencer-white-bg-150x150.png?1444127979"
        }
      ]
    }
  }
}

Choices

A choice needs to be created via the API when a user selects a reward on your site.

Create choice

POST https://api.loyaltybay.co.uk/api/v1/choices

Parameters

name type required description
reward_campaign_identifier string Y identifier of the reward campaign that the user has chosen a reward for
reward_identifier string Y identifier for the reward that the user has chosen - value is available from the result of calling retrieve reward campaign
uuid string Y Unique identifier for the current user. It's important that this id is unique and consistent throughout the process. It is used to figure out which reward to send the user at a later time.

Example API call

curl -X POST -H "Authorization: Token token=YOUR_API_KEY" -d reward_campaign_identifier=REWARD_CAMPAIGN_IDENTIFIER -d reward_identifier=REWARD_IDENTIFIER -d uuid=SOME_UNIQUE_USER_ID https://api.loyaltybay.co.uk/api/v1/choices

Example JSON response

{
  "status": "success"
}

Conversions

Conversions represent the completion of some kind of business process that's important to you, and is the point at which you want to reward your user.

Conversions could be the end of something that happens entirely within an online journey e.g. a user signing up for a subscription to a magazine which starts immediately, or it could include a cooling-off period e.g. a user signs up online for a broadband package, but then must wait 30 days for activation. In the first case, all that is required is a call to the create conversion API method with the appropriate parameters. In the second case, the conversion needs to be deferred, and this can be achieved by making a call to the defer conversion API method when the user has completed the online part of the process, followed by a call to complete deferred conversion

when the process fully completes (e.g. broadband activated after a cooling-off period).

Create conversion

POST https://api.loyaltybay.co.uk/api/v1/conversions

Request parameters

name type required description
uuid string Y Pass the uuid parameter with the value that has been used throughout the signup process.
reward_campaign_identifier string Y identifier of the reward campaign that the user was shown rewards for.
reward_identifier string N identifier of the reward that the user chose. Only pass this when performing a 'combined choice and conversion' see Usage examples.
email string Y The email address of the user to be sent the reward. Note that this value should be URI-escaped
name string N The full name of the user, used to personalise their email as well as infer gender for reporting.

Example API call

curl -X POST -H "Authorization: Token token=YOUR_API_KEY" -d reward_campaign_identifier=REWARD_CAMPAIGN_IDENTIFIER -d uuid=SOME_UNIQUE_USER_ID -d email=alex@nowhere.com  https://api.loyaltybay.co.uk/api/v1/conversions

Example JSON response

{
  "status": "success"
}

Defer conversion

POST https://api.loyaltybay.co.uk/api/v1/conversions/defer

Request parameters

name type required description
reward_campaign_identifier string Y identifier of the reward campaign that the user was shown rewards for
uuid string Y Identifier for the current user. It's important that this id is unique and consistent throughout the process, it is used to figure out which reward to send the user at a later time.
reconciliation_id string Y identifier of the signup process for the user e.g. order number or similar. Used when there is a further completion step necessary e.g. installation of hardware, 30-day cooling off period etc.

Example API call

curl -X POST -H "Authorization: Token token=YOUR_API_KEY"-d reconciliation_id=SOME_ID -d reward_campaign_identifier=REWARD_CAMPAIGN_IDENTIFIER -d uuid=SOME_UNIQUE_USER_ID https://api.loyaltybay.co.uk/api/v1/conversions/defer

Example JSON response

{
  "status": "success"
}

Complete deferred conversion

POST https://api.loyaltybay.co.uk/api/v1/conversions/complete_deferred

Request parameters

name type required description
reconciliation_id string Y Pass reconciliation_id using the same value that was passed in the defer conversion API method call.
email string Y The email address of the user to be sent the reward.
name string N The full name of the user, used to personalise their reward email as well as infer gender for reporting.

Example API call

curl -X POST -H "Authorization: Token token=YOUR_API_KEY" -d reconciliation_id=SOME_ID -d email=alex@nowhere.com  https://api.loyaltybay.co.uk/api/v1/conversions/complete_deferred

Example JSON response

{
  "status": "success"
}

Direct sends

Send reward choice

POST https://api.loyaltybay.co.uk/api/v1/direct_sends/reward_choice

You can use this method to send a reward choice link to your user.

Make sure you pass a unique user ID when calling this method.

Request parameters

name type required description
uuid string Y A unique user id
email string Y The email address to be sent the reward choice.
reward_campaign_identifier string Y Identifier for the reward campaign that you want to send a choice link for.

Example API call

curl -X POST -H "Authorization: Token token=YOUR_API_KEY" -d email=alex@nowhere.com -d uuid=SOME_UNIQUE_USER_ID -d reward_campaign_identifier=REWARD_CAMPAIGN_IDENTIFIER https://api.loyaltybay.co.uk/api/v1/direct_sends/reward_choice

Example JSON response

{
  "status": "success"
}

Reporting

Reward report

GET https://api.loyaltybay.co.uk/api/v1/reporting/rewards/REWARD_IDENTIFIER
You can use this method to find out the status of rewards. The reward identifier you need to pass can be found by calling the retrieve reward campaign method.

Request parameters

None

Response fields

name type always present? description
status string Y whether the call succeeded
message string N (present if error) additional information in case of "error" status
data object N (missing if error) contains the requested or created object
data['reward'] object N (missing if error) representation of the reward report
response fields when data['reward'] is present
data['reward']['name'] string Y reward short name e.g. Amazon $10
data['reward']['identifier'] string Y the reward identifier
data['reward']['remaining_count'] integer Y number of rewards left which are available for collection

Example API call

curl -X GET -H "Authorization: Token token=YOUR_API_KEY" https://api.loyaltybay.co.uk/api/v1/reporting/rewards/REWARD_IDENTIFIER

Example JSON response

{
  "status": "success",
  "data": {
    "reward": {
      "name": "iTunes £10",
      "identifier": "73217ecb96cd0814b33a4e13ebee680d",
      "remaining_count": 22
    }
  }
}