JavaScript Web API Documentation

Last updated on February 15, 2021

This Web API is in public beta

What does it mean to be in "public beta"?

The API has been released publically to early adopters.
The API may have bugs and not work as expected.
The API may change, including function names, parameters, and responses.
We recommend that you email us at support@prefinery.com and let us know that you are using this API so that we can notify you of changes which may affect your integration.
We want to hear your feedback, bug reports, and feature requests!

Add a User

Adds a new user to the campaign, or update an existing user if one exists. If this user was referred by a friend, the friend will automatically be credited with the referral.

    
      prefinery('addUser', data, callback);

Parameters

data string or object: required A String containing the user email address or an Object containing the user's email address and additional data.
If providing an Object, keys can be:

email — The user's email address.

first_name — The user's first name.

last_name — The user's last name.

full_name — The user's full name, which we will automatically split into first and last name.

address_line1 — The user's street address.

address_line2 — More street address information.

city — The user's city.

state — The user's state, region or province.

postal_code — The user's postal or zip code.

country — The user's country.

telephone — The user's phone number.

referred_by — Populate this field with either the referrer code or email address of the referring user and we will credit that person with having referred this user. We will automatically determine this value and we recommend that you do not set this value unless you need to explicitly set it.

http_referrer — The address of the webpage the user was on prior to landing on your site. We will automatically determine this value and we recommend that you do not set this value unless you need to explicitly set it.

utm_source — UTM Source string (max 25 characters). We will automatically determine this value and we recommend that you do not set this value unless you need to explicitly set it.

utm_medium — UTM Medium string (max 25 characters). We will automatically determine this value and we recommend that you do not set this value unless you need to explicitly set it.

utm_campaign — UTM Campaign string (max 25 characters). We will automatically determine this value and we recommend that you do not set this value unless you need to explicitly set it.

utm_term — UTM Term string (max 50 characters). We will automatically determine this value and we recommend that you do not set this value unless you need to explicitly set it.

utm_content — UTM Content string (max 25 characters). We will automatically determine this value and we recommend that you do not set this value unless you need to explicitly set it.

custom_var1 — A custom string which will be made available on the user's profile and in email messages, webhooks and API requests.

custom_var2 — A custom string which will be made available on the user's profile and in email messages, webhooks and API requests.

custom_var3 — A custom string which will be made available on the user's profile and in email messages, webhooks and API requests.
callback function: optional A callback function that will be invoked with the user data.

Example Requests

    
      // Simple
      prefinery('addUser', 'bruce@wayneenterprises.com', function(user) {
        console.log('User: ' + JSON.stringify(user));
      });

    
      // Advanced
      prefinery('addUser', {
        email: 'bruce@wayneenterprises.com',
        first_name: 'Bruce',
        last_name: 'Wayne',
        referred_by: 'robin@boywonder.com',
        utm_source: 'Facebook',
        utm_medium: 'cpc',
      }, function (user) {
        console.log('User: ' + JSON.stringify(user));
      });

Example Response

    
  {
    "id": "5de34a3e-68cb-4956-be9d-e89db02e6989",
    "email": "bruce@wayneenterprises.com",
    "shares": 56,
    "referrals": 12,
    "referral_code": "batman823",
    "referral_link": "https://gotham.com/batman823",
    "referral_status_link": "https://gotham.com/batman823?check=5de34a3e-68cb-4956-be9d-e89db02e6989",
    "created_at": "2020-10-22T14:25:10Z",
    "updated_at": "2020-10-22T14:25:10Z",
    "profile": {
      "first_name": "Bruce",
      "last_name": "Wayne",
      "browser_name": "Chrome",
      "browser_version": "86.0.4240.183",
      "os_name": "Mac OS X",
      "os_version": "10.15.6",
      "ip": "64.71.141.151",
      "http_referrer": "https://www.facebook.com",
      "utm_source": "Facebook",
      "utm_medium": "cpc",
      "utm_campaign": null,
      "utm_term": null,
      "utm_content": null
    }
  }

Pro Tip — Use the recordFormImpression function when using your own form in order to ensure the form impression and signup conversion rate data is accurate on your Analytics Dashboard.

Get a User

Get details about a user in your campaign.

    
      prefinery('getUser', data, callback);

Parameters

data string or object: required A String containing the user email address or an Object in order to find the user by referral code.
If providing an Object, keys can be:

email or referral_code or id— Either the user's email address, referral code or id.
callback function: required A callback function that will be invoked with the user data.

Example Requests

    
      // Get by email address
      prefinery('getUser', 'bruce@wayneenterprises.com', function(user) {
        console.log('User: ' + JSON.stringify(user));
      });

      // Get by referral code
      prefinery('getUser', {
        referral_code: 'batman823'
      }, function(user) {
        console.log('User: ' + JSON.stringify(user));
      });

