Resources

Loyalty Bay Rewards Hub API

Introduction

The Loyalty Bay Rewards Hub API is a REST API callable over HTTPS, which returns JSON data. It allows you to send reward and 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

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, along 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_campaigns'] array N (missing if error) array of JSON objects representing each reward campaign
reward campaign JSON object fields
data['reward_campaigns'][index]['name'] string Y campaign short name
data['reward_campaigns'][index]['created_date'] string Y date of campaign creationg in YYYY-MM-DD format
data['reward_campaigns'][index]['active'] boolean Y whether the campaign is on or off
data['reward_campaigns'][index]['identifier'] string Y campaign identifier
data['reward_campaigns'][index]['rewards'] array Y array of objects representing the rewards for this campaign
reward JSON object fields
data['reward_campaigns'][index]['rewards'][index]['name'] string Y reward short name e.g. Amazon $10
data['reward_campaigns'][index]['rewards'][index]['identifier'] string Y reward identifier
data['reward_campaigns'][index]['rewards'][index]['description'] string Y short-form brand description of the reward e.g. $10 Amazon.com Gift Card
data['reward_campaigns'][index]['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_campaigns'][index]['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

Example JSON response

{
  "status": "success",
  "data": {
    "reward_campaigns": [
      {
        "name": "your campaign name",
        "created_date": "2017-01-11",
        "active": true,
        "identifier": "ABCD1234",
        "rewards": [
          {
            "name": "Amazon £10",
            "identifier": "EFGH5678",
            "description": "£50 Amazon.co.uk Gift Card",
            "details": "You can use this gift card to purchase any Amazon.co.uk product",
            "img_url": "https://dummy-domain.com/amazon-image1.png"
          }
        ]
      }
    ]
  }
}

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 claim or reward choice link to your user (depending on whether there are multiple rewards in the campaigns or not).

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