Refer-a-Friend Programs using our Custom REST API – Guide & Documentation

Matthew Palmer Peach’s Technical Support

This guide teaches you how to set up a refer-a-friend program and integrate it via REST. Custom API refer-a-friend programs are suited to businesses that use services not covered by our other integrations. Please contact Peach’s if you’d like to see other integrations.

• How to create a refer-a-friend program with a custom REST API
• Authenticating your API requests
• Creating a referrer
• Adding a referral
• Rewarding your customers

Creating a refer-a-friend program using a custom API integration

To get started, select ‘New Gambit‘ from the Peach’s console. In the gambit gallery, choose the ‘Refer-a-Friend + Custom API’ gambit type.

Add a name and domain name for your gambit, plus an icon.

Add the URL on your website where people should be sent after they click a referral link. Complete the other fields to fit your needs.

Getting your API key

In the next step, you’ll be given an API key. It’s important to keep this key safe and secure.

You can view this API key again from your gambit settings page.

Authenticating your API requests

Your API requests must be authenticated using Basic Auth. Pass your API key as the username and leave the password value empty.

If your authentication is invalid, you’ll receive the following error.

{
    "message": "An authentication error occurred" 
}

Creating a referrer

POST /api/v1/gambits/:id/referrers

In Peach’s API referrers represent people who sign up to refer their friends via your refer-a-friend program. They can earn rewards by referring enough friends.

Create a new referrer for customers who join your refer-a-friend program. We will generate a unique referral link for that customer which they share with friends.

When their friends visit that link, Peach’s will track the visits to your business via that link.

Example Request

curl -X POST https://peachs.co/api/v1/gambits/56/referrers \
    -u g95eba75368981134c3cd2f5963eb: \
    -d name="Test User" \
    -d email="[email protected]" \
    -d fingerprint="test_user"

Fields

name
The customer’s first and last name.

email
The customer’s email address.

fingerprint
This parameter is important – this field is used to detect spam and duplicate users. This value uniquely identifies users. For example, it might be their IP address, their user ID, or their browser fingerprint. Peach’s counts unique fingerprints when generating treats to avoid rewarding spammers.

Example Response

{
    "id":8645,
    "referralCode": "stark-dirt-8363",
    "referralLink": "https://peachs.co/r/stark-dirt-8363"
}

Adding a referral

POST /api/v1/gambits/:id/referral

In Peach’s API referrals are people who get referred to your business by their friend.

When a customer sends their friend to your application, and that friend completes the required action for the original customer to be rewarded (for example, their friend signs up for a trial), send a POST request to this endpoint to add that friend as a referral of the original customer.

Example Request

curl -X POST http://localhost:3000/api/v1/gambits/56/referral \
    -u g95eba75368981134c3cd2f5963eb: \
    -d referralCode="stark-dirt-8363" \
    -d fingerprint="other_test_user"

Fields

referralCode
The referral code belonging to the person who sent their friend to your business. This is the referral code of the original customer.

fingerprint
This parameter provides the fingerprint for the friend being referred. Peach’s counts unique fingerprints when generating treats to avoid rewarding spammers. See the discussion about fingerprints under ‘Creating a Referrer’ for more information.

Example Response

{
    "message": "Referral step saved"
}

Rewarding your customers

Once the referrers you have created have enough referrals added, we’ll send an email to the original customer who can claim their reward.

We’ll track when they click the link to claim their reward, and redirect them to your website.

In your gambit’s ‘Integration’ settings section, set the ‘Treat URL’ where we should send customers after they have earned their reward.

In your application, this might generate a coupon code they can use or cause some credit to be applied to their account.

In this example, Peach’s would send customers who referred enough friends to the following URL and attaching URL parameters to allow you to identify the customer who needs to be rewarded.

https://app.company.co/apply-credit
    [email protected]
    &referralCode=stark-dirt-8363
    &fingerprint=test_user

Fields

The following fields are passed as URL parameters.

email
The email address belonging to the referrer who needs to be rewarded.

referralCode
The referral code belonging to the person who sent their friend to your business – this is the customer who needs to be rewarded.

fingerprint
A spam detection value that uniquely identifies this customer. See the discussion about fingerprints under ‘Creating a Referrer’ for more information.