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. no
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, da, no, sv. 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 Portal Sharing Page.

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

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 Advocate's email address. Return referred purchases made by advocate if set. Return all referred purchases if not set. no
pending_review_only Whether to only return referred purchases that are pending the review period (true/false). Defaults to false - this returns referred purchases regardless of review period status. 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 advocate who made the referral.
review_period_over Whether the review period for this referred purchase is over.
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}

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}

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

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

Signup 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 Portal Sharing Page.
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"}

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}

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

Field Description Required
email Contact's email address. yes
unsubscribed Whether to unsubscribe or resubscribe contact (true/false). 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.
email Customer email address.
unsubscribed Whether customer is unsubscribed.

Sample Result

{"message":"Success","email":"contact1@example.com","unsubscribed":true}

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...")