Referrals 2.0: Integrating With Salesforce/Marketing Automation Provider

Setting up the Referrals 2.0 integration with Salesforce allows you to do two things:

track your referrals as leads and also update your referral milestones in Influitive as the lead gets updated in Salesforce.

This article requires some working knowledge of Salesforce/your Marketing Automation System. You may want to brush up on this if you have not already done so.

Steps 1-5 can be done on your own through your AdvocateHub. However, once you get to step 6, you will likely need to involve your Salesforce Administrator or someone with Salesforce Admin access.

1. Overview

At a high level, this is how the Influitive Integration with Salesforce / your Marketing Automation provider will work:

• For each referral created in Influitive, a corresponding Lead will be created in Salesforce or your Marketing Automation system.
• Every Salesforce/Marketo Lead that corresponds to an Influitive referral will be populated with a unique Referral ID. This Referral ID allows Influitive to know which Salesforce/Marketo Leads are Influitive Referrals, and who referred them. This Referral ID field can be downloaded via the Salesforce AppExchange Package or created manually. For Marketo, this field can be created manually. Important Note: The Referral ID must be sync in both Salesforce and Marketo if you have set up bi-directional sync.
• Using Workflow rules, you can use Salesforce to send an Outbound Message to our Influitive API to alert Influitive whenever a referral has progressed to a new Milestone. Influitive will then update the referral in Influitive, and award points and notify the referrer accordingly.
• Duplicate leads are handled in the following way:
  • Salesforce - when pushing leads to Salesforce, a duplicate lead will not be created. It will not overwrite existing fields for that lead but will update blank fields on the lead record with new information. However, if the lead is a campaign member, it will fail to push. 
  • Marketo, Hubspot, and Eloqua - when pushing leads to either Marketo, Hubspot or Eloqua, a duplicate lead will not be created. It will overwrite existing fields with new information.

2. Enable the Influitive API Integration

You first need to enable the Influitive API integration to allow Referrals 2.0 to integrate with your Salesforce or Marketing Automation provider instance.  

2.1 Login to Influitive, and click on the cog wheel in the top right corner of Admin View and go to Integrations.

2.2 Under Categories, go to Marketing > Influitive API > Manage

2.3  Click on Enable Integration

2.4 Click on the Setup tab. This will reveal your Authorization Token and X_ORG_ID.  Make note of these values, as you will need them later for triggering outbound Salesforce messages.

3. Authorize your Referrals 2.0 with Salesforce OR your Marketing Automation System

In order to push referral leads from Influitive to your system, you must first authenticate EITHER your Salesforce credentials in Influitive OR your marketing automation credentials. Choose ONE or the other NOT both.

If you want to push leads to Salesforce but do not yet have a Salesforce account or want to first practice these steps in a sandbox environment, you can sign up for a free Salesforce developer account.  

Once you have decided:

3.1 Login to Influitive, and click on the cog wheel in the top right corner of Admin View and go to Integrations.

3.2  On the left hand side under Categories, go to either CRM (for Salesforce) or Marketing (for your marketing automation provider).

Click Manage under the integration you'd like to turn on. You should only turn on ONE of the options below. Consult the instructions above for our best practices if you are not sure which one to use.

3.3 Click on Enable Integration

3.4 Click on Authenticate or follow the steps to continue your authentication

3.5 If you chose Salesforce, login with your Salesforce Username and Password. 

3.6 Click Allow to allow access

3.7 You are now authenticated!

4. Set up Lead Flow from Influitive Referrals to Salesforce or your Marketing Automation System

Next, you may want to have your referrals from Influitive pushed into either your Marketing Automation System or Salesforce as leads.   

To configure lead pushing to Salesforce or your Marketing Automation System:

4.1  Go to the Integration Library and find the integration that you authenticated in section 3 above (it could be your Marketing Automation provider or Salesforce).

4.2 Click Manage on the integration and go to the Settings tab. Turn the button to On. Then click the arrow icon to expand the section Push...leads.... 

Example from Salesforce for Referrals 2.0 below:

4.3  Choose which fields from your Influitive referrals you want to map to your Marketing Automation Provider / Salesforce Lead fields. This is how the data from Influitive will be translated to the lead object. 

Click the + Add Mapping button at the bottom if you want to add a mapping. To remove a mapping click the X to the left side of the mapping.

You must have a mapping to the following Salesforce for Referrals 2.0 / Marketing Automation System fields:

• Lead - First Name
• Lead - Last Name 
• Lead - Company
• Lead - Email

If you do not have these mappings set up, there will be an error when you save as Salesforce requires these fields for any new lead.

The nomenclature on the Influitive Field section is as follows:

• Prospect - The referral
• Contact - The referrer (the person who submitted the referral)
• Referral - The Influitive Referral Campaign
• CRM - If you see this section, it can be ignored and is for internal purposes only.

