About the API

The API uses a RESTful principle and supports the HTTP verbs GET, POST, PUT, and DELETE for managing resources.
Please note that we are using the HTTPS protocol for securing your data.

The response body is always JSON format.

Obtaining an API key

You need a Heyloyalty account. If you don't have one you can order a demo account here.
In your account under settings -> account information, is your API key and API secret.


When issuing calls to the API, credentials must be provided using HTTP Basic Authentication, with username being the API-key, and the password being a request signature (see below).
Every call to the API must also contain the HTTP header X-Request-Timestamp. The value should be a RFC 1123 representation of the current date/time.

X-Request-Timestamp: Fri, 24 May 2013 13:16:26 GMT

Request signature

The request signature is generated using the API Secret and the value of the X-Request-Timestamp header. It's important that the timestamp used to generate the signature is exactly the same as that sent in the header.

Example of how to generate a request signature:

$signature = base64_encode(hash_hmac('sha256', 'Fri, 24 May 2013 13:16:26 GMT', 'API_SECRET'));

Code example

This example shows how to get members from a list in PHP. It uses the Guzzle HTTP client version 5.0. Read the Guzzle documentation here.

use GuzzleHttp\Client;

define('API_KEY', 'xxxxxxxxxxxxxxxxxxx');
define('API_SECRET', 'xxxxxxxxxxxxxxxxxxxxxxxxxxxx');

$client = new Client();

$host = '';

$request = $client->get($host.'/loyalty/v1/lists/1/members');

$requestTimestamp = gmdate("D, d M Y H:i:s") . ' GMT';

$requestSignature = base64_encode(hash_hmac('sha256', $requestTimestamp, API_SECRET));

$request->setAuth(API_KEY, $requestSignature);

$request->addHeader('X-Request-Timestamp', $requestTimestamp);

$response = $request->send()->json();


Note about .NET (C#)

To achieve access to our API with .NET, the following is an example which can grant you access

using System;
using System.Collections;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Threading.Tasks;

namespace HLListsClient

     *  Heyloyalty api example
     *  Shows in c# how to authenticate and connect to Heyloyalty api.
     *  Uses Microsoft Aspnet WebApi client.
     *  Instal Aspnet Webapi client with package manager console by 
     *  running the code below.
     *  Install-Package Microsoft.AspNet.WebApi.Client

    class Program
        static void Main(string[] args)
            //only block calls in console never in real ui
        //create an asynchronous task
        static async Task RunAsync()
            //instantiating httpclient, "using" takes care off disposal process.
            using (var client = new HttpClient())
                 * Heyloyalty user api settings
                var apiKey = ""; //input your apikey found on your Heyloyalty account
                var apiSecret = ""; //input your apisecret found on your Heyloyalty account
                var apiUrl = "loyalty/v1/";

                 * Heyloyalty partner api settings
                 * Change isPartner to true to use the partner api
                var isPartner = false;

                var partnerApiKey = ""; //this key needs to be given to you by Heyloyalty
                var partnerApiSecret = ""; //this secert needs to be given to you by Heyloyalty
                var partnerApiUrl = "reseller/";

                //if partner variable is set to true, use the partner api settings
                    apiKey = partnerApiKey;
                    apiSecret = partnerApiSecret;
                    apiUrl = partnerApiUrl;

                var timeStamp = DateTime.Now.ToString("R");

                var hmacsha256 = new HMACSHA256(System.Text.Encoding.UTF8.GetBytes(apiSecret));

                var hashstring = BitConverter.ToString(hmacsha256.Hash).Replace("-", "").ToLower();
                var requestSignature = Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(hashstring));

                var authorizationString = Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(apiKey + ":" + requestSignature));

                client.BaseAddress = new Uri("");
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", authorizationString);
                client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

                // HTTP GET
                HttpResponseMessage response = await client.GetAsync(apiUrl+"lists");
                if (response.IsSuccessStatusCode)
                    //Heyloyalty are returning an json array.
                    ArrayList list = await response.Content.ReadAsAsync();

                    * Here we are writing out our first object, but could handle it the way you want.