# Create referral programs

> A referral program is defined by an advocate, a friend and a referral code.

> For the complete documentation index, see [llms.txt](https://docs.talon.one/llms.txt).

- The **advocate** is the person who invited their friend via a referral program.
- The **friend** is the person who receives the invite from an advocate.
- The **referral code** is a generated code that can be used by one or more friends.

To learn more about what referral programs are, see the
[Product docs](/docs/product/campaigns/referrals/referral-overview.md).

## Overview

Let's imagine we want to set up a referral program for our business in
Boston, USA. The program should give a referral code to every customer in the database
that they can share with their friends.

## Set up a referral program

Before we begin, let's suppose we have a campaign with the referral and coupon features
active.

To set up a referral program, we must generate referral codes for our customers.
We can do this in two ways:

- Using the [Create referral code for an advocate][createReferral] endpoint from the Integration API.
- Selecting the `Create referral code` as an effect in a rule inside the Campaign Manager.

Both methods as they offer different benefits.

### Use the endpoint

The endpoint allows us to create referral codes directly instead of updating customer
sessions. We can also set a start/expiration date and link the referral code to a customer
profile.

:::note
Another option is to link the referral code to a friend, which is useful when you're
migrating historical referral campaigns to Talon.One.
:::

Let's call the [Create referral code for an advocate][createReferral] endpoint with this
example payload that creates a referral code for customer 88:

```json
curl https://example.talon.one/v1/referrals \
-X POST \
-d '{
    "advocateProfileIntegrationId": "88",
    "campaignId": 58,
    "startDate": "2020-02-12T15:22:48.351041-05:00",
    "expiryDate": "2020-05-28T15:22:48.351041-05:00",
}'
```

:::note Note about the time zone
Pay attention to the `startDate` and `expiryDate`
properties. They use the RFC3339 format. They can contain any time zone,
relative to UTC. In this case, the time zone is EST, or UTC-5. You can provide
any time zone (your own, your store's, your app's...), it is
converted to UTC internally.
:::

We can repeat this operation for each customer of our database to give them a
referral code.

### Use a Rule Builder effect

Let's now imagine that we have more than one loyalty campaign in our Application.
In this case we want to choose in which campaign the referral code can be redeemed.
To do this, we must use the Rule Builder in the Campaign Manager and
[create an effect](/docs/product/rules/effects/use-effects.md).

Whenever this rule gets executed successfully, the Integration API returns
the [referralCreated effect](/docs/dev/integration-api/api-effects.md#referralcreated). It
contains the referral code generated.

## Communicate referral codes to Talon.One

When a user inputs a referral code in your Application, share it with Talon.One using
the [Update Customer Session][updateCustomerSession] endpoint.

For example, submitting the `kg5yldcv1i` referral code for the profile with id `35`:

```js
curl https://example.talon.one/v2/customer_sessions/C156902 \
  -X PUT \
  -d '{
  "profileId": "35",
  "referralCode": "kg5yldcv1i"
  }'
```

After you submit the code, check whether Talon.One accepted or rejected the referral code
by looking for the following effects in the response:

- [acceptReferral](/docs/dev/integration-api/api-effects.md#acceptreferral)
- [rejectReferral](/docs/dev/integration-api/api-effects.md#rejectreferral)

[createReferral]: /integration-api#tag/Referrals/operation/createReferral
[updateCustomerSession]: /integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2