For the prospect, you can choose to map from the Influitive Field section any of the fields you collected in the form on your referral campaign. The field name that appears in this section will be the same as the Label on the Referral Form. If you don't see a field and would like it to appear, make sure you create that field on the form in your referral campaign.

For the contact, you can choose from a preset list of fields as below:

A few things to note:

• Contact - Id: This is not the contact's Salesforce/MAS ID but an ID generated by the hub for tracking purposes. You do not need to map this unless you wish to capture it for a particular reason.
• Contact - CRM Contact id: If you wish to create a link on the lead record to the referrer's contact record in Salesforce, you can map this to a custom Lookup field and you can call it Lead - Advocate Hub Referral Source C. Note that if the referrer is not an advocate in your hub/they are not a contact in SFDC, this field will remain blank.

Below is a sample mapping. Yours may be different depending on your setup and your referral form fields. Remember that you must have the first 4 mappings as Salesforce requires them.

Notice that in this mapping, we are sending information about the Prospect (the referral) as well as the Contact (the person who submitted the referral). That way, you/your Sales team will know who the referrer is and can even CC them when reaching out to the referral, improving the likelihood that the referral will respond.

You may need to create new fields on the lead record (for instance Referral Source Email, Referral Source Title, etc.) If you wish to capture this information and have not mapped to Lead - Advocate Hub Referral Source C as per above. 

You may also wish to create these fields to capture information about non-advocates; if you are pushing leads to a MAS; and referrers that are not in your Salesforce contacts.

4.4  Assign your Referral Leads to a Campaign in Salesforce (Optional).

If you want to associate a Salesforce Campaign to your leads, edit your Referral Campaign and add a hidden field to your referral form named crm_campaign_id. Make sure you use the exact name "crm_campaign_id" in the Field Name box. The default value should be the ID of the campaign in Salesforce. Influitive will automatically add your referrals to that Salesforce campaign, you do not need to map this field to your leads.

4.5 Generate a test referral and verify it appears in Salesforce / your Marketing Automation system.  Follow the steps here

5. Configure the Influitive Referral Milestones you want to be advanced by Salesforce or your MAS

6.2 Now repeat step 6.1 but for ANY additional object that your Lead might become, which would need to trigger a milestone update in Influitive. 

For instance, you might want to do this on all your Opportunity objects, if a Lead becomes an Opportunity once it progresses. You might also want to do it on your Account and Contact objects, if your Leads become/get attached to those as they progress.

6.3  Now you need to link all of those objects together. You will need to map the Referral ID from the Lead to all the objects (i.e. Opportunities, Accounts, Contacts, etc) where you added a Referral ID field in Step 6.1 . This way, if a Lead converts to another object (i.e. Lead -> Opportunity) you can still advance the Milestones in Influitive.   

Go to Salesforce -> Setup -> Customize -> Leads -> Fields -> scroll down to the Custom Fields section and click Map Lead Fields. Map the Referral ID field to the corresponding Referral ID field of the Opportunity or any other object you specified in Step 6.2.

7. Map Referral ID from Influitive to Salesforce or your Marketing Automation System

7.2 Now add a mapping from Referral - Referral Id in Influitive to the Referral ID field in Salesforce or your MAS. The name of the field should look something like: Lead - Advocate Hub Referral Id c

The "c" simply indicates it is a custom lead field.

8. Create an Outbound message to Influitive for every milestone update

Referrals 2.0 gives you the ability to create custom milestones in your Referral Campaign and advance them based on status changes in Salesforce. As you progress a Lead in Salesforce, they will also progress in Influitive Referrals.   

Note: Sections 8/9/10 of this article will explain how to advance milestones in the hub from Salesforce. If you wish to advance milestones in the hub directly from Marketo or another MAS without using Salesforce, you need to use our API. For information on how to do this using Marketo, see here. For other MAS, see here. 

8.1 First, edit your Referral Campaign and ensure you created the appropriate milestones for your referral campaign. The default milestones are: Submitted, Qualified, Won, Lost.  Note the API code for each milestone you've created.  

8.2 Next, you will need to create an  Outbound Message for each Referral Milestone that you would like to update in the Hub. This will be triggered by your Salesforce Flows.  

In Salesforce, Go to your Salesforce Setup > Workflow actions > Outbound Messages >  New Outbound Message.

Select the Object where the you would like the Outbound message to run from. For example: We are looking to run the Outbound message when the Flow rule triggers a Lead status update on the Lead Object. Therefore, we will select Lead object here.

8.2 Now fill out the fields in your Outbound Message as follows (screenshot below):

