Setting Up Incoming Web Leads in Vanillasoft

Before setting up Incoming Web Leads, confirm the following:

• You have Admin access in Vanillasoft with the Incoming Web Leads permission enabled. If you do not see this feature, contact Vanillasoft Support to have it enabled on your account.

  ---

• Know which fields your provider maps to. You will need to configure at least one field mapping when creating a web lead. Have this information from your third-party provider ready before you start.

  ---

• Existing web leads are unaffected. If you already have Incoming Web Leads configured, they continue to work without any changes. You can upgrade them to key authentication at any time. See Upgrading a Legacy Web Lead to Key Authentication below.

  ---

• Note: Email-based web lead integration (receiving leads via a dedicated XML email address) continues to work for existing customers who are already using it. This option is not available for new web lead configurations. If you need to set up email-based integration, contact Vanillasoft Support.

This section walks you through creating a new Incoming Web Lead. The posting URL and verification key are generated automatically when you save for the first time.

1. Log in to Vanillasoft as an Admin.
   

   • If you are logged in as a Caller, switch to Admin from the top menu.

   ---

2. Open the Integration menu and select Incoming Web Leads.
   

   ---

3. Click Add Incoming Web Lead.
   

   ---

4. Fill in the web lead details.
   

   • Name: Required. A descriptive name for this web lead configuration. 

     ---

   • Description: Optional. A brief description for internal reference. 

     ---

   • Email on Success: Optional. An email address to notify when a lead is successfully received. 

     ---

   • Email on Error: Optional. An email address to notify if a submission fails. 

     ---

   • Return URL: Optional. A URL your provider can redirect visitors to after a successful submission.

   ---

5. In the Field Mappings section, add a mapping for each contact field your provider will send.
   

   • Click Add Field.

     ---

   • Open the Vanillasoft Field drop-down and select an existing Vanillasoft field to map to a Web Form field.

     ---

   • In the Web Form Field, enter the exact name of the incoming field text box.

     ---

   • In the Default Value field, enter a fallback value to use when the incoming submission is blank.

     • If the submission includes data in that field, the submitted value is used instead. To always apply the same value regardless of what the provider sends, leave the Web Form Field blank and enter only the Default Value. This is commonly used to automatically tag contacts with a Lead Source. Example, select Lead Source from the Vanillasoft Field drop-down, leave Web Form Field empty, and enter the lead source's name in Default Value to list which lead source each contact came from. This is one example, but can be used for any configuration that fits your needs.

     ---

   • Repeat for each additional field your provider will send.

   ---

6. Click Save.
   

   • After saving, the Posting URL Web Lead Security section expands automatically and displays the verification key along with two authentication options. The key and URLs are read-only and cannot be manually changed.

   ---

7. Review the two authentication options and share the relevant details with your third-party provider.
   

   • Option 1 (Recommended): Send the verification key as a request header. Your provider sends the posting URL and includes the verification key in the HTTP request header. The key is not visible in the URL, making this the most secure method. 

     ---

   • Option 2: Append the verification key to the posting URL. The key is added to the end of the posting URL. Use this option if your provider cannot send a key in the request header. Both options work simultaneously, so your provider can use either one.

   ---

8. Use the Copy buttons next to each field to copy the posting URL, verification key, or full URL. You can also click Download to export all posting details as a PDF to share with your provider.
   

Existing web leads continue to work without a verification key. When you are ready to upgrade a legacy web lead to key authentication, follow these steps. Update your third-party provider with the new posting details before saving to avoid any interruption to your integration.

1. Log in to Vanillasoft as an Admin.
   

   • If you are logged in as a Caller, switch to Admin from the top menu.

   ---

2. Open the Integration menu and select Incoming Web Leads.
   

   ---

3. Click the Edit icon on the web lead you want to upgrade.
   

   • The Posting URL Web Lead Security section appears with Legacy Web Lead Posting selected by default. Your existing integration is unchanged at this point. Simply viewing this section does not activate or change anything.

   ---

4. Select Key Authenticated Web Lead Posting (Recommended).
   

   • Option 1 and Option 2 appear with the newly generated verification key and posting URLs. All fields are read-only.

   ---

5. Copy the new posting details and update your third-party provider before saving.
   

   • Use the Copy buttons next to each field or click Download to export the details as a PDF. 

     ---

   • Note: Once you save with key authentication enabled, the web lead will reject submissions that do not include the correct key. Make sure your provider is updated and ready before you save.

   ---

6. Once your provider is ready, click Save and confirm the activation prompt.
   

   • A confirmation message will appear reminding you that your existing integration may stop working until your provider is updated. Confirm to proceed. 

     ---

   • Note: To revert to legacy posting at any time, open the web lead, select Legacy Web Lead Posting, and click Save. A warning will confirm the change. After saving, the web lead will accept all requests regardless of whether a key is included.

The Generate Example Form feature creates a sample HTML form pre-configured with your web lead's posting URL and verification key. You can copy this HTML and share it with your provider as a starting point for their integration.

1. Log in to Vanillasoft as an Admin.
   

   • If you are logged in as a Caller, switch to Admin from the top menu.

   ---

2. Open the Integration menu and select Incoming Web Leads.
   

   ---

3. Click the Edit icon on the web lead you want to generate a form for.
   

   ---

4. Click Generate Example Form at the top right.
   

   • The example form opens as a popup within the same page.

   ---

5. Click Copy HTML Code to copy the generated form HTML and share it with your provider.
   

   • The generated HTML includes the posting URL with the verification key already appended. A live preview of the form is shown in the lower part of the popup. 

     ---

   • Note: This form is a starting point. Your provider may need to adjust the field names or structure to match their integration requirements.

Copying a Web Lead

When you copy an existing web lead, a brand new verification key and web lead ID are always generated for the copy. What authentication options appear when you edit the copy depends on the original:

How Requests Are Processed

This table shows how Vanillasoft handles incoming submissions depending on the web lead's security setting and whether a key is included: