JavaScript Web API

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 person's email address.
  • first_name — The person's first name.
  • last_name — The person's last name.
  • full_name — The user's full name, which we will automatically split into first and last name.
  • address_line1 — Address line 1 (e.g., street, PO Box, or company name).
  • address_line2 — Address line 2 (e.g., apartment, suite, unit, or building).
  • city — City, district, suburb, town, or village.
  • state — State, county, province, or region.
  • postal_code — ZIP or postal code.
  • country — Two-letter country code (ISO 3166-1 alpha-2).
  • telephone — The person'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. 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. 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. 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. 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. 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');
    
  
    
      // 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?ref-check=5de34a3e-68cb-4956-be9d-e89db02e6989",
    "list_position": 2,
    "list_ahead": 1,
    "list_behind": 10485,
    "list_length": 10487,
    "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
    }
  }

Identity Verification — When adding a new user, the user will be automatically authenticated for their current browser session and you do not need to call the authenticateUser function or provide a signature to subsequent API requests.

Identity Verification — A HTTP 403: Forbidden error will be returned if the following conditions are met: (1) the project has identity verification enabled, (2) the given email address already exists in the project, and (3) there is no authentication cookie present on the user's browser (e.g. you have not called the authenticateUser function).

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.

Authenticate a User

If your project has identity verification enabled, you can authenticate the user into their current browser session so that you do not have to provide a signature to each subsequent API request. This authentication will last until the user closes their browser.

Note — When adding a new user, the user will be automatically authenticated for their current browser session and you do not need to call this function nor provide a signature to subsequent API requests. 

    
      prefinery('authenticateUser', data, callback);

Parameters

data string or object
required An Object, where keys can be:
  • email or referral_code or id— Either the user's email address, referral code or id.
  • signature— HMAC signature of the email, referral_code, or id value and your project's identity verification secret. Learn more about identity verification.
callback function
optional A callback function that will be invoked after the user is authenticated.

Example Requests

    
      prefinery('authenticateUser', {
        email: 'bruce@wayneenterprises.com',
        signature: 'd181b885962e4c8aad0fb4d241e018b67f59e579c475bb4a454c743688237503'
      }, function() {
        // Do something, such as make one of the following API calls ...
      });

Note — A HTTP 401: Unauthorized error will be returned if the signature is incorrect.

Get a User

Get details about a user in your campaign. 

    
      prefinery('getUser', data, callback);

Parameters

data string or object
required An Object, where keys can be:
  • email or referral_code or id— Either the user's email address, referral code or id.
  • signature— HMAC signature of the email, referral_code, or id value and your project's identity verification secret. Required if there is no authentication cookie present on the user's browser and you have identity verification enabled.
callback function
required A callback function that will be invoked with the user data.

Example Requests

    
      // Get authenticated user
      prefinery('getUser', function(user) {
        console.log('User: ' + JSON.stringify(user));
      });
    
  
    
      // Authenticate a user and get their details
      prefinery('authenticateUser', {
        email: 'bruce@wayneenterprises.com',
        signature: 'd181b885962e4c8aad0fb4d241e018b67f59e579c475bb4a454c743688237503',
      }, function() {
        prefinery('getUser', function(user) {
          console.log('User: ' + JSON.stringify(user));
        });
      });
    
  
    
      // Get by a user by email address
      prefinery('getUser', {
        email: 'bruce@wayneenterprises.com',
        signature: 'd181b885962e4c8aad0fb4d241e018b67f59e579c475bb4a454c743688237503',
      }, 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?ref-check=5de34a3e-68cb-4956-be9d-e89db02e6989",
    "list_position": 2,
    "list_ahead": 1,
    "list_behind": 10485,
    "list_length": 10487,
    "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
    }
  }
Identity Verification — A HTTP 403: Forbidden error will be returned if the following conditions are met: (1) the project has identity verification enabled, and (2) either there is no authentication cookie present on the user's browser or the signature is incorrect.

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 person’s email address.
  • signature— HMAC signature of the email address and your project's identity verification secret. Required if there is no authentication cookie present on the user's browser and you have identity verification enabled.
  • 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

    
      // For authenticated user; Without callback
      prefinery('triggerRewards', {
        event: 'purchase',
      });
    
  
    
      // For specific user; With callback
      prefinery('triggerRewards', {
        email: 'bruce@wayneenterprises.com',
        signature: 'd181b885962e4c8aad0fb4d241e018b67f59e579c475bb4a454c743688237503',
        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",
      },
    },
  }
]

Identity Verification — A HTTP 403: Forbidden error will be returned if the following conditions are met: (1) the project has identity verification enabled, and (2) either there is no authentication cookie present on the user's browser or the signature is incorrect.

Get Referral Code

Returns the authenticated user's referral code, or null if there is no authentication cookie present. 

    
      prefinery('getReferralCode', callback);

