v1 API Documentation

Released: 9/20/13.

API EndPoint
https://api.expectreferrals.com/v1
Before you Begin

Prior to getting too deep into our documentation, please note that the Expect Referrals API is not freely available to the public.
You are required to have an active Expect Referrals account (in good financial standing) with a
Professional plan.

Before you run away thinking “How am I supposed to know if this will work for my business if it requires a paid account?”, don’t fret –
we have a Risk Free Trial on our paid plans, including the Professional plan! So you can
sign up, build and test your application logic for free for 30 days, and if you aren’t satisfied, you can cancel without ever getting
billed! We’ve got you covered. So sign up, start building, and see how easy it is to begin integrating our referral marketing platform.

Getting Started

If you are new to the Expect Referrals API, this is the right place to be looking at. By following the steps below, you can be up and
building your application logic in no time flat. So lets begin:

Step 1:

Log in to Expect Referrals

Step1

Step 2:

Go to the ‘My Account’ Section
Step2

Step 3:

Write down your APIKey – this is your unique account identifier for your application.
Step3

Step 4:

Write down or Generate your APISecret – this acts as your private encryption key used to send encrypted data to Expect Referrals so we can verify
that it is you that generating API calls. This key should be kept private as best as possible (in the case of using a javascript API wrapper, this
may prove difficult), so if you feel it has been compromised you have the capability of re-generating it at any time.
Step4

Step 5:

Authorize the domain that you want to be using as your API connection point. This will be used as a secondary form of security to validate that requested
API communications only come from an authorized domain of your choosing.
Step5

Step 6:

You must upload a small html verification file to the root of your domain and click ‘Verify’ to complete the authorization step. After your domain
has been verified, you absolutely may delete our verification file from your root to keep your files nice and tidy.
Step6

Step 7:

You are ready to start building and connecting with our API! You may want to jump over to our API Wrapper Downloads section to
download one of our already built API wrappers to make getting started even easier, or if you are anxious to see the functionality, jump down to our
API Methods section.

Otherwise keep on reading and learning.

Headers & Security

This section describes how information is securely transmitted and managed over our API, using a combination of SSL, Cryptography, and matching key/value pairs
to ensure that all of your requests are safely transported and handled as best as possible.

First off, our API endpoint only allows communication over a secure channel. All other requests will be automatically rejected.
Always ensure that your API requests are being sent to our HTTPS:// endpoint to ensure that your request is being received.

Second, there are two custom headers that the Expect Referrals API requires you to send with each request in order to authenticate your requests:

ERH:
{Your_HMAC_Encryption}
ORIGIN:
{Your_Authenticating_Domain}

The ERH header (which stands for Expect Referrals HMAC) is cryptographic auhentication code that verifies that
the data that you sent has not been altered with along transport. We utilize a SHA-512 encryption on the posted data using your
APISecret as the encryption key. If you are unfamiliar with this process, you can check out wikipedia, to find out more about HMAC.
All data must be sorted on keys, alphabetically ascending, prior to creating your HMAC value.

You will receive the following response if you have not correctly sent your ERH header:

{
   Valid: false,
   ResponseCode: "107",
   Message: "Invalid Parameters"
}

The ORIGIN header contains the domain name that you verified while setting up your API key. Yes, we know that this can be easily spoofed, however we feel this does add another level of key/value pairs that you are in control of. The ORIGIN that is sent through must be validated through our My Accounts page prior to use. You will receive the following response if you have not correctly sent your ORIGIN header:

{
   Valid: false,
   ResponseCode: "105",
   Message: "Invalid Requestor"
}
HTTP Status Codes

Refer to the table below for the HTTP Status codes that are returned by the Expect Referrals API, and what they represent.

200 (OK):
Your API Request was successfully handled.
(Note – this doesn’t mean a successful response was returned.)
401 (Unauthorized):
You have exceeded our 15 minute or 24 hour API request threshold limit.
403 (Forbidden):
Your request was not sent over HTTPS
5xx (Unavailable):
Our API service is currently unavailable or handling too many concurrent requests.
API Rate Limiting

All API requests are tracked by both APIKey as well as originating IP.
To prevent abuse on our system, the number of API requests you can make are limited by two rolling time windows:
a 15 minute window and a 24 hour window.

IF your APIKey generates more than 200 requests in a 15 minute period, you will receive the following response:

{
   Valid: false,
   ResponseCode: "108",
   Message: "15 minute APIKey Threshold exceeded. Over 200 requests generated."
}

