# Create referrals via Braze

> In this tutorial, let's set up Braze to automatically generate referrals inside Talon.One and deliver the referral codes to specific customer segments.

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

To do so, we'll send requests to a Talon.One Braze-specific endpoint that generates referrals.

## Talon.One requirements

- You are an [admin](/docs/product/account/account-settings/manage-roles.md#admin-role) user.
- You have set up an [Application](/docs/product/applications/create-and-manage-applications.md).
- Your Application contains a running [campaign](/docs/product/campaigns/create-and-manage-campaigns.md) with the **Referrals** feature
  [enabled](/docs/product/campaigns/settings/manage-campaign-features.md).

You can edit the default format of the referral codes in
the campaign's <Settings className="icon" /> **Settings** > **Referral Codes** section.

## Braze requirements

- You have created a [campaign](https://www.braze.com/docs/user_guide/messaging/campaigns/creating_campaign) or [canvas](https://www.braze.com/docs/user_guide/messaging/canvas) in Braze.
- You have a way to identify a given customer across Talon.One and Braze.
   In this tutorial, we assume a customer's Talon.One `integrationId` is always equal to Braze's `user_id`.
   You can also create a new property on your Braze customer profiles to store Talon.One's integration ID.

## Set up the integration

<StepsContainer>

### Create an API key in Talon.One

In the Campaign Manager, create a Braze-specific API key:

1. In your Application, click <Settings className="icon" /> **Settings** > **Integration API Keys**.
1. Click <Add className="icon" /> **Create API Key**.
1. In the **Create API Key** drawer, if you are asked for a key type, select **Production**.
1. In **Key name**, type a name to identify the key.
1. In **Key expiration date**, select a date.

   :::tip
   Avoid choosing expiration dates that fall at the end of the year or during other
   high-traffic periods.
   :::

1. In **Third-party integration**, select **Yes**.
1. From **Platform**, select **{props.partner}**.
1. Click **Create API Key**.
1. Click <Copy className="icon" /> to copy the key for use.

:::note
You cannot view or copy the API key after closing the drawer.
:::

We will use the API key in the Braze campaign template.

### Create the referral code

To generate a referral code from Braze, we call the following endpoint:

```text title="POST Create referral"
https://integration.talon.one/braze/referral
```

<Button variant="primary" size="l" href="/third-party-api#tag/Braze/operation/braze/createReferral">
  See API docs
</Button>

To trigger the endpoint, we must use Braze's
[Connected Content](https://www.braze.com/docs/user_guide/messaging/design_and_edit/personalize/connected_content/making_an_api_call) feature.

:::important
We assume that your customer profile in Braze contains a unique identifier that is equal to the customer integration ID in Talon.One.
In this tutorial, we use `${user_id}`. Ensure the user ID matches the integration ID in Talon.One.
:::

1. Open your Braze campaign or canvas for editing.
1. Add the following Connected Content call to the body of your message, where:
   - `YOUR_DEPLOYMENT_URL` is the base URL of your Talon.One deployment.
   - `YOUR_CAMPAIGN_ID` is the ID of your campaign in Talon.One.
   - `YOUR_API_KEY` is the API key you [created](#create-an-api-key-in-talonone).

   ```liquid
   {% capture postbody %}
     {"deploymentUrl": "YOUR_DEPLOYMENT_URL","campaignId": YOUR_CAMPAIGN_ID,"advocateProfileIntegrationId": "{{${user_id}}}"}
   {% endcapture %}

   {% connected_content https://integration.talon.one/braze/referral
     :headers {"Authorization": "ApiKey-v1 YOUR_API_KEY"}
     :method post
     :body {{postbody}}
     :content_type application/json
     :save result
   %}

   Your referral code is: {{result.code}}
   ```

1. To test your request:
   1. In the sidebar, click **Preview & Test**.
   1. In **Preview message as user**, select **Search User** and search for an existing user in Braze.You should see a referral code.
   :::note
   A new referral code is only generated **once** per user ID.
   :::

Your referral codes are now generated automatically when your campaign is running.

</StepsContainer>

## Customize the referral call

You can customize the [Braze call](#create-the-referral-code) with the following form.

:::note
This form does not cover all the available options for creating referral codes. See the [API docs](/third-party-api#tag/Braze/operation/braze/createReferral) for an exhaustive list.
:::

<BrazeCodeGenerator endpoint="referral"/>