> For the complete documentation index, see [llms.txt](https://docs.growsurf.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growsurf.com/integrations/salesforce.md).
# Salesforce
Trigger referrals when Salesforce records match the conditions you choose and update/add Salesforce contact field labels with their unique share link and referrer information.
{% hint style="warning" %}
**Important Note:** Your Salesforce user account MUST have the proper permissions to perform the following actions within Salesforce:
* Create custom fields, delete custom fields
* Assign permissions to those custom fields
* Create contacts, delete contacts
* Create or update the GrowSurf-managed Salesforce PushTopic used for referral-trigger events
If you do not have these permissions, the Salesforce integration cannot be enabled within your program. Please contact your Salesforce system administrator to update your user account with the listed permissions to proceed.
{% endhint %}
## Referral Trigger
### Description
When you connect your Salesforce account to your GrowSurf program and enable *Referral Trigger*, GrowSurf can automatically detect and trigger referrals when the Salesforce records you choose match the conditions you configure.
GrowSurf lets you choose one Salesforce object, one direct trigger field on that object, and one exact value to match. Supported objects include:
* Opportunity
* Lead
* Contact
* Account
* Other Salesforce custom objects that are queryable in your Salesforce account
GrowSurf then determines which participant should count as the referred participant:
* **Opportunity:** By default, GrowSurf uses the *Primary Opportunity Contact*. You can also choose *All Opportunity Contacts* as an advanced option.
* **Lead:** GrowSurf uses `Lead.Email` to find the referred participant.
* **Contact:** GrowSurf uses `Contact.Email` to find the referred participant.
* **Account** and **Other Salesforce Object:** GrowSurf can use a direct email field on that object, a direct Contact lookup, or a direct Lead lookup to find the referred participant.
{% hint style="info" %}
**Note:** GrowSurf creates and manages its own Salesforce PushTopic for referral-trigger events. If Salesforce connects successfully but enabling or changing the *Referral Trigger* fails, ask your Salesforce administrator to confirm that the connected user has the API access and PushTopic permissions required to create and update that GrowSurf-managed PushTopic.
{% endhint %}
In order for a referral to trigger from within Salesforce, the following must be true:
1. The selected Salesforce record must exist
2. The selected trigger field on that record must match the exact value you configured
3. GrowSurf must be able to resolve one or more referred-participant email addresses from the matching rule you selected
4. One or more of those resolved email addresses must already exist as participants in the GrowSurf program connected to Salesforce
If all of the above holds true and a participant match is found, the referral will trigger within GrowSurf. Referral credit will then be given to the referrer and unlock any rewards, if applicable.
Here's how to set up Salesforce referral triggers:
### **How to Set Up**
{% hint style="warning" %}
If your program does not add participants automatically ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LgbRcVrYaKYUhQVctKK%2F-LgbS62PrNqHiJm-qwdI%2FScreen%20Shot%202019-06-05%20at%207.42.50%20PM.png?alt=media\&token=85e064ce-4bac-4617-9481-f80215478d51)), add them first with JavaScript [`growsurf.addParticipant()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#add-participant) or the REST API [`/POST Add Participant`](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-participant).
{% endhint %}
**Step 1**: In *Program Editor > 4. Options > Integrations*, click the *Connect to Salesforce* button, then choose *Production org* or *Sandbox org*.
{% hint style="info" %}
**Note:** Salesforce sandbox orgs are best for testing. If you choose *Sandbox org*, GrowSurf sends you through Salesforce's sandbox login. We recommend connecting sandbox orgs to a separate GrowSurf test program instead of your live program.
{% endhint %}
{% hint style="info" %}
**Note:** Once connected, Salesforce requires us to collect certain information from your organization, such as Org ID and business address. Please contact GrowSurf support [here](http://app.growsurf.com/settings#contact_support) to submit your organization details.
The Salesforce integration will continue to work without this information, however, to ensure there are no service interruptions please submit this information within 3-5 business days of your first GrowSurf invoice payment.
{% endhint %}
**Step 2:** Once connected, toggle the switch to enable the Referral Trigger.
**Step 3:** Choose the Salesforce object, direct trigger field, and exact value that triggers the referral.
**Step 4:** Choose how GrowSurf should identify the referred participant when that record matches.
* For Opportunities, choose either *Use the Primary Opportunity Contact* or *Use all Opportunity Contacts (advanced)*.
* For Leads and Contacts, GrowSurf automatically uses the record's email field to find the referred participant.
* For Accounts and custom objects, choose a direct email field, Contact lookup, or Lead lookup that points to the referred participant.
**(Optional) Step 5:** You can add a referral trigger hold period by toggling the *Show advanced settings* section.
{% hint style="info" %}
**Note:** The referral trigger hold period is useful for making sure that Salesforce records that stop matching do not count as referrals. During this hold period, if the selected Salesforce record no longer matches the condition you configured, the referral trigger will be cancelled completely.
{% endhint %}
### Troubleshooting Tips
* When testing out the Salesforce Referral Trigger integration, make sure to view participants' activity logs for details that can help you troubleshoot any issues.
* Salesforce can take a minute or longer to send record updates, so a referral may not trigger right away.
* If you are connecting a Salesforce sandbox org, choose *Sandbox org* after clicking *Connect to Salesforce*. If your program is already connected to the wrong org type, disconnect Salesforce and reconnect with the correct choice.
* If Salesforce connects but GrowSurf shows an error when you save or change the *Referral Trigger*, ask your Salesforce admin to confirm that the connected user can create and update the GrowSurf-managed Salesforce PushTopic and has the required API access.
* If you are using *Use the Primary Opportunity Contact* for Opportunities, make sure exactly one primary contact is marked on the Opportunity. If there is no primary contact, GrowSurf will not trigger the referral for that Opportunity.
* If you are using an Account or custom object, make sure the matching rule points to a direct email field, Contact lookup, or Lead lookup on that same object. GrowSurf does not follow indirect relationship chains for Salesforce referral triggers.
## Sync Data
### **Description**
When new GrowSurf participants are added to your program, they will automatically be added/updated as Salesforce contacts with new *GrowSurf Field Labels.* Their unique share link and referrer information will be available for use in emails and reports.
### How to Set Up
**Step 1:** In *Program Editor > 4. Options > Integrations*, click the *Connect to Salesforce* button, then choose *Production org* or *Sandbox org*.
{% hint style="info" %}
Connect Salesforce before importing participants. If participants are already in your program, follow [these ESP sync options](https://support.growsurf.com/article/385-how-can-i-sync-my-growsurf-participants-to-my-esp) to send their GrowSurf data to Salesforce.
{% endhint %}
**Step 2:** Give GrowSurf authorization to connect to Salesforce
### Enabling Contact Field Visibility in Salesforce
Once you have successfully connected to Salesforce, GrowSurf fields are automatically available. However, in some cases, the custom field permissions must be modified to grant other Salesforce users access and allow visibility.
To find contact fields and add permissions to those fields as an admin, follow the steps below:
**Step 1:** In Salesforce navigate to *Setup > Object Manager > Contact > Fields and Relationships*
**Step 2:** Select a Field Label from the list
**Step 3:** Click the *Set Field-Level Security button* and make modifications.
{% hint style="danger" %}
**Critical Note:** If any of the defaulted permissions (currently System Administrator and Standard User) are removed, GrowSurf will not have the ability to add contacts with the GrowSurf custom fields (e.g., GrowSurf Share URL).
{% endhint %}
### How to Add Fields to Page Layouts in Salesforce
To view the GrowSurf custom fields within Salesforce, you must update one or more page layouts so that the fields appear for contacts within Salesforce.
**Step 1:** In Salesforce navigate to *Setup > Object Manager > Contact > Page Layouts*
**Step 2:** Select the target page layout from the list
**Step 3:** Click and drag one or more GrowSurf custom contact fields into the view
**Step 4:** Click the *Save* button
**Step 5:** Navigate to the layout to view the added fields
### Examples
[View our Salesforce tutorials](https://docs.growsurf.com/integrations/salesforce/tutorials) to see different kinds of examples that you can copy/paste into your email templates.
### Contact Field Labels
GrowSurf will automatically create these new contact field labels for your Salesforce contacts.
| **Field Label** | **API Field Name** | **Type** | **Description** | **Example** |
| ------------------------------------------------- | --------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| GrowSurf Share URL | `growsurf_share_url__c` | URL | The participant's unique Share URL (contains their unique GrowSurf ID) | `https://piedpiper.com?grsf=d77a8j` |
| GrowSurf Participant ID | `growsurf_participant_id__c` | Text | The participant's unique GrowSurf ID | `d77a8j` |
| GrowSurf Referral Status | `growsurf_referral_status__c` | Text | The referral status of the participant\* | `CREDIT_PENDING` |
| GrowSurf Referrer Email | `growsurf_referrer_email__c` | Email | The email of the participant's referrer | `gavin@hooli.com` |
| GrowSurf Referrer First Name | `growsurf_referrer_first_name__c` | Text | The first name of the participant's referrer | `Gavin` |
| GrowSurf Referrer Last Name | `growsurf_referrer_last_name__c` | Text | The last name of the participant's referrer | `Belson` |
| GrowSurf Participant First Name | `growsurf_participant_first_name__c` | Text | The participant's First Name | `Bob` |
| GrowSurf Participant Last Name | `growsurf_participant_last_name__c` | Text | The participant's Last Name | `Loblaw` |
| GrowSurf Total Referral Count | `growsurf_total_referral_count__c` | Number | The participant's all-time referral count | `0` |
| GrowSurf Lead Count | `growsurf_lead_count__c` | Number | The participant's current lead count (pending referrals that have not converted yet) | `0` |
| GrowSurf Monthly Referral Count | `growsurf_monthly_referral_count__c` | Number | The participant's current month referral count | `19` |
|
GrowSurf
Prev Monthly Referral Count
| `growsurf_previous_monthly_referral_count__c` | Number | The participant's previous month referral count | `200` |
| GrowSurf Next Milestone | `growsurf_next_milestone__c` | Text | The text for the next/upcoming milestone reward (only applies to milestone rewards. [See an example here](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-next-milestone)) | `You are only 2 referrals away from winning a free t-shirt!` |
| GrowSurf Next Monthly Milestone | `growsurf_next_monthly_milestone__c` | Text | The text for the next/upcoming monthly milestone reward (only applies to milestone rewards. [See an example here](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-next-milestone)) | `You are only 2 referrals away from winning a free t-shirt!` |
| GrowSurf Total Invite Count | `growsurf_total_invite_count__c` | Number | The participant's all-time invite count | `112` |
| GrowSurf Total Impression Count | `growsurf_total_impression_count__c` | Number | The participant's all-time impression count | `150` |
\**GrowSurf Referral Status* can have one of these values:
* `CREDIT_PENDING`: The participant must trigger a referral before their referrer receives credit.
* `CREDIT_AWARDED`: The participant triggered a referral, and their referrer received credit.
* `CREDIT_EXPIRED`: The participant did not trigger a referral before the referral credit expired.
### Troubleshooting Tips
* Check the participant's activity logs if they do not sync. GrowSurf retries failed syncs for up to 7 days.
* **If the new participant is being added twice to Salesforce (as a Lead and Contact):**
* If you are tracking referrals on a form (typically a Marketo form), you will always see a new Salesforce contact created/updated by GrowSurf. This is the expected behavior, as GrowSurf will create/update Salesforce Contact objects regardless of Salesforce Lead objects. Your form most likely has an automation that also generates a Salesforce Lead upon form submission.
* **NOTE:** Even if you have a Duplicate Rule set up in your Salesforce instance to prevent Leads and Contacts from having the same email address, GrowSurf will still create a new Contact if it does not already exist.
* **If you are having trouble connecting to Salesforce:**
* If you are having trouble connecting Salesforce to your GrowSurf program, the issue may be related to permissions. Contact your Salesforce administrator and ask them to enable API access in the 'Permission Sets' section. Keep in mind that API access is only available in certain Salesforce editions, including Enterprise, Unlimited, Developer, and Performance. It is not available in Group, Essentials, and Professional but can be added as a feature in the Professional edition. For more information, check out [Salesforce editions with API access](https://help.salesforce.com/s/articleView?id=000385436\&type=1).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.growsurf.com/integrations/salesforce.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