• Name: Whatever you'd like to call it (e.g. "Influitive Referral Milestone Advance - Qualified")
• Endpoint URL: Use this format:
  • https://api.influitive.com/referral-automation/sfdc/transition?auth_token=<xxxx>&hub_id=<yyyy>&status=<zzzz>
    • replace  <xxxx> with your Authorization Token (e.g. e58528e623a50e9bcb5be9f085f15303e4d381d5). This is the same fields you noted in the Enable Influitive API section above.
    • replace  <yyyy> with your X_ORG_ID (e.g. ef7c8170-58d8-49b0-85de-441afdf00d4). This is the same field you noted in the Enable Influitive API section above.
    • replace  <zzzz> with the API Code for the Milestone you'd like your referral to be updated to for this particular rule (e.g. won). This is the same API Code that you noted in the Milestone section above.

  • A sample API endpoint might be: https://api.influitive.com/referral-automation/sfdc/transition?auth_token=e58528e623a50e9bcb5be9f085f15303e4d381d5&hub_id=ef7c8170-58d8-49b0-85de-441afdf00d4f&status=won

    Note: Ensure that there are no spaces in the API endpoint or it will not work. The API Code is also case sensitive.

• Lead fields to send / Selected Fields:  Make sure you add AdvocateHub__Referral_ID_c to Selected Fields

8.3 Click Save. You will need to remember the Name of the Outbound message for when you create a Salesforce Flow in Step 9.

8.4 Return to Step 8.2 and repeat this process for any further milestones you have to set up.

9. Create a Flow rule for every relevant referral update

Create a Salesforce Flow rule to trigger the Outbound message you've created in the previous step. Use this step to migrate Salesforce Workflow rules (retiring at the end of 2022) to Salesforce Flows.

We recommend filling out the following template to plan out the Referral Lead process.

9.1 Now login to Salesforce -> Setup -> Process Automation -> Flow. You're going to set up one Flow Rule for each time you want a referral milestone to be updated.

9.2 Click on “ New Flow” > Select Record-triggered Flow

9.3 Next, select the Object where you want the trigger to start.

Your referrals will default to the Submitted milestone automatically when they are entered by an advocate, so you don't need to worry about that milestone.

Each company is different, but here is a sample:

Influitive Milestone         Status in Salesforce                                       Salesforce Object

Important Note on Converting Leads into Other Objects: If you require an object other than a Lead to trigger a milestone update, you need to ensure that you  convert the lead into that object. Otherwise, Influitive will not be able to update the correct milestone. For instance, if you want Opportunity Status "Closed Won" to indicate a referral is Won, you need to make sure that the original lead created for that referral is converted into an opportunity, and then that opportunity status is marked as "Closed Won." If you create a separate opportunity without converting it from the original Lead, Influitive will not be able to progress the milestone for the appropriate referral unless that object has the Referral ID from the original Influitive lead. You may be able to use other tools on the Salesforce AppExchange such as Rollup Helper to assist you in doing this if you choose not to follow the conversion path.

9.4 Configure Trigger > Trigger the Flow when: > Select “ A record is created or updated”

9.5 Set Entry Conditions. You can set your trigger criteria here. You should have a minimum of two criteria:

1. Referral ID (appexchange) is not equal to blank (Required)
2. Whatever the criteria are for triggering the milestone update (e.g. Field: "Lead: Lead Status" "equals" "Working - Contacted."

For this example, let’s use the following:

- Condition Requirements: All Conditions Are Met (AND)

- AdvocateHub__Referral_ID__c is not null (not empty). This means that it will only trigger if a Referral Lead is coming from Influitive and has the AdvocateHub Referral ID (appexchange) field populated.

- Lead Status is equals to the milestone status if your choosing.

9.6 When to Run the Flow for Updated Records: Every time a record is updated and meets the condition requirements

9.7. Click Done and time to create an Action and connect to the Outbound Message you've created on Step 8.

9.8 Click on the plus sign to Add Element and select Action.

9.9 Select Outbound Message > Under the Action field, select the Outbound message you would like to run when the Flow is triggered. Add the Label and API Name for this Action and Done.

9.10 Save your Flow and Add Flow Label and Flow API Name that corresponds with your milestone update. It's recommended that you provide a description of what triggers and action is included in this Flow.

9.11 Repeat Step 9 for each Referral milestones.

9.12 Now that the Flow is saved. Run a test by submitting a Referral Test Lead.

Update a lead or other object in Salesforce that should trigger a milestone update in Influitive (you may want to create a test lead/opportunity with $0 value to avoid confusing anyone else in your company!). 

Then open your Referrals Dashboard in Influitive to see if the milestone successfully updates. If it does, then you are good! If not, see the troubleshooting steps below.

10. Add a Feedback Field (Optional)

A feedback field allows you to specify why a milestone was changed. For instance, you might advance a referral to a "Lost" milestone and provide the feedback "wasn't a good fit." This feedback will get sent as a message (either an email or an in-app notification) to the person who generated the referral and will be shown in the feedback section on the referral dashboard.  

To set this up:

10.1  Login to Salesforce -> Setup -> Customize -> Leads -> Fields -> Scroll down to Custom Fields section and click New 

10.2 Add Feedback as a field on your lead object (make sure to use the exact capitalization and parameters below):

• Formula
• Field Label: Referral Feedback
• Length: 200
• Field Name: Referral_Feedback

10.3 Now create the formula for your Feedback field based on other fields' relevant information. For instance, if you have a Lead Status field that provides the status of the lead, you might want to display feedback based on that status. For instance if Lead Status = "Closed - Not a fit", you might want to have feedback saying "Thanks for the Referral, but it looks like they are not a fit!"  Below is an example of how we do this at Influitive.

10.4 Once the formula is complete, for any lead workflow rules you set up above, add feedback as a field in the outbound message (Step 9.2 above). To do this you must edit the Workflow by editing the Workflow Actions.

10.5 Repeat Steps 10.2/10.3 for any other objects you have setup that trigger milestone updates (Opportunity, etc.). Make sure you map the Feedback field from the Lead in the Mapping fields process.

10.6 Test your set up.

11. Testing your setup

Testing Leads Pushing from Influitive to Salesforce

Here we will test that a referral you make in Influitive will show up in Salesforce. Make sure you have completed Sections 1-4 above before attempting this.  

11.1  Follow these steps to submit a referral through the advocate referral campaign page. Let's pretend we submitted a referral named "Frank Smith".

11.2 Now login to your Salesforce Account and type in "Frank Smith" in the search box.

11.3 You should see your lead "Frank Smith" appear in the Lead results. If it does not appear you may want to try the troubleshooting steps here.

11.4 Click on Frank's name to open the Lead Detail page. Verify the fields you mapped from Influitive to Salesforce have been correctly added to the Lead. You may want to check your mapping if not.

Testing Object Update to Salesforce Pushing Milestones to Influitive

11.5 Update a lead or other object in Salesforce that should trigger a milestone update in Influitive (you may want to create a test lead/opportunity with $0 value to avoid confusing anyone else in your company!).

If everything looks good, then you are all set! If not, see the troubleshooting steps below.  

12. Troubleshooting your setup

If your leads are not showing up in Salesforce

12.1 Make sure you have enabled the Influitive API Integration (see this step).

12.2 If you already have done this and the issue persists, go to the Salesforce for Referrals 2.0 section of the Integrations page

12.3 Click on the Logs tab:

12.4 Note if there are any failures.

12.5 Check the error message and see the steps to remedy:

INVALID_CROSS_REFERENCE_KEY - "xyz" : this ID value isn't valid for the user: "abc" - the user you are authenticated with ("abc") doesn't have access to update the field ("xyz") in Salesforce to the specified value. Your salesforce admin should update the user credentials for the Influitive authenticated user to give permissions for that.

ERROR: REQUIRED_FIELD_MISSING - Required fields are missing: "xyz"  - you have mapped a field "xyz" from Influitive to Salesforce but the field on the Influitive side is blank.  You either need to make sure this field is not blank in on the referral form (i.e. make sure this field is filled in on the form and/or  make this field required on the referral form), or remove the mapping for that field. You must have a mapping to at least these 4 fields in Salesforce, so you will not be able to remove these mappings: Lead - First Name, Lead - Last Name, Lead - Company, Lead - Email.  

If your leads are showing up in Salesforce but the correct fields are not being updated

Make sure you check your mapping above and verify the correct fields are being mapped.

If your milestones are not advancing

12.6 Login to Salesforce and go to Setup -> Administration Setup -> Monitoring -> Outbound Messages

12.7 Check if any messages are showing as failed. Check the Delivery Failure Reason. 

12.8 Follow the steps below depending on the failure reason:

(404)Not Found

• make sure you have entered "https://" in the endpoint URL above for api.influitive.com, not "http://"
• make sure the authorization token and X_ORG_ID are correct in the endpoint url
• make sure the API URL domain matches the domain of your hub. So if your hub is on staging (influitives.com), the API URL must also be on staging (https://api.influitives.com)
• make sure the Referral_ID field you are passing in the body of the outbound message is not blank. If it is blank, you need to make sure that you have mapped it from Influitive as per Section 7.
• make sure the field name for the field you create in Section 6.2 matches exactly Referral_ID

(422)Unprocessable Entity

• make sure the milestone code in the endpoint URL you entered is valid and exists in the referral campaign you are trying to update. Remember that this code is also case-sensitive.

(503)Service Unavailable Error

• a server may be down on the Influitive side.