ReferralCandy API

Introduction

The ReferralCandy API provides a simple interface with JSON-formatted responses to integrate your store with the ReferralCandy referral platform.

ReferralCandy API calls are made to the following URL:

https://my.referralcandy.com/api/v1/some-method.json

(Please note that all API input should be encoded in UTF-8.)


Authentication

Each call to the ReferralCandy API requires the sending of the current UNIX timestamp, Access ID and signature parameters. Your API Access ID can be found on your account settings page. The signature parameter is generated from your API Secret Key which can also be found on your account settings page.

To generate the signature for a particular call to the API, carry out the following steps:

  1. Gather the API call parameters into an array of strings of the format "parameter_name=parameter_value".
  2. Sort the name/value pairs in the array.
  3. Join the array elements into a string.
  4. Prepend the API Secret Key to the string to form a combined string.
  5. The signature is the MD5 of this combined string.

A sample signature calculation is as follows:

  1. ["timestamp=1296664909", "accessID=acihijaklscj", "name=john"]
  2. ["accessID=acihijaklscj", "name=john", "timestamp=1296664909"]
  3. "accessID=acihijaklscjname=johntimestamp=1296664909"
  4. "APISECRETKEYaccessID=acihijaklscjname=johntimestamp=1296664909"
  5. signature = MD5("APISECRETKEYaccessID=acihijaklscjname=johntimestamp=1296664909") = "04535fe455e9f77a90c06e81d7888569"



Response Codes

The ReferralCandy API uses standard HTTP status codes to indicate success or failure of API calls.

HTTP Code Meaning
200 API call was successful.
400 You've made an error in your request. See the message field in the response for details.
401 Authentication credentials provided were incorrect.
404 Unknown API method.
500 A temporary internal server error.

API Methods


Verify Method

Overview
This method lets you verify that authentication for your API calls is set up correctly.


URL
https://my.referralcandy.com/api/v1/verify.json


Request Method
GET


Input Parameters
Field Description Required
timestamp
UNIX timestamp of API call.
yes
accessID
API Access ID.
yes
signature
Calculated signature.
yes

Output Parameters
Field Description
message
A message indicating the outcome of the API call.


Sample Result
{"message":"Verification Ok"}



Purchase Method

Overview

This method lets you register a new purchase at your store. A referral email will be sent to the customer.


URL
https://my.referralcandy.com/api/v1/purchase.json

Request Method
POST

Input Parameters
Field Description Required
first_name
Customer's first name.
yes
last_name
Customer's last name.
yes
email
Customer's email address.
yes
locale
Customer's preferred language. Defaults to campaign's default language if it is not set or not available to the campaign.

This is a complete list of valid values (ISO 639-1 language code):
en, fr, de, es, it, ja, nl, ru, zh-CN, zh-HK, zh-TW.
no
discount_code
Discount code used in the order. Blank if no discount code was used.
yes if discount code was used
accepts_marketing
Whether the customer opted in to marketing (true/false). Defaults to true.
no
order_timestamp
UNIX timestamp of order.
yes
browser_ip
IP address of customer when making the purchase.
yes
user_agent
User agent string of the customer's web browser.
yes
invoice_amount
Total invoice amount for this purchase.
yes
currency_code
ISO 4217 currency code used in order invoice (e.g. USD, GBP, INR).
yes
timestamp
UNIX timestamp of API call.
yes
accessID
API Access ID.
yes
signature
Calculated signature.
yes

Output Parameters
Field Description
message
A message indicating the outcome of the API call.
referralcorner_url
URL of the new customer's Referral Corner.

Sample Result
{"message":"Success","referralcorner_url":"http://refcandy.referralcandy.com/BW299X"}


Get Referrals Method

Overview
This method lets you query for the referrals made by a particular customer over some period of time.

URL
https://my.referralcandy.com/api/v1/referrals.json

Request Method
GET

Input Parameters
Field Description Required
period_from
UNIX timestamp of start of query period.
yes
period_to
UNIX timestamp of end of query period. Defaults to most recent timestamp.
no
customer_email
Customer email address. Return all referrals if not set.
no
timestamp
UNIX timestamp of API call.
yes
accessID
API Access ID.
yes
signature
Calculated signature.
yes

Output Parameters
Field Description
referrals
Array of referred customers and referral timestamps.


Field Description
referral_email
Email address of referred customer.
referral_timestamp
UNIX timestamp when referral purchase was made.
referring_email
Email address of referring customer.
period_from
UNIX timestamp of start of query period.
period_to
UNIX timestamp of end of query period of the results returned. This might not be the same as the period_to value requested since successful referrals can only be detected up till a couple of minutes before the current time.
message
A message indicating the outcome of the API call.

Sample Result
{"message":"Success","referrals":[{"referral_email":"referral1@example.com","referral_timestamp":1329738979,"referring_email":"customer@example.com"},{"referral_email":"referral2@example.com","referral_timestamp":1329738984,"referring_email":"customer@example.com"}],"period_from":1329738679,"period_to":1329739284}


Update Referral Method

