Loyalty Bay Reward Sender API

Introduction

The Loyalty Bay Reward Sender API is a REST API callable over HTTPs, which returns JSON data. It allows you to send reward choice emails to your users.

Definitions

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 sets of your users.

Usage Examples

1 - Send reward choice email

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. If your campaign only has a single reward in it, then this API call will send a claim link instead of a link to the choice page.

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.

List reward campaigns

GET https://api.loyaltybay.co.uk/api/v1/reward_campaigns
Returns all of the reward campaigns associated with your API key, alongs with their associated rewards.

Request parameters

None

Response fields

This method call will return active flags for 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']['created_date'] string Y date of campaign creationg in YYYY-MM-DD format
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]['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 user_id=SOME_UNIQUE_USER_ID

Example JSON response

{
  "status": "success",
  "data": {
    "reward_campaign": {
      "name": "Demo conversion optimizer",
      "created_date": "2014-02-07",
      "active": true,
      "identifier": "3eaf974f82668c1b39c9393e0bdb4c0bcc857171",
      "rewards": [
        {
          "name": "iTunes £10",
          "identifier": "73217ecb96cd0814b33a4e13ebee680d",
          "description": "£10 iTunes Code",
          "details": "Perfect for anyone who enjoys apps, games, music, films, TV programmes, books and more.",
          "img_url": "https://loyaltybay-production.s3.amazonaws.com/reward_products/2/product_logos/api/itunes-gift-card.png?1504091920"
        },
        {
          "name": "M&S £10",
          "identifier": "ee2624655555076799b4f75346001aa3",
          "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"
        },
        {
          "name": "Amazon £10",
          "identifier": "62c7b02ac196ffe4da452686cae91d9c",
          "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": "Pizza Express £10",
          "identifier": "42c5b38c25f1725363b39c484969dcb2",
          "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"
        }
      ]
    }
  }
}

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
user_id 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 user_id=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"
}