IF your APIKey generates more than 10,000 requests in a 24 hour period, you will receive the following response:

{
   Valid: false,
   ResponseCode: "109",
   Message: "24 hour APIKey Threshold exceeded. Over 10,000 requests generated."
}

Requests are throttled on an IP basis as well as APIKey basis to prevent brute force randomized APIKey access attempts from a singular source of attack.

IF your IP generates more than 1,000 requests in a 15 minute period, you will receive the following response:

{
   Valid: false,
   ResponseCode: "110",
   Message: "15 minute IP Threshold exceeded. Over 1000 requests generated."
}

IF your IP generates more than 20,000 requests in a 24 hour period, you will receive the following response:

{
   Valid: false,
   ResponseCode: "111",
   Message: "24 hour IP Threshold exceeded. Over 20,000 requests generated."
}
Tracking & Analytics

All API requests are logged and monitored within the Expect Referrals system. We utilize this information to handle rate limiting,
internal debugging, statistical analysis, as well as abuse detection. We reserve the right to individually ban access to our API on any account
that is exhibiting suspicious or malicious behavior. Account owners will be notified of being banned immediately, and will require a conversation with our
support team to correct. Warnings may not always be provided.

Analytics of API usage will be coming soon to your Expect Referrals reporting dashboard. Here you will be able to see charts and graphs of
your daily API utilization, as well as statistics on the number of successful vs failed actions.

Input & Output

The Expect Referrals API is currently set up to receive ONLY raw POST key/value pair data.

ApiKey=1111111111&RedemptionCode=R1234567
To request additional forms of input data to be accepted, please send details to Technical Support

The Expect Referrals API is currently set up to respond only with JSON data.

{
   Valid: true,
   ResponseCode: "205",
   Message: "This Code is valid.",
   Type: "Referral",
   ValidFor: "$10 off our $39.95 oil change package",
   DateCreated: "2013-09-02",
   CreditsRemaining: "876"
}

 

To request additional forms of output data to be delivered, please send details to Technical Support

 

 

API Methods

 

POSThttps://api.expectreferrals.com/v1/Verify Full path

 

The Verify method allows you to check if a redemption code is valid within your account at Expect Referrals. Redemption codes are the unique tracking codes that are attached to every single incentive email that is sent out to both the customer and the referral.

Input Fields
ApiKey
(Required) Your personal API Key
RedemptionCode:
(Required) The 7 digit Expect Referrals redemption code to be verified
Email
(Optional) An email address to validate the provided Redemption Code against, to ensure that the code being used matches the customer trying to use that code.
Output Fields
Valid
Boolean flag indicating if the redemption code is valid or not.
ResponseCode
Numerical response code that matches the provided message(See Full list of responses)
Message
Human legible response message indicating the result of the request.
Type
The type of redemption code that was matched (Customer or Referral).
Only available for ResponseCode: 204, 205
ValidFor
The incentive text that the redemption code was originally created for. Allows you to apply custom business logic to match your incentive if you are running a multi-tier incentive program, or change your referral program from month to month.
Only available for ResponseCode: 204, 205
DateRedeemed
The date that the redemption code had already been previously redeemed.
Only available for ResponseCode: 204
DateCreated
The date that the redemption code was originally created. Allows you to build your own custom expiration logic (ie - Valid for 30 days) into your referral program.
Only available for ResponseCode: 205
CreditsRemaining
The number of Expect Referrals credits you have left for the month.
Only available for ResponseCode: 204, 205
Example Use Case:

 

You have an ecommerce site and you are giving away 10% off to new customers who have been referred and 20% off to customers who have made 5 referrals, and you want to provide this discount at time of checkout, but only to recipients who have a valid redemption code within Expect Referrals. On submission of your checkout page, you add business logic to verify the redemption code field and apply your discount, or inform your customer that their code is invalid.

 

Sample Code: (Using our PHP API Wrapper)

<?php
$APIKey "{YOUR_API_KEY}";
$APISecret "{YOUR_API_SECRET}";
$Code $_POST["RedemptionCode"];
$API = new EXRAPI($APIKey$APISecret);
$Response $API->Verify($Code);
if( $Response->Valid && $Response->Type == "Customer") {
    // Redeem Code & Apply 20% off discount
} else if( $Response->Valid && $Response->Type == "Referral" ) {
    // Redeem Code & Apply 10% off discount
} else {
    // Invalid Code - Notify Customer
}
?>

