.jpg)
.webp)
ReferralCandy API
Introduction
The ReferralCandy API provides a simple interface with JSON-formatted responses to integrate your store with the ReferralCandy referral platform.
(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:
Gather the API call parameters into an array of strings of the format"parameter_name=parameter_value".
Sort the name/value pairs in the array.
Join the array elements into a string.
Prepend the API Secret Key to the string to form a combined string.
The signature is the MD5 of this combined string.
A sample signature calculation is as follows:
["timestamp=1296664909", "accessID=acihijaklscj", "name=john"]
["accessID=acihijaklscj", "name=john", "timestamp=1296664909"]
"accessID=acihijaklscjname=johntimestamp=1296664909"
"APISECRETKEYaccessID=acihijaklscjname=johntimestamp=1296664909"
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.
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
Output Parameters
Sample Result
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
Output Parameters
Sample Result
{"message":"Success","referralcorner_url":"http://refcandy.referralcandy.com/BW299X"}
Referrals Method
Overview
This method lets you query for referred purchases made over some period of time.
URL
https://my.referralcandy.com/api/v1/referrals.json
Request Method
GET
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}
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
Output Parameters
Sample Result
{"message":"Success","customer_email":"customer@example.com","returned":true}
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"}
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}]}
Signup Method
Overview
This method lets you sign an advocate up for your referral program. If the advocate already exsits, you can use this method to retrieve the advocate's referral link and Portal Sharing Page address.
URL
https://my.referralcandy.com/api/v1/signup.json
Request Method
POST
Input Parameters
Output Parameters
Sample Result
{"message":"Success","referralcorner_url":"http://refcandy.referralcandy.com/BW299X","referral_link":"http://refcandy.refr.cc/ABCDEF","invite_code":"BW299X"}
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
Output Parameters
Sample Result
{"message":"Success","invites":500}
Unsubscribed Method
Overview
This method lets you unsubscribe and resubscribe a contact in your referral program.
URL
https://my.referralcandy.com/api/v1/unsubscribed.json
Request Method
PUT
Input Parameters
Output Parameters
Sample Result
{"message":"Success","email":"contact1@example.com","unsubscribed":true}
Get Rewards Method
Overview
This method lets you query for rewards which match some criteria.
URL
https://my.referralcandy.com/api/v1/rewards.json
Request Method
GET
Input Parameters
Output Parameters
Sample Result
{:message=>"Success", :rewards=>[{:advocate_email=>"john@example.com", :advocate_name=>"John Smith", :created_at=>1442584289, :description=>"20% discount", :id=>2, :status=>"delivered", :type=>"custom"}, {:advocate_email=>"alice@example.com", :advocate_name=>"Alice Bob", :created_at=>1442584426, :description=>"20% discount", :id=>3, :status=>"pending_fulfilment", :type=>"custom"}], :since_id=>1}
Reward Purchases Method
Overview
This method lets you query for the referred purchases that are associated with a reward.
URL
https://my.referralcandy.com/api/v1/reward_purchases.json
Request Method
GET
Input Parameters
Output Parameters
Sample Result
{"message":"Success", "referred_purchases":[{"id":1, "external_reference_id":"ORDER_1", "purchaser_email":"john@example.com"},{"id":2, "external_reference_id":"ORDER_2", "purchaser_email":"alice@example.com"}]}
Post Rewards Method
Overview
This method lets you update a custom reward.
URL
https://my.referralcandy.com/api/v1/rewards.json
Request Method
POST
Input Parameters
Output Parameters
Sample Result
{:message=>"Success", :reward=>{:advocate_email=>"john@example.com", :advocate_name=>"John Smith", :created_at=>1442584289, :description=>"20% discount", :id=>3938282, :status=>"delivered", :type=>"custom"}}
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...")
