Developers Guide


Using the API

The Leadreporter API allows a user to insert and export leads from the system.

The Web Service User

In order to utilise our API functionality, an account administrators must first create a web service user in their system. This can be done in the same way as adding any other type of user:

  1. Click on the Settings link on the top menu
  2. Click on the Company/User Management link in the settings page.
  3. Click the Add User button.
  4. When creating the new user, make sure the User Type is set to Web Service.

If you do not already have an account with us but wish to integrate your application with ours please contact us at support@leadreporter.com and we will create a test account for you.

Methods available in the Leadreporter API

This section describes the Methods that are available to systems integrators.

getLogin(username,password) – returns a login object

This method is always the first method that you should call when using the web service. It takes the username and password of a valid Web Service user account and returns a Login Object.

The Login Object contains the following properties:

  • Status (SUCCESS OR FAIL)
  • Value (UNIQUE REFERENCE FOR THIS LOGIN)

An example of the values for a successful login would be:

  • Status -> SUCCESS
  • Value -> 9819-6665-4591-6319

An example of the values for an unsuccessful login would be:

  • Status -> FAILURE
  • Value -> 0000-0000-0000-0000

Once you have a valid login object, you can use it to pass as an input to the other exposed methods. Without a valid successful login object no other method can be used. Please Note: Each successful login will create a session that is valid for 30 minutes. You can pass the returned login object to as many of the web service functions you wish to use before its time limit expires, after that you will need to create a new login object by calling this method again.

getLeadArray(Login Object) – returns an array of field objects

Before you can use the web service to add a lead you must download this array, which contains an object for each field that you can upload data to. Each of the field objects has the following properties:

  • Datatype (TEXT, INT,FLOAT,DATE,YESNO,SELECT,URL,EMAIL ) ...please see the field types section
  • Fieldname (The name given to the field in Leadreporter)
  • Options (If the value is an Enumerated Type, the possible values are listed in a comma separated list)
  • Value (This will initially be empty)

In order to insert a lead into Leadreporter, you must populate the Value property of the Field Objects in the array that was returned by the getLeadArray method. If you are adding a value to a field whose possible values are derived from an enumerated type, please make sure that you check that your value matches one of these values. Once you have populated the array of field objects you are ready to upload your lead into the Leadreporter system.

insertLead(Login Object, Array of Field Objects) – returns a string

If you will be using the distribution engine to distribute leads to your staff use the insertDeLead method instead of the insertLead method. It Takes the same inputs and returns the same values as insertLead.

Now that you have a Login Object and a Array of Field Objects with populated Value properties, you can use the insertLead method to upload your lead to the system. The insertLead method takes a Login Object and Array of Field Objects as inputs. It returns a String that contains the result of the attempted record insert.

A successfully inserted lead will return the String: SUCCESSFULLY INSERTED

A lead that is not successfully inserted will return one of the following Strings:

  • INSERT FAILED
  • 1 OR MORE OPTION FIELDS NOT CORRECT
  • SESSION INVALID
  • LOGIN INVALID

getFieldNames(Login Object) – returns an array of strings contains field names

This method returns a list of field names in the system. This is designed to be used in conjunction with the exportLead method. The elements of this array correspond as field names to the values contained in an Export Array.

getExportLeadIds(Login Object, Stage, Start Date, End Date ) – returns an array of Lead IDs as integers.

This method takes a Login Object, a Lead Stage, a Start Date and an End Date. The Lead Stage is the stage in the Leadreporter process that you wish to export records from and should be entered as an integer. The Start Date and End Date are set as strings with the format: ‘YYYY-MM-DD HH:mm:ss’ where:

  • YYYY = the year displayed as a 4 digit integer
  • MM = the month displayed as a 2 digit integer
  • DD = the day displayed as a 2 digit integer
  • HH = the hour displayed as a 2 digit integer in the 24 hour format
  • mm = the minutes as a 2 digit integer
  • ss = the seconds as a 2 digit integer

