JavaScript Web API Documentation

Last updated on April 23, 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 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",
      },
    },
  }
]

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 ...
      });

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 ...
      });

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 ...
      });

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 ...
      });

Developer Resources

JavaScript Web API beta

This Web API is in public beta

Add a User

Parameters

Example Requests

Example Response

Authenticate a User

Parameters

Example Requests

Get a User

Parameters

Example Requests

Example Response

Trigger Rewards

Parameters

Example Requests

Example Response

Get Referral Code

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

Logout User

Parameters

Example Requests