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.

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

Output Parameters

Sample Result

{"message":"Verification Ok"}

Purchase Method

Overview

This method lets you register a new purchase at your store.

URL

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

Request Method

POST

Input Parameters

Output Parameters

Sample Result

{"message":"Success","referralcorner_url":"http://refcandy.referralcorner.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

Output Parameters

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.

URL

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

Request Method

POST

Input Parameters

Output Parameters

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

Output Parameters

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

Output Parameters

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

Output Parameters

Sample Result

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