ReferralCandy API

Introduction

The ReferralCandy API provides a simple interface withJSON-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/v2.2/some-method.json

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

Please note that all timestamps used in our API must be in Unix time format (seconds). For example, use 1625078400 for June 30, 2021, 00:00:00 UTC. Do not use milliseconds (e.g., 1625078400000) or ISO 8601 (e.g., 2021-06-30T00:00:00Z).

Authentication

Each call to the ReferralCandy API requires the sending of the currentUNIX 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.

API Methods

{"message":"Verification Ok"}

{"message": "Success", "campaigns": [{"campaign_id": 123, "campaign_name": "Summer Referral Campaign", "join_url": "https://abc.refr.cc/join/summer-campaign","campaign_state": "ACTIVE"}]}

{"message":"Success","status":"true","referralcorner_urls":[{"campaignId":123,"url":"//refcandy.referralcandy.com/share/BW299X"}]}

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

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

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

{"message":"Success","total_count":2,"contacts":[{"id":800,"first_name":"Contact","last_name":"One","email":"contact1@example.com","purchase_made":true,"purchases":[{"purchased_at":1329738679,"amount":97.0,"currency":"USD"}],"unsubscribed":false},{"id":1250,"first_name":"Contact","last_name":"Two","email":"contact2@example.com","purchase_made":false,"purchases":[],"unsubscribed":false}],"campaignId":123,"limit":100}

{
  "message": "Success",
  "referralcorner_url": "http://refcandy.referralcandy.com/BW299X",
  "referral_link": "http://refcandy.refr.cc/ABCDEF",
  "invite_code": "BW299X",
  "enrollments": [
    {
      "campaignId": 101,
      "enrolled": true,
      "primary": true,
      "referralcorner_url": "http://refcandy.referralcandy.com/BW299X",
      "referral_link": "http://refcandy.refr.cc/ABCDEF",
      "invite_code": "BW299X"
    },
    {
      "campaignId": 102,
      "enrolled": true,
      "primary": false,
      "referralcorner_url": "http://refcandy.referralcandy.com/CX300Y",
      "referral_link": "http://refcandy.refr.cc/GHIJKL",
      "invite_code": "CX300Y"
    }
  ]
}

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

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

{: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}

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

{:message=>"Success", :reward=>{:advocate_email=>"john@example.com", :advocate_name=>"John Smith", :created_at=>1442584289, :description=>"20% discount", :id=>3938282, :status=>"delivered", :type=>"custom"}}

API Clients

Open-source client libraries that handle signature generation for you:

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