Sample Response:
{
   Valid: false,
   ResponseCode: "204",
   Message: "This Code has already been redeemed.",
   Type: "Referral",
   ValidFor: "$10 off our $39.95 oil change package",
   DateRedeemed: "2013-09-17 10:02:05",
   CreditsRemaining: "842"
}

 

 

POSThttps://api.expectreferrals.com/v1/RedeemFull path

 

The Redeem method allows you track and redeem a redemption code into your account at Expect Referrals. Redeeming a code will subsequently trigger any redemption based campaign logic you have built into your account. (IE – After 2 redemptions, the customer gets a reward email). Once a code is redeemed into the Expect Referrals system, it becomes invalid for subsequent use. Redemption codes are the unique tracking codes that are attached to every single incentive email that is sent out to both the customer and the referral. The Redeem method does all the same business logic as /Verify above prior to redeeming the code to ensure that the code being requested to redeem is valid.

Input Fields
ApiKey
(Required) Your personal API Key
RedemptionCode:
(Required) The 7 digit Expect Referrals redemption code to be verified
Email
(Optional) An email address to validate the provided Redemption Code against, to ensure that the code being used matches the customer trying to use that code.
Output Fields
Valid
Boolean flag indicating if the redemption code is valid or not.
ResponseCode
Numerical response code that matches the provided message(See list of responses)
Message
Human legible response message indicating the result of the request.
Type
The type of redemption code that was matched (Customer or Referral).
Only available for ResponseCode: 204, 205
ValidFor
The incentive text that the redemption code was originally created for. Allows you to apply custom business logic to match your incentive if you are running a multi-tier incentive program, or change your referral program from month to month.
Only available for ResponseCode: 204, 205
DateRedeemed
The date that the redemption code had already been previously redeemed.
Only available for ResponseCode: 204
DateCreated
The date that the redemption code was originally created. Allows you to build your own custom expiration logic (ie - Valid for 30 days) into your referral program.
Only available for ResponseCode: 205
CreditsRemaining
The number of Expect Referrals credits you have left for the month.
Only available for ResponseCode: 204, 205

 

 

Example Use Case:

 

You have an ecommerce site, and you are giving away 10% off to new customers who have been referred and 20% off to customers who have made 5 referrals. You have successfully validated the customers redemption code is legitimate, and you have processed the order. You now want to redeem the code into Expect Referrals to prevent re-use in the future, trigger your redemption based campaign, and to update your analytics.

 

Sample Code: (Using our PHP API Wrapper)

<?php
$APIKey "{YOUR_API_KEY}";
$APISecret "{YOUR_API_SECRET}";
$Code $_POST["RedemptionCode"];
$API = new EXRAPI($APIKey$APISecret);
$Response $API->Redeem($Code);
if( $Response->Valid && $Response->Type == "Customer") {
    // Apply 20% off discount
} else if( $Response->Valid && $Response->Type == "Referral" ) {
    // Apply 10% off discount
} else {
    // Invalid Code - Notify Customer
}
?>

Sample Response:
{
   Valid: true,
   ResponseCode: "206",
   Message: "Referral Code R04652D has been redeemed.",
   Type: "Referral",
   ValidFor: "$10 off our $39.95 oil change package",
   DateCreated: "2013-09-12",
   CreditsRemaining: "824"
}

 

 

POSThttps://api.expectreferrals.com/v1/CreateCustomer Full path

 

The CreateCustomer method allows you to add a Customer record into your Expect Referrals account, which gives you the capability of a maintaining a synchonized membership site that allows your customers to seamlessly login to Expect Referrals without having to sign up for a separate account and maintain multiple credentials.

