Referrals 2.0: Integrating with Salesforce/Marketing Automation Provider
Setting up the Referrals 2.0 integration with Salesforce.com or your Marketing Automation provider allows you to 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.
- Enable the Influitive API Integration
- Authorize your Referrals 2.0 with Salesforce OR your Marketing Automation System
- Set up Lead Flow from Influitive Referrals to Salesforce or your Marketing Automation System
- Configure the Influitive Referral Milestones you want to be advanced by Salesforce.com or your MAS
- Set up Lead Fields in Salesforce
- Map Referral ID from Influitive to Salesforce or your Marketing Automation System
- Trigger a workflow rule for every relevant referral update
- Trigger an Outbound message to Influitive for every milestone update
- Add a Feedback Field (Optional)
- Testing your Setup
- Troubleshooting your setup
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 Lead that corresponds to an Influitive referral will be populated with a unique Referral_ID. This Referral_ID allows Influitive to know which Salesforce Leads are Influitive Referrals, and who referred them.
- 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 - when pushing leads to Marketo, a duplicate lead will not be created. It will overwrite existing fields with new information.
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 your name 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.
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.
Our best practice suggestion is that if you use a marketing automation provider (like Marketo, Hubspot, Eloqua), to push leads from Influitive to that system first and then have that system automatically sync with Salesforce - rather than pushing it directly from Influitive to Salesforce.
Remember choose only ONE - do NOT integrate with BOTH Salesforce AND a Marketing Automation provider for this step.
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 your name in the top right corner of Admin View and go to Integrations
3.2 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.
Note: if you choose Marketo or Salesforce, make sure you use Marketo V2 or Salesforce for Referrals 2.0
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.com Username and Password.
Note: You may want to consult your Salesforce Admin on the login to use. Often they may want you to use a designated integrations user for this.
3.6 Click Allow to allow access
3.7 You are now authenticated!
Next, you may want to have your referrals from Influitive pushed into either your Marketing Automation System or Salesforce as leads.
Important: Influitive will create a new lead regardless of whether or not that email address exists in Salesforce / your Marketing Automation System.
To configure lead pushing to Salesforce.com 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....
Important: If you are integrating with a Marketing Automation system, make sure you choose the section called "Push Referral app leads to <system>". There is an old section simply called "Push Referral Leads to <system>" (without the word App) that is deprecated and should NOT be used.
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 field to Lead - Advocate Hub Referral Source C. Before doing so, make sure that you have integrated with Salesforce 1.0 and installed the AppExchange package as per steps 2 & 3 of this help article. You will also need to add this field to the Lead record in Salesforce as per these instructions. 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. 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 the previous paragraph. 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.com 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.com or your MAS
Note: Starting with this step, you may need administrative privileges in Salesforce. We suggest contacting your Salesforce Admin to assist.
6.1 Login to Salesforce -> Setup -> Customize -> Leads -> Fields. Scroll down to Custom Fields section and click New.
Note: you must use exactly the parameters and capitalization indicated. The field is case sensitive.
- Text Field
- Field Label: Referral ID
- Length: 36
- Field Name: Referral_ID
6.3 Now repeat steps 6.1 and 6.2 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.
For example, for the Opportunity, you would go to Setup -> Customize -> Opportunity -> Fields -> scroll down to the Custom Fields section and click New.
6.4 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 created a Referral_ID in Step 6.3 . 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.3.
This can typically be accomplished by creating a new Lead field called Referral ID Copy (or something similar), of type Formula, and return type Text and then equating this Referral ID Copy field to be the same value as the Referral_ID field. See below for a sample. If you have further questions on this topic you may want to consult the Salesforce help article on formulas.
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 - Referral Id c
The "c" simply indicates it is a custom lead field.
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 Now login to Salesforce -> Setup -> Create -> Workflow & Approvals -> Workflow Rules. You're going to set up one Workflow Rule for each time you want a referral milestone to be updated.
8.3 Click Continue (if applicable) -> New Rule
8.4 Next, determine what object and status in Salesforce should trigger a milestone update in Influitive.
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
|Qualified||Lead Status is "Working - Contacted"||Lead|
|Won||Opportunity Status is "Closed - Won"||Opportunity|
|Lost||Opportunity Status is "Closed - Lost"||Opportunity|
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.
8.5 Now select the object that it is appropriate for your milestone.
8.6 Name your rule as you wish (we suggest something like "Influitive Referral Milestone Update - Qualified") and now select the criteria that should be met to correspond to your milestone update.
You should have two criteria:
- Whatever the criteria is for triggering the milestone update (e.g. Field: "Lead: Lead Status" "equals" "Working - Contacted."
- Referral_ID is not equal to blank
The second criteria will ensure this rule is not triggered for leads that were not from Influitive.
8.7 Click Save & Next. Make sure this field is visible/editable for any user that needs to create leads from Influitive referrals.
Now we want to add a workflow action to send Influitive an Outbound Message once your rule has been triggered.
9.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:
- 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 Referral_ID_c to Selected Fields
9.3 Click Save.
9.4 Go back to Salesforce -> Setup -> Create -> Workflow & Approvals -> Workflow Rules. Then make sure you Activate this workflow rule.
9.5 Now run a test - follow the steps here. 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.
9.6 Return to Step 9.1 and repeat this process for any further milestones you have to set up.
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):
- 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.
Note: Feedback does not NEED to be a formula, but in order to make this as automated as possible we suggest trying to implement some kind of Formula field so it does not manually need to be populated each time.
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.
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!).
11.6 Then open your Referrals Dashboard in Influitive to see if the milestone successfully updated to the correct milestone. If you've created Feedback in Salesforce (Optional, Section 10) then you'll also see a chat icon on your milestone.
If everything looks good, then you are all set! If not, see the troubleshooting steps below.
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:
- 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
- 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.