How to Generate Personalized URLs (PURLs) through Our API

William Harper Updated by William Harper

While we've already discussed how to generate personal referral links using our platform's built-in feature, in this help article, we'll go over how you can generate PURLs using our API! In order to use our API to generate PURLs, you'll need a few things:

  • The email(s) of the customers you'd like to generate PURLs for
  • The campaign ID of the campaign you'd like the PURL to be associated with for analytics tracking
  • Your Friendbuy account's Private API Keys (if you don't have this, please reach out to your Customer Success Manager or support@friendbuy.com)
Tip: familiarize yourself with our REST API documentation.

Step 1

If you have all of the above items, you're ready to get started! Using a program such as Postman (or any other similiar program), you'll want to create a new POST request to https://mapi.fbot.me/v1/personal-referral-link to create or retrieve the PURL for a given customer.

Note: to request a batch of PURLs, use our other endpoint: /v1/personal-referral-link-batch

Step 2

Next, you'll want to navigate to your Authorization settings, and set the Authorization Type to Bearer Token. Enter your Bearer Token in the Token field.

Note: You can retrieve your Bearer Token by doing a POST call to our https://mapi.fbot.me/v1/authorization endpoint using the API credentials your Customer Success Manager has provided to you.

Step 3

Now, under the Request Body, you'll want to use the above mentioned email address and campaign ID in order to create the Request Body to send to our endpoint. An example of this would be as follows:

{

"email": "test@example.com",

"campaignId": "abcdefg-a123-b456-c789-101112abcdef",

}

Note: The campaign ID can be retrieved from the page URL when navigating to your campaign settings in the Friendbuy platform. For example, the highlighted portion in this URL would be your campaign ID: https://retailer.friendbuy.io/referral-campaign/abcdefg-a123-b456-c789-101112abcdef/general

For a full list of available parameters used in generating PURLs through our API, be sure to check out our developer documentation by clicking here.

Step 4

Once you have all of the above steps completed, you're now ready to generate the PURL and send the request! Click Send, and if all is correct, you should receive a 200 response containing the link unique for that customer, example below:

You've now successfully generated a PURL using our API! For generating multiple PURLs via CSV file upload, we'd recommend using our built-in platform feature for this, which you can read more about by clicking here.

Additional Notes

  • PURLs will include a randomly generated referral code unless you have set up Referral Code Personalization in your Referral Campaign settings and provided the optional fields (firstName or lastName) as a seed in the CSV file. Example: https://fbuy.io/alias/prefixseed
  • If a PURL does not exist for the Advocate associated with the requested campaign, one will be created. If a PURL already exists, the link will remain the same.
  • If a PURL already exists for an Advocate when creating a new widget for a new PURL campaign, the Analytics for their PURL will not be tracked in the new widget, and will only be tracked in the original widget.
  • You can create an Additional Widget in your campaign to assign for tracking PURL analytics independent of existing widgets. Reach out to your Customer Support Manager to learn more about best practices!
Tip: Consider using PURLs to send personalized referral marketing campaigns by including the customer's personal referral link in an eblast. Take a look at the below PURL campaign example from one of our customers, Metromile, for an idea of how you can create your own PURL campaign!

How did we do?

Setting Up Max Clicks for Referral Links

How to Generate Personalized URLs (PURLs) for Advocates

Contact