Developer Resources
JavaScript Web API beta
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
orreferral_code
orid
— 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
orreferral_code
orid
— 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
orreferral_code
orid
— 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
});