Overview
This method lets you update the purchase status of a referred customer. By default, an email is sent out to the customer who made the referral to inform him/her that he/she is not eligible for a recent referral reward.

Example:
Bob makes a purchase at your store, referred by Amy. Bob returns his purchase. Make an 'Update Referral' API call, and set 'returned' to true. By default, Amy gets an email informing her that she is no longer eligible for the referral reward.

URL
https://my.referralcandy.com/api/v1/referral.json

Request Method
POST

Input Parameters
Field Description Required
customer_email
Email address of customer who made the referred purchase.
yes
notify
Whether to notify customer who referred customer specified above that the referral has been disregarded (true/false). Defaults to true.
no
returned
Whether customer has returned his/her purchase (true/false). If 'returned' is set to true, the referral will be disregarded and rewards will not be paid out.
yes
timestamp
UNIX timestamp of API call.
yes
accessID
API Access ID.
yes
signature
Calculated signature.
yes

Output Parameters
Field Description
message
A message indicating the outcome of the API call.
customer_email
Customer email address.
returned
Whether customer has returned his/her purchase.

Sample Result
{"message":"Success","customer_email":"customer@example.com","returned":true}


Get Referrer Method

Overview
This method lets you query for the referrer of a particular customer.

URL
https://my.referralcandy.com/api/v1/referrer.json

Request Method
GET

Input Parameters
Field Description Required
customer_email
Customer email address.
yes
timestamp
UNIX timestamp of API call.
yes
accessID
API Access ID.
yes
signature
Calculated signature.
yes

Output Parameters
Field Description
referrer
Email address of referring customer if one exists, null otherwise.
message
A message indicating the outcome of the API call.

Sample Result
{"message":"Success","referrer":"referrer@example.com"}


Get Contacts Method

Overview
This method lets you query for contacts involved in your referral campaign.

Example:
Query with id = 50 and limit = 100 will return the 100 contacts invited to your referral campaign after (and including) contact with id = 50.

URL
https://my.referralcandy.com/api/v1/contacts.json

Request Method
GET

Input Parameters
Field Description Required
id
Lowest id of contact returned by query. Defaults to 1.
no
limit
Number of contacts to return. Defaults to 100. Capped at 100.
no
timestamp
UNIX timestamp of API call.
yes
accessID
API Access ID.
yes
signature
Calculated signature.
yes

Output Parameters
Field Description
contacts
Array of contacts.


Field Description
id
Unique identifier of contact.
first_name
First name of contact.
last_name
Last name of contact.
email
Email address of contact.
purchase_made
Whether contact made a purchase at the store (true/false).
purchases
Array of purchases made by contact.

Field Description
purchased_at
UNIX timestamp of purchase.
amount
Invoice amount of purchase.
unsubscribed
Whether contact is unsubscribed (true/false).
total_count
Total number of contacts involved in your referral campaign to date.
message
A message indicating the outcome of the API call.

Sample Result
{"message":"Success","total_count":400,"contacts":[{"id":800,"first_name":"Contact","last_name":"One","email":"contact1@example.com","purchase_made":true,"purchases":[{"purchased_at":1329738679,"amount":97.0}],"unsubscribed":false},{"id":1250,"first_name":"Contact","last_name":"Two","email":"contact2@example.com","purchase_made":false,"purchases":[],"unsubscribed":false}]}


Sign Up Method

Overview
This method lets you sign a contact up for your referral program.

URL
https://my.referralcandy.com/api/v1/signup.json

Request Method
POST

Input Parameters
Field Description Required
first_name
Contact's first name.
yes
last_name
Contact's last name.
yes
email
Contact's email address.
yes
timestamp
UNIX timestamp of API call.
yes
accessID
API Access ID.
yes
signature
Calculated signature.
yes

Output Parameters
Field Description
message
A message indicating the outcome of the API call.
referralcorner_url
URL of the contact's Referral Corner.
referral_link
URL of the contact's unique referral link.

Sample Result
{"message":"Success","referralcorner_url":"http://refcandy.referralcandy.com/BW299X","referral_link":"http://refcandy.refr.cc/ABCDEF"}


In-app Invite Method

Overview
This method lets you send out an in-app invite to a contact. This counts against your in-app invite quota.

URL
https://my.referralcandy.com/api/v1/invite.json

Request Method
POST

Input Parameters
Field Description Required
email
Contact's email address.
yes
timestamp
UNIX timestamp of API call.
yes
accessID
API Access ID.
yes
signature
Calculated signature.
yes

Output Parameters
Field Description
message
A message indicating the outcome of the API call.
invite
The number of in-app invites remaining for your campaign.

Sample Result
{"message":"Success","invites":500}


Troubleshooting

Signature Calculation

A common mistake is that the same URI encoded API params for making a POST request are also used to compute the signature.

For example, if you had the following params:

{email: "abc@xyz.com", name: "john & jane"}

Your POST body would be URI encoded:

email=abc%40xyz.com&name=john+%26+jane

However, your MD5 should be computed with the literal string (not the URI encoded string):

MD5("...email=abc@xyz.comname=john & jane...")