Referral Endpoints - TrackStreet Reverb API

Referrals

This set of API functions deals with managing referral data.

Note: The word 'customer' can be used interchangeably with the word 'advocate' in terms of terminology.

Fields that are marked with [REQUIRED] are needed with the API function call. Other fields are optional.

GET - Single Referral Record

Fetch data on a single referral record. Record will give details on who referred who, reward earned, and incentive used by incoming referrred customer.

https://reverbapi.trackstreet.com/api/v1/referrals/<referral_uuid>

Variable	Description	Options	Default
referral_uuid	The internal unique ID for the referral record

Example Call:

PHP

<?php

// The consumer key and secret can be obtained from website settings in Reverb admin app
$consumer_key = 'REVERB_API_CONSUMER_KEY';
$consumer_secret = 'REVERB_API_CONSUMER_SECRET';

// Build and make API call
$referral_uuid = 'XXXX-XXXX-XXXX-XXXX-XXXX';

$url = 'https://reverbapi.trackstreet.com/api/v1/referrals/' . $referral_uuid;

// @link http://php.net/manual/en/function.curl-setopt.php
$curl_handle = curl_init();
curl_setopt($curl_handle, CURLOPT_URL, $url);
curl_setopt($curl_handle, CURLOPT_USERPWD, $consumer_key . ':' . $consumer_secret);
curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
$response = curl_exec($curl_handle);
curl_close($curl_handle);

echo($response);

?>

Example Response:

JSON

{
    "response": {
        "code": "200",
        "message": "OK: The request was successful. See response body for additional data.",
        "data": {
            "referral": {
                "uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                "campaign_uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                "referrer_advocate_uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                "referred_customer_uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                "referred_order_uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                "level": 1,
                "short_code": "VG7UJK"
                "reward_earned": "5.00"
                "reward_type": "commission",
                "reward_payed": "false",
                "incentive_used": "COUPON20",
                "incentive_type": "coupon",
                "referral_date": "2014-03-14T05:49:54-07:00",
            }
        }
    }
}

GET - Multiple Referral Records

Find all referral records for a customer.

https://reverbapi.trackstreet.com/api/v1/referrals/<customer_uuid>

Variable	Description	Options	Default
customer_uuid	The internal unique ID for a customer

Example Call:

PHP

<?php

// The consumer key and secret can be obtained from your settings area in the Reverb admin app
$consumer_key = 'REVERB_API_CONSUMER_KEY';
$consumer_secret = 'REVERB_API_CONSUMER_SECRET';

// build and make API call
$referral_uuid = 'XXXX-XXXX-XXXX-XXXX-XXXX';

$url = 'https://reverbapi.trackstreet.com/api/v1/referrals/' . $referral_uuid;

// @link http://php.net/manual/en/function.curl-setopt.php
$curl_handle = curl_init();
curl_setopt($curl_handle, CURLOPT_URL, $url);
curl_setopt($curl_handle, CURLOPT_USERPWD, $consumer_key . ':' . $consumer_secret);
curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
$response = curl_exec($curl_handle);
curl_close($curl_handle);

echo($response);

?>

Example Response:

JSON

{
    "response": {
        "code": "200",
        "message": "OK: The request was successful. See response body for additional data.",
        "data": {
            "referrals": {
                {
                    "uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                    "campaign_uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                    "referrer_advocate_uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                    "referred_customer_uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                    "referred_order_uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                    "level": 1,
                    "short_code": "VG7UJK"
                    "reward_earned": "5.00"
                    "reward_type": "commission",
                    "reward_payed": "false",
                    "incentive_used": "COUPON20",
                    "incentive_type": "coupon",
                    "referral_date": "2014-03-14T05:49:54-07:00"
                },
                {
                    "uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                    "campaign_uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                    "referrer_advocate_uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                    "referred_customer_uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                    "referred_order_uuid": "XXXX-XXXX-XXXX-XXXX-XXXX",
                    "level": 1,
                    "short_code": "FGJUJK"
                    "reward_earned": "3.00"
                    "reward_type": "commission",
                    "reward_payed": "false",
                    "incentive_used": "FGJUJK",
                    "incentive_type": "coupon",
                    "referral_date": "2014-04-24T09:53:54-07:00"
                }
            }
        }
    }
}

POST - Create Referral Record

Create a new single referral record. A referral links an advocate to a conversion action, like a purchase or a referred enrollment of a new advocate.

https://reverbapi.trackstreet.com/api/v1/referrals

Variable	Description	Options	Default
website_uuid	The internal unique ID for the website the customer belongs to
campaign_uuid	The internal unique ID for the campaign the referral qualifies for
reward_action_type	The type of action conversion that advocate has completed in order to earn the defined reward.	This is a numeric value that represents the following conversion types that can earn a reward: 1 = Referred Purchase 2 = Referred Enroll 3 = Reached # of clicks to earn a reward 4 = Reached # of shares to earn a reward
qualified_amount	The numeric value that qualified the advocate completing a conversion requirement for earning a reward. This could be a number of shares, number of clicks, etc. that were required to earn this reward. This field is required for conversion actions that require a number of activity to qualify for reward. reward_action_type: 3 or 4
referrer_advocate_uuid	The internal unique ID for the customer who made the referral. This field is required.
referrer_order_uuid	The internal Reverb unique ID for an order that was made by the referrer. This field is required if conversion action was a referred purchase.
referrer_offer_uuid	The internal Reverb unique ID for the offer that a referrer shared from that resulted in referral conversion. This field is optional.
referred_customer_uuid	The internal unique ID for the incoming customer that was referred. This field is required if conversion was referred purchase or a referred enrollment.
referred_order_uuid	The internal unique UUID for order placed by the referred customer. This field is required if conversion was a referred purchase.
referred_order_number	Another way that you can attach a referred order to the referral is by providing the order number used for the order with your website. This field is required if conversion was a referred purchase and order UUID not provided.
referred_offer_uuid	The internal Reverb unique ID for the offer that a referrer shared from that resulted in referral conversion. This field is optional.
referred_level	Numeric value for multi-level programs; level at which referral took place. This field is required if conversion action was a referred purchase.		1
referred_through
reward_amount	If you would like to specific a specific dollar amount that you would like to give for the reward it can be passed into this field. If value not provided, then the Reverb will use the amount you have defined for the reward in the settings for the campaign. This field is optional.
incentive_amount	If you would like to specific a specific dollar amount that was used as the incentive by the referred advocate, it can be passed into this field. If value not provided, then the Reverb will use the amount you have defined for the incoming advocate incentive in the settings for the campaign. This field is optional.
is_qualified_for_reward	With this field you can indicate if the referrer advocate did, or did not, qualify for the reward This field is optional.	0 = Referrer advocate did not qualify for reward. 1 = Referrer advocate did qualify for reward	1
is_qualified_for_incentive	With this field you can indicate if the referred advocate did, or did not, qualify for the incentive. This field is optional.	0 = Referred advocate did not qualify for reward. 1 = Referred advocate did qualify for reward	1
number_of_referrals	A numeric value indicating how many referrals this advocate has completed. This field is optional, and if not specified will be maintained by Reverb.
payment_status
status	Status of the referral record. This field is optional.	0 = Inactive/Deleted 1 = Active	1
transaction_uuid	If a transaction (such as a payout) is with this referral record, then the UUID for the transaction record will be saved with this field. This field is optional, and if not specified will be maintained by Reverb.
cooling_period_end	Indicate an end date for when cooling period will complete for referral record, and it can be approved. This field is optional, and if not specified will be maintained by Reverb.	Format: YYYY-MM-DD HH:MM:SS
share_code	If you have a coupon code or offer share code that was used you can pass it by this parameter. If one is not provided, then we will use other tracking elements to determine referral connection. This field is optional, and if not specified will be maintained by Reverb.

Example Call:

PHP

<?php

// The consumer key and secret can be obtained from website settings in Reverb admin app
$consumer_key = 'REVERB_API_CONSUMER_KEY'; // string
$consumer_secret = 'REVERB_API_CONSUMER_SECRET'; // string

$website_uuid = 'XXXX-XXXX-XXXX-XXXX-XXXX';

// Need to use an order that has not been connected to a referral record
$referred_order_uuid = 'XXXX-XXXX-XXXX-XXXX-XXXX';

$campaign_uuid = 'XXXX-XXXX-XXXX-XXXX-XXXX';
$referrer_advocate_uuid = 'XXXX-XXXX-XXXX-XXXX-XXXX';
$referred_customer_uuid = 'XXXX-XXXX-XXXX-XXXX-XXXX';

// Uncomment the conversion action that you would like to test
$reward_action_type = 1; // CampaignRewardAction_PURCHASE
//$reward_action_type = 2; // CampaignRewardAction_ENROLL
//$reward_action_type = 3; // CampaignRewardAction_CLICKS
//$reward_action_type = 4;  // CampaignRewardAction_SHARES

$params_array = array(
    'website_uuid' => $website_uuid,
    'campaign_uuid' => $campaign_uuid,
    'referrer_advocate_uuid' => $referrer_advocate_uuid,
    'referred_customer_uuid' => $referred_customer_uuid,
    'referred_order_uuid' => $referred_order_uuid,
    'level' => 1, // change this if campaign has multiple level rewarding for referred purchases
    'reward_action_type' => $reward_action_type,
);

if ($reward_action_type == 3)
{
    $params_array['qualified_amount'] = 2000;
}

if ($reward_action_type == 4)
{
    $params_array['qualified_amount'] = 150;
}

$params = json_encode($params_array);

$url = 'https://' . $this->config->item('reverb_api_domain') . '/api/v1/referrals';

$curl_handle = curl_init();

curl_setopt($curl_handle, CURLOPT_URL, $url);
curl_setopt($curl_handle, CURLOPT_USERPWD, $consumer_key . ':' . $consumer_secret);
curl_setopt($curl_handle, CURLOPT_POST, 1);
curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $params);
curl_setopt($curl_handle, CURLOPT_FAILONERROR, TRUE);
curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);

// Uncomment these lines if you are getting SSL cert errors, but be aware that it opens up potential for security threats
// curl_error(): SSL certificate problem: unable to get local issuer certificate
// see https://stackoverflow.com/questions/15135834/php-curl-curlopt-ssl-verifypeer-ignored
// curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, 0);
// curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, 0);

$curl_response = curl_exec($curl_handle);

echo '$curl_response: ' . var_export($curl_response, TRUE) . PHP_EOL;

if ($curl_response === FALSE) 
{
    echo 'curl_errno(): ' . curl_errno($curl_handle) . PHP_EOL;
    echo 'curl_error(): ' . htmlspecialchars(curl_error($curl_handle)) . PHP_EOL;
    echo 'curl_getinfo(): ' . curl_getinfo($curl_handle, CURLINFO_HTTP_CODE) . PHP_EOL;
}

curl_close($curl_handle);

echo 'Done' . PHP_EOL;
exit();

?>

Example Response:

JSON

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful.",
  }
}