Example Response

    
  {
    "id": "5de34a3e-68cb-4956-be9d-e89db02e6989",
    "email": "bruce@wayneenterprises.com",
    "shares": 56,
    "referrals": 12,
    "referral_code": "batman823",
    "referral_link": "https://gotham.com/batman823",
    "referral_status_link": "https://gotham.com/batman823?check=5de34a3e-68cb-4956-be9d-e89db02e6989",
    "created_at": "2020-10-22T14:25:10Z",
    "updated_at": "2020-10-22T14:25:10Z",
    "profile": {
      "first_name": "Bruce",
      "last_name": "Wayne",
      "browser_name": "Chrome",
      "browser_version": "86.0.4240.183",
      "os_name": "Mac OS X",
      "os_version": "10.15.6",
      "ip": "64.71.141.151",
      "http_referrer": "https://www.facebook.com",
      "utm_source": "Facebook",
      "utm_medium": "cpc",
      "utm_campaign": null,
      "utm_term": null,
      "utm_content": null
    }
  }

Trigger Rewards

Evaluate a custom event and create all necessary rewards.

When you set up a reward in your Prefinery dashboard, you can specify that the reward be earned when a person completes a goal-based action (see What Triggers a Reward? for more information). This API method allows you to let us know that a person has completed an action. If having performed that action causes any rewards to be earned by any users, then those rewards will be created and the list will be returned here.

    
      prefinery('triggerRewards', data, callback);

Parameters

data object: required An Object containing the email address of the user who performed a custom event and the name of the custom event performed.

email — The user's email address.

event — The name of the custom event the user performed.
callback function: optional A callback function that will be invoked with an array of any triggered rewards.

Example Requests

    
      prefinery('triggerRewards', {
        email: 'bruce@wayneenterprises.com',
        event: 'purchase',
      }, function(rewards) {
        rewards.forEach(function (reward) {
          console.log('Reward: ' + JSON.stringify(reward));
        });
      });

Example Response

    
[
  {
    "descriptor": "discount10",
    "name": "$10 discount",
    "user_id": "5de34a3e-68cb-4956-be9d-e89db02e6989",
    "user_role": "referrer",
    "status": "earned",
    "type": "SingleSided",
    "earned_at": "2021-01-16T21:25:01Z",
    "delivered_at": null,
    "revoked_at": null,
    "user": {
      "id": "5de34a3e-68cb-4956-be9d-e89db02e6989",
      "email": "bruce@wayneenterprises.com",
      "referral_code": "batman823",
      "profile": {
        "first_name": "Bruce",
        "last_name": "Wayne",
      },
    },
  }
]

Get Referrer Code

Returns the referral code of the user that referred this visitor, or null if the visitor was not referred.

    
      prefinery('getReferrerCode', callback);

Parameters

callback function: required A callback function that will be invoked with the referring user's referral code.

Example Requests

    
      prefinery('getReferrerCode', function(code) {
        console.log('Referred by ' + code);
      });

Example Response

    
  "robin182"

Popup Referral Page

Display a user's personalized referral page in a popup.

    
      prefinery('popupReferralPage', data, callback);

Parameters

data object: required An Object, where keys can be:

email or referral_code or id— Either the user's email address, referral code or id.
callback function: optional A callback function that will be invoked when the referral page popup is shown.

Example Requests

    
      // Without callback
      prefinery('popupReferralPage', {
        email: 'bruce@wayneenterprises.com'
      });

    
      // With callback
      prefinery('popupReferralPage', {
        email: 'bruce@wayneenterprises.com'
      }, function () {
        // Do something
      });

Close Referral Page

Close the referral page popup.

    
      prefinery('closeReferralPage', callback);

Parameters

callback function: optional A callback function that will be invoked after the referral page popup is closed.

Example Requests

    
      // Without callback
      prefinery('closeReferralPage');

    
      // With callback
      prefinery('closeReferralPage', function() {
        // Do something
      });

Embed Referral Page

Embed the referral page into the page.

    
      prefinery('embedReferralPage', data, callback);

Parameters

data object: required An Object, where keys can be:

email or referral_code or id— Either the user's email address, referral code or id.

dom_id — The DOM ID into which the referral page should be embedded.
callback function: optional A callback function that will be invoked with the user data.

Example HTML

    
      <div id="embed-here"></div>

Example Requests

    
      // Without callback
      prefinery('embedReferralPage', {
        email: 'bruce@wayneenterprises.com',
        dom_id: 'embed-here',
      });

    
      // With callback
      prefinery('embedReferralPage', {
        email: 'bruce@wayneenterprises.com',
        dom_id: 'embed-here',
      }, function() {
        // Do something
      });

Record Form Impression

Tell Prefinery that your signup form has been viewed. The user will be cookied to ensure that impressions are unique.

Pro Tip — Use this alongside the addUser function when using your own form in order to ensure the form impression and signup conversion rate data is accurate on your Analytics Dashboard.

    
      prefinery('recordFormImpression', callback);

Parameters

callback function: optional A callback function that will be invoked after the impression has been recorded.

Example Requests

    
      prefinery('recordFormImpression', function() {
        // Do something
      });

Developer Resources

JavaScript Web API beta

This Web API is in public beta

Add a User

Parameters

Example Requests

Example Response

Get a User

Parameters

Example Requests

Example Response

Trigger Rewards

Parameters

Example Requests

Example Response

Get Referrer Code

Parameters

Example Requests

Example Response

Popup Referral Page

Parameters

Example Requests

Close Referral Page

Parameters

Example Requests

Embed Referral Page

Parameters

Example HTML

Example Requests

Record Form Impression

Parameters

Example Requests