The start date and end date specify a time period which will include leads in the export whose upload date falls between these values. Below is an example of calling this method:

getExportLeadIds($login,3,'2010-01-31 00:00:00','2010-01-31 23:59:59');

The above example will produce a list of lead Ids that are at the third stage in the leadreporter system and who were inserted on the 31st of January 2010. Now that you have an array of Lead IDs that match your export criteria, you can export each lead by using the exportLead method.

exportLead(Login Object, Lead ID) – returns an array of strings containing the field values for that record.

The exportLead method allows you to export a lead from the system. It takes a valid login object and a valid Lead ID as input and returns an array containing the values for the fields. The order of these values corresponds to the result of the getFieldNames method.

Examples

This section provides some PHP examples of using the methods available in this web service. All examples are written in PHP 5.1.x. If you are using another programming language, please consult its documentation on consuming web services.

Example 1 - Inserting a lead

 
<?php
// Set debug level. Set to true for a detailed output.
$debug = false;
 
// Create the client from the WSDL file
$soapclient = new SoapClient("https://app.leadreporter.com/ws/service.php?class=leadManager&wsdl");
 
// Get a Login Object
$login = $soapclient->getLogin("yourwebserviceuser","password");
// print the contents of the Login Object
if ($debug == true) {
    print_r($result);
}
 
// Create an Array of Field Objects
$lead = $soapclient->getLeadArray($login);
if ($debug == true) {
    print_r($lead);
}
 
// Create a lead in an array, each array element is an array of (Fieldname,Value)
$newlead[0][0] = "Firstname";
$newlead[0][1] = "Joe";
$newlead[1][0] = "Surname";
$newlead[1][1] = "Bloggs";
$newlead[2][0] = "Email";
$newlead[2][1] = "joe.bloggs@example.com";
$newlead[3][0] = "Lead Source";
$newlead[3][1] = "Website";
$newlead[4][0] = "Lead Type";
$newlead[4][1] = "Product Enquiry";
 
// Loop through the array of Field Objects and populate it with the values in our example lead
$lead_length = count($lead);
$newlead_length = count($newlead);
for($i=0;$i<$lead_length;$i++){
    for($j=0;$j<$newlead_length;$j++){
        if ($lead[$i]->Fieldname == $newlead[$j][0]){
            $lead[$i]->Value = $newlead[$j][1];
        }
    }        
}
 
if ($debug == true) {
    print_r($lead);
}
 
// Insert the lead into the Leadreporter system 
$test = $soapclient->insertLead($login,$lead);
 
// Print out the result of the insertion
print_r($test);
?>
 

Example 2 - Exporting a lead

 
<?php
// Set debug level. Set to true for a detailed output.
$debug = false;
 
// Create the client from the WSDL file
$soapclient = new SoapClient("https://app.leadreporter.com/ws/service.php?class=leadManager&wsdl");
 
// Get a Login Object
$login = $soapclient->getLogin("yourwebserviceuser","password");
if ($debug == true) {
    print_r($login);
}
 
// Get a list of Lead IDs 
$leadidlist = $soapclient->getExportLeadIds($login,3,'2010-01-31 00:00:00','2010-01-31 23:59:59');
if ($debug == true) {
    print_r($leadidlist);
}
 
// Get the array of field names
$fieldnames = $soapclient->getFieldNames($login);
if ($debug == true) {
    print_r($fieldnames);
}
 
// Loop through the Ids an export each of the leads 
$leadcount = count($leadidlist);
for($i=0;$i<$leadcount;$i++){
    $insertresult = $soapclient->exportLead($login,$leadidlist[$i]);
    $exportedleads[$i] = $insertresult;    
}
 
// Print the array of exported leads
print_r($exportedleads);
?>
 

Support

Please contact support@leadreporter.com if you require any assistance in using the API.

Lead Reporter Screenshots

See how our lead management software can help you manage your sales leads. Get a no obligation free trial today.