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/v2/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 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/v2/verify.json

Request Method

POST

Input Parameters

Parameter
Required
Description
accessID
Yes
Your Access ID
secretKey
Yes
Your Secret Key (for verification only)

Output Parameters

Parameter
Description
message
Status message
status
Status indicator

Sample Result

{"message":"Success","status":"success"}

Campaigns Method

Overview

This method retrieves a list of all campaigns associated with your account or a specific client. It returns campaign IDs, names, and join URLs that can be used for integration with other API endpoints. This is particularly useful for discovering available campaigns and their identifiers for use with campaign-specific operations like signup, contacts, and invite endpoints. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

Example

Your account has multiple referral/affiliate campaigns running. Use the Campaigns API to retrieve all available campaigns, then use the campaign IDs to enroll customers or fetch campaign-specific data through other endpoints.

URL

https://my.referralcandy.com/api/v2/campaigns.json

Request Method

GET

Input Parameters

Parameter
Required
Description
accessID
Yes
API Access ID
timestamp
Yes
UNIX timestamp of API call
signature
Yes
Calculated signature

Output Parameters

Parameter
Description
message
A message indicating the outcome of the API call
campaigns
Array of campaign objects containing campaign information
campaigns[].campaign_id
Unique identifier for the campaign. Use this ID with other API endpoints
campaigns[].campaign_name
Human-readable name of the campaign
campaigns[].join_url
Direct URL for customers to join this specific campaign

Sample Result

{
 "message": "Success",
 "campaigns": [
   {
     "campaign_id": 123456,
     "campaign_name": "Summer Referral Program",
     "join_url": "https://mystore.referralcandy.com/join/summer2024"
   },
   {
     "campaign_id": 789012,
     "campaign_name": "VIP Customer Rewards",
     "join_url": "https://mystore.referralcandy.com/join/vip-rewards"
   }
 ]
}

Purchase Method

Overview

This method lets you register a new purchase at your store and get referral URLs for all enrolled campaigns. 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/v2/purchase.json

Request Method

POST

Input Parameters

Parameter
Required
Description
accessID
Yes
Your Access ID
email
Yes
Customer's email address
firstName
Yes
Customer's first name
lastName
No
Customer's last name
invoiceNumber
Yes
Unique invoice/order number
orderTimestamp
Yes
Unix timestamp of the order
receiptTotal
Yes
Total order amount
currencyCode
No
Currency code (e.g., "USD")
referrerCode
No
Referral code used
timestamp
Yes
Unix timestamp
signature
Yes
MD5 signature
The referrerCode will be used to help identify who referred this purchase.

Output Parameters

Parameter
Description
message
Status message
status
Status indicator
referralcorner_urls
Array of campaign URLs with campaignId and url

Sample Results

{"message":"Success","status":"success","referralcorner_urls":[{"campaignId":123456,"url":"https://mystore.referralcandy.com/ABC123"},{"campaignId":789012,"url":"https://vip.referralcandy.com/XYZ789"}]}

{"message":"Success","status":"success","referralcorner_urls":[]}

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/v2/referrals.json

Request Method

GET

Input Parameters

Parameter
Required
Description
accessID
Yes
Your Access ID
campaignId
No
Filter by specific campaign
period_from
No
Unix timestamp for start of period
period_to
No
Unix timestamp for end of period
timestamp
Yes
Unix timestamp
signature
Yes
MD5 signature

Output Parameters

Parameter
Description
message
Status message
referrals
Array of referral objects
period_from
Start period timestamp
period_to
End period timestamp

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 track a referral purchase and attribute it to the referrer. 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/v2/referral.json

Request Method

POST

Input Parameters

Parameter
Required
Description
accessID
Yes
Your Access ID
email
Yes
Referee's email address
firstName
Yes
Referee's first name
lastName
No
Referee's last name
invoiceNumber
Yes
Unique invoice/order number
orderTimestamp
Yes
Unix timestamp of the order
receiptTotal
Yes
Total order amount
currencyCode
No
Currency code
referrerCode
Yes
Referral code used
timestamp
Yes
Unix timestamp
signature
Yes
MD5 signature

Output Parameters

Field
Description
message
Status message
campaignId
Campaign ID where referral was tracked

Sample Result

{"message":"Success","campaignId":123456}

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/v2/referrer.json

Request Method

GET

Input Parameters

Field
Required
Description
accessID
Yes
Your Access ID
email
Yes
Email to check for referrer
timestamp
Yes
Unix timestamp
signature
Yes
MD5 signature

Output Parameters

Parameter
Description
message
Status message
referrer
Referrer's email address (null if none)
campaignId
Campaign ID (null if no referrer)

Sample Result

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

Contacts Method

Overview

Example:
Query with id = 50 and limit = 100 will return the 100 contacts invited to your first campaign after (and including) contact with id = 50.

