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.
403
Forbidden. Authentication was successful but the method is not available. See the message and reason fields for details.
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. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

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.
reason
Further information provided about the response. This field is returned only in certain cases.

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. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

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, pt-BR.
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
external_reference_id
An ID that can be used to track this purchase externally.
no
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.
reason
Further information provided about the response. This field is returned only in certain cases.
referralcorner_url
If the customer is enrolled, this will return the URL of the new customer's Portal Sharing Page. If the customer is not enrolled, this field will not be returned.

Sample Results

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

{"message":"Success"}

Referrals Method

Overview

This method lets you query for referred purchases made over some period of time. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

URL

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

Request Method

GET

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.
external_reference_id
An ID that can be used to track this referred purchase externally.
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.
reason
Further information provided about the response. This field is returned only in certain cases.

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. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

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.
reason
Further information provided about the response. This field is returned only in certain cases.
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. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

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.
reason
Further information provided about the response. This field is returned only in certain cases.

Sample Result

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

Contacts Method

Overview

This method lets you query for contacts involved in your referral campaign. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

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).
purchase_made
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.
reason
Further information provided about the response. This field is returned only in certain cases.

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 exists, you can use this method to retrieve the advocate's referral link and Portal Sharing Page address. This method is not available when the campaign is paused or stopped and will return a HTTP 403 Forbidden status code.

URL

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

Request Method

POST

Input Parameters

Field
Description
Required
first_name
Advocate's first name.
yes
last_name
Advocate's last name.
yes
email
Advocate'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.
reason
Further information provided about the response. This field is returned only in certain cases.
referralcorner_url
URL of the advocate's Portal Sharing Page.
referral_link
URL of the advocate's unique referral link.
invite_code
The latest invite code(AIC) of the advocate.

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. This method is not available when the campaign is paused or stopped and will return a HTTP 403 Forbidden status code.

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.
reason
Further information provided about the response. This field is returned only in certain cases.
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. This method is not available when the campaign is stopped and will return a HTTP 403 Forbidden status code.

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.
reason
Further information provided about the response. This field is returned only in certain cases.
email
Customer email address.
unsubscribed
Whether customer is unsubscribed.

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. This method is not available when the campaign is stopped and will return a HTTP 403 Forbidden status code.

URL

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

Request Method

GET

Input Parameters

Field
Description
Required
email
When given, the result only contains rewards from the advocate with this email address.
no
since_id
When given, the result starts from the next matching reward earned after the specified reward ID. Otherwise, the result starts with the first matching reward.
no
status
When specified, the result contains rewards with the matching status. Otherwise, the result contains rewards matching all statuses. Accepted values are pending_fulfillment, delivered.
no
type
When specified, the result contains rewards with the matching type. Otherwise, the result contains rewards matching all types. Accepted values are cash, coupon, custom, none.
no
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.
rewards
The first 200 matching rewards.
since_id
The value specified in the request if available.
status
The value specified in the request if available.
type
The value specified in the request if available.

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. This method is not available when the campaign is stopped and will return a HTTP 403 Forbidden status code.

URL

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

Request Method

GET

Input Parameters

Field
Description
Required
reward_id
The ID of the reward.
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.
reason
Further information provided about the response. This field is returned only in certain cases.
referred_purchases
The list of the referred purchases that is associated with the reward.

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. This method is not available when the campaign is stopped and will return a HTTP 403 Forbidden status code.

URL

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

Request Method

POST

Input Parameters

Field
Description
Required
id
The ID of the reward.
yes
status
The status of the reward. Accepted values are pending_fulfillment, delivered.
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 if available.
reason
Further details provided to help understand the response. This field is returned only in certain cases.
messages
A list of messages indicating the outcome of the API call if available.
reward
The updated reward.

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