Website Integration: PHP

This document provides guidance for integrating a PHP website with the MyMedLeads Web API. It outlines the various properties and attributes of a Lead, as well as how to populate these attributes and send them to MyMedLeads.

Intended Audience
This document is designed for PHP Web Developers. It assumes that you are familiar with PHP and currently manage the website.

Requirements
To get started, you will need a few items from our team. We have prepared a zip file containing some JavaScript and a PHP file that includes a utility class. This class will facilitate communication between your website and our API, and its usage is explained below.

Additionally, you will need a LeadSource Key to represent the LeadSource of your website. The LeadSource may differ from page to page and from form to form. Your team may need to implement logic to dynamically determine which LeadSource Key to use based on your specific requirements.

Optionally, if you wish to associate Procedures of Interest with the leads you generate, you will also need a list of Procedures from your MyMedLeads account.

High Level Steps of Integrating with the MyMedLeads API

The following instructions guide you through the high-level steps of integrating a PHP website with MyMedLeads. It will also explain how to communicate data to the MyMedLeads API. Two specific areas require special attention: passing in procedure data and tracking referring URLs and keywords. Please note that most of the logic is contained in the `mmlclient.php` file, which is available upon request. This file includes the `MMLClient`, which manages all communications between your site and the MyMedLeads API.

LeadSource Keys – Identifying the LeadSource
The LeadSource Key is a GUID-like string used to identify the account and the Lead Source associated with an individual form. MyMedLeads accounts can have multiple LeadSources, and a single website may utilize more than one LeadSource. Clients can create and update LeadSources within their MyMedLeads account by navigating to: Preferences -> Edit LeadSources. On this screen, a list of LeadSources is displayed, with each row featuring a green key that reveals the LeadSourceKey.

Lead Data
The MyMedLeads `MMLClient` handles all direct communications. Your logic will need to populate the `MMLClient` with the details of a single lead (e.g., first name, last name, phone number, etc.). Most web forms request specific information, such as the “Best Time to Call.” For these types of fields, the `MMLClient` offers a method called `addCustomValue()`. This method takes a value and a label (a string that describes the value). This information is included in the lead’s comments and appears as: “Best Time to Call: Mornings.” Refer to Diagram 1.0 for details on lead properties.

Passing in Procedure Data to MyMedLeads
It is possible to specify the type of procedure the lead is interested in. Associating procedures with leads allows our system to qualify leads for specific marketing campaigns within MyMedLeads. To achieve this, you will need a list of procedures from the MyMedLeads account you are integrating with. When a new mutual client signs up, the MyMedLeads team can provide a list of procedure IDs and names for that client. Please refer to the relevant page for more details on how to map procedures.

Tracking Referring URLs and Keywords
Referring URLs and keywords are tracked using a small JavaScript library mentioned in the integration steps below. This file captures the URL that the visitor accessed just before entering your site (typically from a search engine or directory site). We store this information in a cookie, which is later referenced when posting the lead. Therefore, it is crucial to include the JavaScript on all pages of the website.

Integration Process

When it is determined that the API is the right integration model, then the MyMedLeads team will share PHP code with your team to use to integrate the website.  Normally, the MyMedLeads team will prepare a .php file with different functions called SendToMML().  Each of these functions will have a signature that matches the fields within that Form.  Our team will provide explicit instructions on how to use the code and functions. By following the below instructions, your team can integrate a web form without the SendToMML() functions.  The below steps will demonstrate the steps that are necessary to integrate a web form with the MyMedLeads Web API.

1. Copy the mmlclient.php up to your server and reference it correctly
2. The javascript will need to be placed on all pages of the website, not just the pages with Web Forms.  You can find the javascript within the shared zip file.
3. When the form posts to the server and after all of the validation logic and email notifications are sent and completed, then your logic will need to instantiate the MMLClient, using the Transaction Key for the appropriate Lead Source.
4. Then call addValue on the MMLClient for each field on your form
5. For fields that do not have a matching LeadProperty, your logic can use the addCustomValue() or addCustomMapping() to send in these values.   These two functions will append the values to the comments of the Lead, and the functions do ask for a ‘label’ to help identify what the information is.
6. using the function PostLead() will communicate all of the populated  data to MyMedleads.
7. the result of a PostLead() call will be a numeric number, which is the LeadId within MyMedLeads or zero (if failure), followed by a pipe ‘|’ then a Success/Warning message. Example: 1838332|Success.

The below sections demonstrate how to organize and structure your php to easily integrate a web form with MyMedLeads.   The two example below shows an advanced form that asks for several fields, including ProcedureOfInterest.   You and your team can use this as a good working example.

PHP WebSite Example

<?php 
  require_once('mmlclient.php'); 
  if (strtolower($_SERVER['REQUEST_METHOD'])=="post") 
  {
    $mml = new MMLClient("LeadSourceKey");
    $mml->addValue($_POST['txtFirstName'], MML_PARAM_FIRSTNAME); 
    $mml->addValue($_POST['txtLastName'], MML_PARAM_LASTNAME); 
    $mml->addValue($_POST['txtPhone'], MML_PARAM_PHONE); 
    $mml->addValue($_POST['txtEmailAddress'], MML_PARAM_EMAILADDRESS); 
    $mml->PostLead(); 
  } 
?>

WordPress ContactForm7 Example

Our integration team will provide you an installable Plugin that includes the below code.  The code below is a snippet of what is within the .zip file.

...
// $formId - provided by the WordPress/ContactForm7 logic
// $formdata[] - provided by WordPress/ContactForm7 logic
// $LeadSourceKey - retrieve from MyMedLeads Account
switch ((string)$formId) {
  case "1982" : // Contact Us Form
    $mml = new MMLClient($LeadSourceKey);
    $mml->addValue($formdata["name"], MML_PARAM_FULLNAME);
    $mml->addValue($formdata["email"], MML_PARAM_EMAILADDRESS);
    $mml->addValue($formdata["phone"], MML_PARAM_PHONE);
    $mml->addValue('22', MML_PARAM_PROCEDUREDATA);// botox
    $mml->PostLead();
  break;
  default:
    // do not send to MyMedLeads
  break;
}
...

WordPress GravityForm Example

Our integration team will provide you an installable Plugin that includes the below code.  The code below is a snippet of what is within the .zip file.

...
// $form[] - provided by WordPress/GravityForm logic
// $entry[] - provided via WordPress/GravityForm logic
// $LeadSourceKey - retrieve from MyMedLeads Account
switch ($form['id']) {
  case '3' : // 	Sidebar Form
    $mml = new MMLClient($LeadSourceKey);
    $mml->addValue($entry['1'], MML_PARAM_FIRSTNAME);
    $mml->addValue($entry['2'], MML_PARAM_LASTNAME);
    $mml->addValue($entry['3'], MML_PARAM_PHONE2);
    $mml->addValue($entry['4'], MML_PARAM_EMAILADDRESS);
    $mml->addValue($entry['5'], MML_PARAM_COMMENTS);
    $mml->addValue('true', MML_PARAM_CAPTCHA);
    $mml->PostLead();
  break;
  default:
    // do not send to MyMedLeads
  break;
}
...

Proprietary Procedure IDs are Required

MyMedLeads allows clients to have a list of Procedures that are custom to their practice. Most clients have the same basic set of procedures within their respected fields, however we do allow for Custom Procedures ex: ‘Vampire Facelift’. Clients also use our Procedures to ‘tag’ a Lead to possibly qualify him/her into a Marketing Campaign.
Because we allow custom procedures per client, the MMLClient expects the proprietary ProcedureID within MyMedLeads. When your visitor selects ‘Botox’, then our API will expect to receive our ID of ’22’. For this reason, it is required that your logic have access to this data.

Please Note: While leads can be associated to multiple ProcedureOfInterests, it is strongly recommended to only communicate a single ProcedureOfInterest. This is specifically for our Marketing Campaigns; being qualified for multiple Procedure Campaigns will trigger a Default Campaign rather than a specific Campaign on Botox (as an example).

The below tables describe what type of data that can be communicated to MyMedLeads, via the Web API.  There are native properties that you can set using the addValue() function within the MMLClient, and it is also possible to send in custom values. Below is a list of the properties you can directly populate within MyMedLeads.

First, Last and/or Full Name – The full name of the Lead.  The name is broken up on the first space to make the first and last name

Email Address – The email address of the Lead

Home Phone – The phone number of the Lead

Mobile Phone – The mobile phone number of the Lead

Street Address – The street address of the Lead

City – The city of the Lead

StateName – The state that the Lead resides in

PostalCode – The postal code of the Lead

Gender – The gender of the Lead

Date of Birth – The date of birth of the Lead

Comments – The comments or message that the Lead posted.  This field is used to house any questions and answers on the form that does not have a direct property within MyMedLeads.  If the form asks “How did you hear about us?” or “What is the best time to contact you?”, these properties do not exist on a Lead within MyMedLeads, so this data will be appended to the Comments of the Lead.

Preferred Doctor – The preferred Doctor of the Lead

Preferred Location – The preferred Location of the Lead

Procedure of Interest – A list of procedures that the Lead is interested in