URL

https://my.referralcandy.com/api/v2/contacts.json

Request Method

GET

Input Parameters

Parameter
Required
Description
accessID
Yes
Your Access ID
campaignId
Yes
Campaign to filter contacts
email
No
Filter by specific email
name
No
Filter by name (partial match)
limit
No
Number of results (default: 100, max: 1000)
offset
No
Pagination offset
timestamp
Yes
Unix timestamp
signature
Yes
MD5 signature

Output Parameters

Parameter
Description
message
Status message
campaignId
Campaign ID
contacts
Array of contact objects with details
total
Total number of contacts
limit
Results limit applied
offset
Results offset applie

Sample Result

{"message":"Success","campaignId":123456,"contacts":[{"email":"john@example.com","firstName":"John","lastName":"Doe","referralCode":"JOHN123","referralUrl":"https://mystore.referralcandy.com/JOHN123","enrolledAt":"2024-01-01T00:00:00Z","referralsCount":5,"rewardsEarned":3,"status":"active"}],"total":150,"limit":10,"offset":0}

Signup Method

Overview

This method lets you enroll a contact into a specific campaign. 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/v2/signup.json

Request Method

POST

Input Parameters

Field
Required
Description
accessID
Yes
Your Access ID
campaignId
Yes
Campaign to enroll contact in
email
Yes
Contact's email address
firstName
Yes
Contact's first name
lastName
No
Contact's last name
timestamp
Yes
Unix timestamp
signature
Yes
MD5 signature

Output Parameters

Parameter
Description
message
Status message
status
Status indicator
referralcorner_url
Referral corner URL for the contact

Sample Result

{"message":"Success","status":"success","referralcorner_url":"https://mystore.referralcandy.com/ABC123"}

Invite Method

Overview

This method lets you send campaign-specific invitation emails to contacts. 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/v2/invite.json

Request Method

POST

Input Parameters

Parameter
Required
Description
accessID
Yes
Your Access ID
campaignId
Yes
Campaign to send invites for
emails
Yes
Array of email addresses (max: 50)
subject
No
Custom email subject
message
No
Custom email message
timestamp
Yes
Unix timestamp
signature
Yes
MD5 signature

Output Parameters

Parameter
Description
message
Status message
invitesSent
Number of invites sent
campaignId
Campaign ID

Sample Result

{"message":"Success","invitesSent":2,"campaignId":123456}

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/v2/unsubscribed.json

Request Method

PUT

Input Parameters

Parameter
Required
Description
accessID
Yes
Your Access ID
email
Yes
Contact's email address
unsubscribed
Yes
True to unsubscribe, false to resubscribe
timestamp
Yes
Unix timestamp
signature
Yes
MD5 signature

Output Parameters

Parameter
Description
message
Status message
email
Contact's email address
unsubscribed
Subscription status

Sample Result

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

Get Rewards Method

Overview

This method lets you query for rewards for contacts, optionally filtered by campaign. 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/v2/rewards.json

Request Method

GET

Input Parameters

Parameter
Required
Description
accessID
Yes
Your Access ID
campaignId
No
Filter rewards by campaign
email
No
Filter by contact email
status
No
Filter by status: "pending", "delivered", "cancelled"
limit
No
Number of results (default: 100, max: 1000)
offset
No
Pagination offset
timestamp
Yes
Unix timestamp
signature
Yes
MD5 signature

Output Parameters

Parameter
Description
message
Status message
campaignId
Campaign ID (if filtered by campaign)
rewards
Array of reward objects with details
total
Total number of rewards
limit
offset
Results limit applied
Results offset applied

Sample Result

{"message":"Success","campaignId":123456,"rewards":[{"id":"RWD001","email":"john@example.com","type":"cash","amount":10.00,"currency":"USD","status":"delivered","earnedAt":"2024-01-15T10:00:00Z","deliveredAt":"2024-01-16T09:00:00Z","referralInvoice":"INV-67890"}],"total":45,"limit":20,"offset":0}

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 account is suspended and will return a HTTP 403 Forbidden status code.

URL

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

Request Method

GET

Input Parameters

Parameter
Required
Description
accessID
Yes
Your Access ID
reward_id
Yes
Reward ID to query purchases for
timestamp
Yes
Unix timestamp
signature
Yes
MD5 signature

Output Parameters

Parameter
Description
message
Status message
referred_purchases
Array of purchase objects 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/v2/rewards.json

Request Method

POST

Input Parameters

Parameter
Required
Description
accessID
Yes
Your Access ID
reward_id
Yes
Reward ID to update
status
Yes
New status for the reward
timestamp
Yes
Unix timestamp
signature
Yes
MD5 signature

Output Parameters

Parameter
Description
message
Status message
reward
Updated reward object

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