Input Fields
ApiKey
(Required) Your personal API Key
Email:
(Required) The customers email address. Must be a legitimate and real email address. If you are having discrepancies in trying to add a customers of yours but the email address is returning as invalid, please use the SkipEmailValidation field mentioned below.
FirstName:
(Required) The customers first name. Required due to the heavy use of personalization pre-built into Expect Referrals. If your site does not collect FirstName as a required field for membership signup, it is recommended to use a generic fallback term that applies to everyone. IE - Member, Valued Customer, etc.
LastName
(Required) The customers last name. Required due to the heavy use of personalization pre-built into Expect Referrals. If your site does not collect LastName as a required field for membership signup, it is recommended to use a generic fallback term that applies to everyone. IE - Member, Valued Customer, etc.
Password
(Required) A salted encryption of the customers password from your system. This ensures the utmost privacy is maintained for your customer, and that we don't know any of your passwords. The password format is as follows (pseudo):
md5_hash( unix_timestamp ) + md5_hash( Password + ApiKey )
The resulting encrypted string should be 64 characters.
Never send unencrypted passwords!
SkipEmailValidation
(Optional) Allows you to ignore our internal email validation process which may reject invalid customer email addresses that you have already allowed into your system.
Address
(Optional) The customers household address (line1, line2). Provide if you want to use it for personalization, and analytics.
City
(Optional) The customers city. Provide if you want to use it for personalization, and analytics.
State
(Optional) The customers state (2 character state code). Provide if you want to use it for personalization, and analytics.
Zip
(Optional) The customers zip/postal code. Provide if you want to use it for personalization, and analytics.
Birthday
(Optional) The customers birth date. Date format YYYY-MM-DD. Provide if you want to use it for personalization, and analytics.
Phone
(Optional) The customers phone number. Max 10 characters. Provide if you want to use it for personalization, and analytics.
OptIn
(Optional) The customer has opted in to receive additional marketing communications from you (not Expect Referrals - we never communicate with your customers beyond what you've configured us to do). Provide if you want to use it for personalization, and analytics.
Custom_{UniqueID}
(Optional) If you have set up Custom Form Fields for use within the Expect Referrals platform, you can provide the custom field identifier to have that data appropriately saved. Provide if you want to use it for personalization, and analytics. Note - if you have set up Custom Form fields and have made your custom fields required, the API will return with a validation failure if you do not provide the custom field information.
Output Fields
Valid
Boolean flag indicating if the redemption code is valid or not.
ResponseCode
Numerical response code that matches the provided message(See list of responses)
Message
Human legible response message indicating the result of the request.
PersonalLink
The newly created customers unique bit.ly Personal Sharing Link. Give this to your customers if you so choose to let them know how they can begin sharing Expect Referrals with their friends immediately (without them ever having to log in to our widget or referral site).
Only available for ResponseCode: 306

 

Example Use Case:

 

You have an ecommerce site where purchasing customers can sign up to maintain a historical information about their purchases, and save items to a wish-list for future purchases. You now want to allow them to make referrals from your site after they have made a purchase but you do not want them to have to sign up for another service and simply just want to log them in.

 

Sample Code: (Using our PHP API Wrapper)

<?php
$APIKey "{YOUR_API_KEY}";
$APISecret "{YOUR_API_SECRET}";
$Code $_POST["RedemptionCode"];
$API = new EXRAPI($APIKey$APISecret);

$CustomerData = array(
    //"FirstName" => "Jon",// Left Off to show validation error
    "LastName" => "Doe",
    "Email" => "jon@expectreferrals.com",
    "Password" => "12345",    // Our PHP API Wrapper handles the password encryption format for you
    "Address" => "123 Main Street",
    //"Custom_4748" => "US",    // Custom required "Country" field left off to show validation error
    "SkipEmailValidation" => // We want to allow any email address to sign up
);
$Response $API->CreateCustomer($Data);
if( $Response->Valid ) {
    // Customer successfully added
} else {
    // Customer Validation Failed
}
?>

Sample Response:
{
   Valid: false,
   ResponseCode: "308",
   Message: {
      FirstName: "First Name cannot be left blank",
      Custom_4748: "Country cannot be left blank"
   }
}

 

 

POSThttps://api.expectreferrals.com/v1/LoginCustomer Full path

 

The LoginCustomer method allows you to create an authentication token (AuthToken) to be used for Single Sign On from your membership site to your Expect Referrals customer portal and/or plugin. Customers must already exist (See CreateCustomer) in order to log them in. AuthToken‘s are valid for 24 hours from creation before you need to re-validate your customers credentials. Also note, that creating an AuthToken does NOT automatically log the customer in to your Expect Referrals account. You must load the Expect Referrals site or Plugin with the returned AuthToken to seamlessly log them in. See below for more details.

Input Fields
ApiKey
(Required) Your personal API Key
Email:
(Required) The email address of the customer you are attempting to log in
Hash
(Required) A salted encryption of the customers password from your system. This ensures the utmost privacy is maintained for your customer, and that we don't know any of your passwords. The password format is as follows (pseudo):
md5_hash( unix_timestamp ) + md5_hash( Password + ApiKey )
The resulting encrypted string should be 64 characters.
Never send unencrypted passwords!
Output Fields
Valid
Boolean flag indicating if the redemption code is valid or not.
ResponseCode
Numerical response code that matches the provided message(See list of responses)
Message
Human legible response message indicating the result of the request.
AuthToken
A 15 character alpha-numeric string that authorizes login to your customers Expect Referrals account for 24 hours.
Only available for ResponseCode: 305
ValidUntil
The timestamp that the AuthToken expires. Format: YYYY-MM-DD HH:MM:SS.
Only available for ResponseCode: 305
Example Use Case:

 

You have an ecommerce site where purchasing customers can sign up to maintain a historical information about their purchases, and save items to a wish-list for future purchases. Your existing customer has logged in and you want to single sign them in to Expect Referrals to allow them to share an offer with their friends.

 

Sample Code: (Using our PHP API Wrapper)

<?php
$APIKey "{YOUR_API_KEY}";
$APISecret "{YOUR_API_SECRET}";
$API = new EXRAPI($APIKey$APISecret);

$Email "support@expectreferrals.com";
$Password "SuperSecretPassword";
$Response $API->LoginCustomer($Email$Password);
if( $Response->Valid ) {
    // Load Your Expect Referrals site. FYI - this one is invalid
    header("Location: http://yoursitename.irecommendafriend.com/Auth/{$Response->AuthToken}");
    exit();
} else {
    // Invalid Customer Login
}
?>

Sample Response:
{
   Valid: true,
   ResponseCode: "305",
   Message: "Customer successfully Authenticated.",
   AuthToken: "520f30b3a8e28c8",
   ValidUntil: "2013-09-20 14-43-48"
}

 

 

How to use your AuthToken

 

If you are using our 1 page layout or our 4 page layout system, you simply need to load your site with the following url format:

 http://yoursitename.irecommendafriend.com/Auth/{$AuthToken}
OR http://yoursitename.sharewitheverybody.com/Auth/{$AuthToken}
OR http://yoursitename.your_custom_domain.com/Auth/{$AuthToken}

 

This will also work automatically with our mobile optimized version of the above sites. If you utilize the Expect Referrals Plugin as your primary tool, you need to modify the plugin’s EXRSettings object:

<script type="text/javascript">
EXRSettings = {
	"Key": "1234567",
	"Token": "23456789",
	"Container": "",
	"AuthToken": "<?=$AuthToken; ?>"
};
</script>
<script id="EXRScript" type="text/javascript" src="http://ui.expectreferrals.com/Plugin/plugin.js"></script>
POSThttps://api.expectreferrals.com/v1/GetCustomers Full path

The GetCustomers method allows you to search and retrieve customer data from the Expect Referrals platform to be used with whatever
customer integration you may want. Example suggested ideas are: Load customers into your own CRM tool, create a personalized reporting
dashboard, create a “Customers who refer” mailing campaign if they have opted in to follow up communication.

Input Fields
ApiKey
(Required) Your personal API Key
Fields
(Optional) Comma separated list of specific fields you want to see. See available customer fields below.
Limit

(Optional) How many records you wish to have returned. Keep in mind that the higher the number of records, the longer the request may take.

Default: 15. Min: 0. Max: 100.
Offset

(Optional) The starting database record number of the total returned result to retrieve. Example: Limit=5, Offset=3, means return 5 records starting after position 3.

Default: 0. Min: 0. No Max.
Email
(Optional,Queryable) The customer’s email address.
FirstName
(Optional,Queryable) The customer’s first name.
LastName
(Optional,Queryable) The customer’s last name.
Address
(Optional,Queryable) The customer’s address.
City
(Optional,Queryable) The customer’s city.
State
(Optional,Queryable) The customer’s 2-letter state/province code.
Zip
(Optional,Queryable) The customer’s zip/postal code.
Birthday
(Optional,Queryable) The customer’s birthday, formatted as YYYY-MM-DD.
Phone
(Optional,Queryable) The customer’s phone number.
OptIn
(Optional,Queryable) Whether or not the customer has opted in to additional communication.
Source
(Optional,Queryable) Which Expect Referrals platform the customer signed up from: API, Plugin, Mobile, Direct
HttpSource
(Optional,Queryable) Which domain the customer had signed up from. Data exists only if Source is API or Plugin.
SignupDate
(Optional,Queryable) The date the customer signed up to use Expect Referrals.
Queryable Format

By default, all query fields above utilize an EXACT match lookup, in conjunction with AND based logic.
Any of the above fields that are Queryable> however can utilize broader query tools by
appending a Pipe delimited (|) and the SearchFormat you wish to use. Example: “Email”=>”gmail.com|EndsWith” finds all users
whose email ends in ‘gmail.com’.

Here is a list of allowed SearchFormats (case insensitive):

EXACT
Exact Match search. The Default value, and unnecessary to specify. Useful however if you are building a drop down based search solution.
STARTSWITH
Wildcard search where the search results start with the provided string.
ENDSSWITH
Wildcard search where the search results end with the provided string.
CONTAINS
Wildcard search where the search results contains the provided string anywhere within the value.
BETWEEN

Returns results between two dates. Valid only for DATE queryable fields (Birthday, SignupDate, Custom Fields).Format for use is: DATE1|BETWEEN|DATE2

Output Fields
ResponseCode

Numerical response code that matches the provided message(See list of responses)

Message
Human legible response message indicating the result of the request.
Count
The number of customers returned from your query.
Customers
Array of customer data returned, optionally limited by fields specified in request, or all data. See available customer fields below.
Available Customer Fields
FirstName
The customer’s first name.
LastName
The customer’s last name.
Address
The customer’s address (line1/line2).
City
The customer’s city.
State
The customer’s state/province.
Zip
The customer’s zip/postal code.
Birthday
The customer’s birthday. (0000-00-00 for non-valid entry)
Phone
The customer’s phone number.
OptIn
Boolean flag indicating if the customer has opted in to additional communication.
FirstLogin
The date the customer first logged in. Formatted as YYYY-MM-DD HH:MM:SS
SignupDate
The date the customer signed up. Formatted as YYYY-MM-DD
LastLogin
The date the customer last logged in. Formatted as YYYY-MM-DD HH:MM:SS
TotalLogins
The number of times the customer has logged in.
BitlyURL
The customer’s unique personal sharing link.
Purchased
A flag indicating whether or not this customer has had any redemption codes redeemed within Expect Referrals.
Source
Which Expect Referrals platform the customer signed up from: API, Plugin, Mobile, Direct.
HttpSource
Which domain the customer had signed up from. Data exists only if Source is API or Plugin.
FBLogins
How many times the customer has logged in using Facebook.
FBLastLogin
The date the customer last logged in using Facebook. Formatted as YYYY-MM-DD
NumberOfReferrals
The total number of referrals this customer has made.
[CUSTOM]**
Custom Form Fields that you have created within your account are all available and displayed by thier Label.
Example Use Case:
You have built a custom administrative dashboard, and you are trying to find all customers with an email address like @expectreferrals,
whose name begins with J.
Sample Code: (Using our PHP API Wrapper)

<?php
$APIKey "{YOUR_API_KEY}";
$APISecret "{YOUR_API_SECRET}";

$Options = array( 
    "Email" => "expectreferrals.com|EndsWith",
    "FirstName" => "J|StartsWith",
    "Fields" => "FirstName,LastName,Email",
    "Limit" => 3
);

$API = new EXRAPI($APIKey$APISecret);
$Response $API->GetCustomers($Options);
if( $Response->Count ) {
    echo "<pre>";
    print_r($Response);
    echo "</pre>";
} else {
    echo "No Customers Found";
}
?>

Sample Response:
{
   ResponseCode: "309",
   Message: "Successfully retrieved requested customers.",
   Count: 3,
   Customers: [
      {
         FirstName: "Jon",
         LastName: "Smith",
         Email: "test1@expectreferrals.com"
      },
      {
         FirstName: "Jane",
         LastName: "Smith",
         Email: "test2@expectreferrals.com"
      },
      {
         FirstName: "Jamie",
         LastName: "Layne",
         Email: "test3@expectreferrals.com"
      }
   ]
}

 

 

 

 

POSThttps://api.expectreferrals.com/v1/GetReferrals Full path

 

The GetReferrals method allows you to search and retrieve referral data from the Expect Referrals platform to be used with whatever custom integration you may want. Example suggested ideas are: Load referrals into your own CRM tool, create a personalized reporting dashboard, etc.

Input Fields
ApiKey
(Required) Your personal API Key
Fields
(Optional) Comma separated list of specific fields you want to see. See available referral fields below.
Limit
(Optional) How many records you wish to have returned. Keep in mind that the higher the number of records, the longer the request may take.
Default: 15. Min: 0. Max: 100.
Offset
(Optional) The starting database record number of the total returned result to retrieve. Example: Limit=5, Offset=3, means return 5 records starting after position 3.
Default: 0. Min: 0. No Max.
Email
(Optional,Queryable) The referral's email address.
FirstName
(Optional,Queryable) The referral's first name.
LastName
(Optional,Queryable) The referral's last name.
Address
(Optional,Queryable) The referral's address.
City
(Optional,Queryable) The referral's city.
State
(Optional,Queryable) The referral's 2-letter state/province code.
Zip
(Optional,Queryable) The referral's zip/postal code.
Phone
(Optional,Queryable) The referral's phone number.
DateReferred
(Optional,Queryable) The date this referral was referred on
Source
(Optional,Queryable) Which Expect Referrals platform the referral was referred on: Plugin, Mobile, Direct
HttpSource
(Optional,Queryable) Which domain the referral was made on. Data exists only if Source is Plugin.
Queryable Format
By default, all query fields above utilize an EXACT match lookup, in conjunction with AND based logic. Any of the above fields that are Queryable> however can utilize broader query tools by appending a Pipe delimited (|) and the SearchFormat you wish to use. Example: "Email"=>"gmail.com|EndsWith" finds all users whose email ends in 'gmail.com'. Here is a list of allowed SearchFormats (case insensitive):
EXACT
Exact Match search. The Default value, and unnecessary to specify. Useful however if you are building a drop down based search solution.
STARTSWITH
Wildcard search where the search results start with the provided string.
ENDSSWITH
Wildcard search where the search results end with the provided string.
CONTAINS
Wildcard search where the search results contains the provided string anywhere within the value.
BETWEEN
Returns results between two dates. Valid only for DATE queryable fields (Birthday, SignupDate, Custom Fields).Format for use is: DATE1|BETWEEN|DATE2
Output Fields
ResponseCode
Numerical response code that matches the provided message(See list of responses)
Message
Human legible response message indicating the result of the request.
Count
The number of customers returned from your query.
Referrals
Array of referrals data returned, optionally limited by fields specified in request, or all data. See available referral fields below.
Available Referral Fields
FirstName
The referral's first name.
LastName
The referral's last name.
Address
The referral's address (line1/line2).
City
The referral's city.
State
The referral's state/province.
Zip
The referral's zip/postal code.
Phone
The referral's phone number.
DateReferred
The date this referral was referred on. Formatted as YYYY-MM-DD HH:MM:SS
Message
The personal message that was included in the customer's email to this referral.
Source
Which Expect Referrals platform the referral was made on: Plugin, Mobile, Direct.
HttpSource
Which domain the referral was made on. Data exists only if Source is Plugin.
Code
The redemption code that was created for this referral
CodeValidFor
The incentive that this referral received.
CodeRedeemed
Boolean flag indicating whether or not this referral has redeemd thier code yet.
[CUSTOM]**
Custom Form Fields that you have created within your account are all available and displayed by thier Label.
Example Use Case:

 

You have created a 1 day only special referral campaign on September 19th, and you want to retrieve which referrals were created and what their associated redemptions codes are so you can add their data to a specific CRM based automation campaign.

 

Sample Code: (Using our PHP API Wrapper)

<?php
$APIKey "{YOUR_API_KEY}";
$APISecret "{YOUR_API_SECRET}";

$Options = array( 
    "DateReferred" => "2013-09-19|Between|2013-09-19",
    "Fields" => "Email,Code,DateReferred",
);

$API = new EXRAPI($APIKey$APISecret);
$Response $API->GetReferrals($Options);
if( $Response->Count ) {
    echo "<pre>";
    print_r($Response);
    echo "</pre>";
    // Push result into CRM
} else {
    echo "No Referrals Found";
}
?>

Sample Response:
{
   ResponseCode: "401",
   Message: "Successfully retrieved requested referrals.",
   Count: 1,
   Referrals: [
      {
         Email: "test1@expectreferrals.com",
         DateReferred: "2013-09-19 14:19:11",
         Code: "R04652D"
      }
   ]
}

 

 

Response Codes

 

Every successful API request returns a numerical ResponseCode that has an associated Message. Here is the complete list of ResponseCodes generated from the API so you can track / catch / debug your application.

{
   100: {
      Message: "Invalid Action: [Method] [Action]",
      Reason: "The requested method/action pair does not exist. All API actions must be POSTed, and only the documented methods are available for external use."
   },
   101: {
      Message: "Missing required API key",
      Reason: "No API key was provided. Field 'ApiKey' must be provided with all requests."
   },
   102: {
      Message: "Invalid API key provided",
      Reason: "The API Key that was provided could not be found. Check the API key for typos."
   },
   103: {
      Message: "API is only valid for Complete Plan subscribers. You must upgrade your account to use this feature.",
      Reason: "The Expect Referrals plan that you have subscribed to does not allow access to the API feature."
   },
   104: {
      Message: "API has not been configured to be used with this account.",
      Reason: "You have not initially set up API access to your account. Please log in and generate an APISecret key to continue"
   },
   105: {
      Message: "Invalid Requestor",
      Reason: "The domain that you are trying to utilize the API from has not been registered as authorized."
   },
   107: {
      Message: "Invalid Parameters",
      Reason: "The HMAC security check did not match the data that you provided. Please check your hashing technique and/or verify your APISecret is correct."
   },
   108: {
      Message: "15 minute APIKey Threshold exceeded. Over 200 requests generated",
      Reason: "Too many API requests for your APIkey in the past 15 minutes. If you feel you need higher thresholds, please contact support."
   },
   109: {
      Message: "24 hour APIKey Threshold exceeded. Over 10,000 requests generated",
      Reason: "Too many API requests for your APIkey in the past 24 hours If you feel you need higher thresholds, please contact support."
   },
   110: {
      Message: "15 minute IP Threshold exceeded. Over 1000 requests generated",
      Reason: "Too many API requests from your IP in the past 15 minutes. If you have a dedicated IP and you feel you need higher thresholds, please contact support"
   },
   111: {
      Message: "24 hour IP Threshold exceeded. Over 20,000 requests generated",
      Reason: "Too many API requests from your IP in the past 24 hours. If you have a dedicated IP and you feel you need higher thresholds, please contact support"
   },
   112: {
      Message: "API access has been suspended for your account. Please contact support.",
      Reason: "Your account has been manually suspended due to suspicious activity. You must talk with support to determine next course of action"
   },
   201: {
      Message: "Invalid Code.",
      Reason: "The redemption code that you are looking up is incorrect. Check the key for typos."
   },
   202: {
      Message: "Invalid email address provided.",
      Reason: "The email address that was provided is mal-formed. "
   },
   203: {
      Message: "This Code is not valid for provided email address.",
      Reason: "The redemption code that was provided does not match the email address of the recipient of that code."
   },
   204: {
      Message: "This Code has already been redeemed.",
      Reason: "The redemption code that you are looking up has been redeemed in the system already and cannot be redemed again."
   },
   205: {
      Message: "This Code is valid.",
      Reason: "The redemption code is valid and available to be redeemed."
   },
   206: {
      Message: "[CodeType] Code [Code] has been redeemed.",
      Reason: "The redemption code has been successfully marked as redeemed into Expect Referrals."
   },
   207: {
      Message: "You have run out of credits for the month. Code cannot be redeemed at this time.",
      Reason: "Redemption codes can only be redeemed when you have credits. Upgrade your account or wait until your billing cycle completes to have your credits refreshed."
   },
   303: {
      Message: "Invalid Customer Credentials",
      Reason: "The customer that you are looking for does not exist."
   },
   304: {
      Message: "Invalid Customer Credentials",
      Reason: "Invalid password provided for requested customer."
   },
   305: {
      Message: "Customer successfully Authenticated.",
      Reason: "Valid customer credentials have been provided. You may use the returned AuthToken to login the customer for the next 24 hours."
   },
   306: {
      Message: "Customer has been successfully Created.",
      Reason: "Customer has been successfully added to your Expect Referrals account."
   },
   307: {
      Message: "This email address is already registered.",
      Reason: "The customer email that you are trying to create already exists in the system. Attempt to log them in instead."
   },
   308: {
      Message: "Missing required fields to complete customer signup.",
      Reason: "Some of the required fields for customer signup were missing or are invalid. This includes custom created form fields as well."
   },
   309: {
      Message: "Successfully retrieved requested customers.",
      Reason: "Request to GetCustomers successully returned."
   },
   401: {
      Message: "Successfully retrieved requested referrals.",
      Reason: "Request to GetReferrals successfully returned."
   }
}
Feature Requests / Bug Complaints

We appreciate your time and involvement in using the Expect Referrals API to make integrating your solution as easy as possible. If you have specific functionality that you wish the API could accomodate for you, or if you need to report any bugs, please email that information to api@expectreferrals.com, and we will review every one of them on a case by case basis.