Parameters

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

Example Requests

    
      prefinery('getReferralCode', function(code) {
        console.log('Referral code is ' + code);
      });

Example Response

    
  "batman823"

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.
  • signature— HMAC signature of the email, referral_code, or id value and your project's identity verification secret. Required if there is no authentication cookie present on the user's browser and you have identity verification enabled.
callback function
optional A callback function that will be invoked when the referral page popup is shown.

Example Requests

    
      // For authenticated user
      prefinery('popupReferralPage');
    
  
    
      // For specific user; Without callback
      prefinery('popupReferralPage', {
        email: 'bruce@wayneenterprises.com',
        signature: 'd181b885962e4c8aad0fb4d241e018b67f59e579c475bb4a454c743688237503',
      });
    
  
    
      // For specific user; With callback
      prefinery('popupReferralPage', {
        email: 'bruce@wayneenterprises.com',
        signature: 'd181b885962e4c8aad0fb4d241e018b67f59e579c475bb4a454c743688237503',
      }, function () {
        // Do something ...
      });

Identity Verification — A HTTP 403: Forbidden error will be returned if the following conditions are met: (1) the project has identity verification enabled, and (2) either there is no authentication cookie present on the user's browser or the signature is incorrect.

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.
  • signature— HMAC signature of the email, referral_code, or id value and your project's identity verification secret. Required if there is no authentication cookie present on the user's browser and you have identity verification enabled.
  • 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

    
      // For authenticated user
      prefinery('embedReferralPage', {
        dom_id: 'embed-here',
      });
    
  
    
      // For specific user; Without callback
      prefinery('embedReferralPage', {
        email: 'bruce@wayneenterprises.com',
        signature: 'd181b885962e4c8aad0fb4d241e018b67f59e579c475bb4a454c743688237503',
        dom_id: 'embed-here',
      });
    
  
    
      // With callback
      prefinery('embedReferralPage', {
        email: 'bruce@wayneenterprises.com',
        signature: 'd181b885962e4c8aad0fb4d241e018b67f59e579c475bb4a454c743688237503',
        dom_id: 'embed-here',
      }, function() {
        // Do something ...
      });

Identity Verification — A HTTP 403: Forbidden error will be returned if the following conditions are met: (1) the project has identity verification enabled, and (2) either there is no authentication cookie present on the user's browser or the signature is incorrect.

Embed Leaderboard

Embed the Top 10 leaderboard into the page. 

    
      prefinery('embedLeaderboard', data, callback);

Parameters

data object
An Object, where keys can be:
  • required dom_id — The DOM ID into which the leaderboard should be embedded.
  • email or referral_code or id— Either the user's email address, referral code or id if you want to highlight their position on the leaderboard.
  • signature— HMAC signature of the email, referral_code, or id value and your project's identity verification secret. Required only if you pass the user's email address, referral code or id and if there is no authentication cookie present on the user's browser and you have identity verification enabled.
callback function
optional A callback function that will be invoked with the user data.

Example HTML

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

Example Requests

    
      // Show Top 10 leaderboard
      prefinery('embedLeaderboard', {
        dom_id: 'embed-here',
      });
    
  
    
      // Highlight user on leaderboard, or add an 11th row showing their position
      prefinery('embedLeaderboard', {
        email: 'bruce@wayneenterprises.com',
        signature: 'd181b885962e4c8aad0fb4d241e018b67f59e579c475bb4a454c743688237503',
        dom_id: 'embed-here',
      });
    
  
    
      // With callback
      prefinery('embedLeaderboard', {
        email: 'bruce@wayneenterprises.com',
        signature: 'd181b885962e4c8aad0fb4d241e018b67f59e579c475bb4a454c743688237503',
        dom_id: 'embed-here',
      }, function() {
        // Do something ...
      });

Identity Verification — A HTTP 403: Forbidden error will be returned if the following conditions are met: (1) the project has identity verification enabled, (2) a user's email address, referral code or id is passed, and (3) either there is no authentication cookie present on the user's browser or the signature is incorrect.

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

    
      // Without callback
      prefinery('recordFormImpression');
    
  
    
      // With callback
      prefinery('recordFormImpression', function() {
        // Do something ...
      });

Initialize Forms

Reinitialize the signup form(s).

This method is useful if you are using a Single Page Application (SPA) framework and find that you need to explicitly re-initialize Prefinery's forms after your page HTML has been written. 

    
      prefinery('initForms');

Logout User

Logs the user out of their browser session by removing their session authentication cookie. 

    
      prefinery('logoutUser', callback);

Parameters

callback function
optional A callback function that will be invoked when the user has been logged out and their authentication cookie is removed.

Example Requests

    
      // Without callback
      prefinery('logoutUser');
    
  
    
      // With callback
      prefinery('logoutUser', function() {
        // Do something ...
      });