Introduction to Lead Qualification API

Digital lead generation campaigns on your website, social media or email marketing produce large lists of contact information that are often incorrect. Cleaning this database by calling phone numbers one by one is a time consuming task.

Putting these phone numbers through the Lucep Lead Qualification system automates and speeds up this repetitive manual task. Furthermore, Lucep’s APIs make it easy for you to integrate with your existing systems.

Workflow and configuration

The first step in qualification is validating the correctness of the telephone number. Beyond basic format checking, an actual outbound dial attempt is required to verify that the number is active.

The phone number may or may not be live, or in certain circumstances may be temporarily unavailable. The most reliable way to check this is to perform an outbound call to the number.

If the phone number exists, the following outcomes are possible:

1. The target prospect is contacted and confirms their interest, resulting in the lead being categorised as qualified
2. The prospect elects to opt-out from being contacted, in which case the lead is categorised as rejected.
3. The prospect ignores all attempts to contact them, or if it is not possible to determine if the phone number exists or is temporarily unavailable. In this circumstance the system will redial the contact a configured number of times before desisting and marking the lead as rejected

After Call Validation

If any of the following occur:

1. Attempts to call the prospect fail
2. The prospect hangs up after taking the call
3. The prospect ignores all the offered options during the call to opt-out or qualify their number

then the Lucep Lead Qualification system will trigger the following methods simultaneously to contact the target prospect:

1. E-mail: If this option has been enabled, and the contact information includes an email address, then an email will be sent by the Lucep system to the given email address. The content of the mail can replicate the options offered by the IVR, with the aim of confirming the prospect’s interest in the services offered, and to allow the recipient to opt-out from the qualification campaign if they so desire.
2. SMS: If this option has been enabled, the system will send a transactional SMS to the phone number. The message includes a link to a webpage that has the same content as the email indicated above. The message should comply to regular SMS constraints of 160 characters per message.
3. WhatsApp: If this option has been enabled, the Whatsapp message sent out to the same phone number can be similar to the SMS, with a link to a webpage that drives the prospect to the available options. Alternatively, Lucep can supply a WhatsApp chatbot that can take the prospect through the qualification process.

The e-mail, SMS and WhatsApp methods can be enabled or disabled by Lucep depending on your requirements.

The sequence and number of contact events is configurable based on campaign requirements.

Simultaneous multiple campaigns using the same account

All campaigns are linked to a target service under which all the submitted leads are placed. This helps to group the sales team members chosen to receive the leads after being qualified by the Lucep Lead Qualification System.

Different campaigns (linked to the same account) may use their own individual set of IVR call flow and email, SMS and WhatsApp message templates, or make use of the account’s generic configuration. Lucep can help you configure this as required.

Outside working hours

If the Lucep Lead Qualification System is being integrated into a website for example, then many users who request a callback may submit the form Outside working hours. In this situation, the IVR calls will not be triggered immediately. Instead, the system will start off with the e-mail, SMS and/or WhatsApp messaging options (if one or more have been set up), with the goal of encouraging the prospect to agree to a call back during the very next working hour slot.

The same working / out of hours configuration can be shared across different campaigns for the same account. Lucep can help you configure this as required.

Using the API

Submit the data of your prospect using the API described at the "Submit Lead for Clearance" API subsection.

Rate limits

The "Submit Lead for Clearance" API limits the call requests per IP per minute. If you are planning to make a lot of requests, it is required to create an access token. The a new access token is need per submission. You will need to use the "Create one-time-consumable token" API to create this access token. Reference the subsection for further details.

Create one-time-consumable token

This is an API that is part of the Lead Qualification API. Use this API first to create a one-time consumable token, then use "Submit Lead for Clearance" API to actually submit the data of your prospect and verify if the data belongs to an actual person, or if it is incorrect. To use this API, you will need a API key. Please check with your account manager for a valid API key, if you do not have one.

curl https://my.lucep.com/api/ \
    --data  'action=token_create&account_key=mydemo&for_action=lead_submit&apikey=ABC...xyz'
  

  // This code requires jQuery
  
  const URL = "https://my.lucep.com/api/";
  const ACCOUNT_KEY = "mydemo";
  const API_KEY = "ABC...yxz";
  var tokenCreateRequest = {
      action: "token_create",
      account_key: ACCOUNT_KEY,
      for_action: "lead_submit",
      apikey: API_KEY,
  };
  $.post(URL,tokenCreateRequest).done(function(tokenCreateResponse) {
      console.log("tokenCreateResponse = ",tokenCreateResponse);
      if (tokenCreateResponse.status == "ok") {
          // Submit lead
      } else {
          alert("Got error " + tokenCreateResponse.status);
      }
  })
  .fail(function(jqXHR, textStatus, errorThrown) {
      console.log("fail token creation jqXHR = ",jqXHR);
      console.log("fail token creation textStatus = ",textStatus);
      console.log("fail token creation errorThrown = ",errorThrown);
      alert("Got network error?");
  });
  
  

<?php
  
  $url = "https://my.lucep.com/api/";
  $context = [
      'http'=> [
          'method' => 'POST',
          'ignore_errors' => true,
          'content' => $q = http_build_query([
              'account_key' => "mydemo",
              'action' => "token_create",
              'for_action' => 'lead_submit',
              'apikey' => 'ABC...yxz',
          ]),
          'header' => "Content-Length:".strlen($q)."\r\nContent-Type: application/x-www-form-urlencoded\r\n",
      ],
  ];
  $content = file_get_contents($url,false,stream_context_create($context));
  $retArr = json_decode($content,true);
  if ($retArr && $retArr['status'] == 'ok') {
      // Success
  } else {
      // Error
  }
  
  

HTTP Request

POST https://my.lucep.com/api/

Request Body Parameters

Response Body Parameters

Submit Lead for Clearance

This is an API that is part of the Lead Qualification API. You need to acquire a valid one-time consumable token that calls the "Create one-time-consumable token" API before calling the Submit Lead for Clearance API. You are going to need to provide customer_id and interaction_id values afterwards for tracking the prospect's actions when using Lucep app. Generate these values as random strings of hexadecimal values, with maximum length of 40 characters. Associate a customized data set with this prospect. Stringify it using JSON format and assign the value to the payload parameter. service_id is unique to your campaign, and the value should be provided by your account manager. You can provide a service_name as you see fit, but we recommend that you assign a related value.

curl https://my.lucep.com/api/ \
    --data  'action=lead_submit&account_key=mydemo&auth=123...def&name=John+Smith&phone_number=15551234&[email protected]&service_id=1&service_name=test'
  

  // This code requires jQuery
  
  const URL = "https://my.lucep.com/api/";
  const ACCOUNT_KEY = "mydemo";
  const API_KEY = "ABC...yxz";
  var leadCreateRequest = {
      action: "lead_submit", 
      customer_id: new Date().getTime().toString(16).padStart(40,'0'),
      interaction_id: new Date().getTime().toString(16).padStart(40,'0'),
      langcode: "eng",
      location: "Singapore",
      name: "John Smith",
      phone_number: "15551234",
      email: "[email protected]",
      service_id: 1,
      service_name: "test",
      auth: tokenCreateResponse.token,
  };
  $.post(URL,leadCreateRequest).done(function(leadSubmitResponse) {
      console.log("leadSubmitResponse = ",leadSubmitResponse);
      if (leadSubmitResponse.status == "ok") {
          // Submit lead
      } else {
          alert("Got error " + leadSubmitResponse.status);
      }
  })
  .fail(function(jqXHR, textStatus, errorThrown) {
      console.log("fail lead submit jqXHR = ",jqXHR);
      console.log("fail lead submit textStatus = ",textStatus);
      console.log("fail lead submit errorThrown = ",errorThrown);
      alert("Got network error?");
  });
  
  

<?php
  
  $url = "https://my.lucep.com/api/";
  $context = [
      'http'=> [
          'method' => 'POST',
          'ignore_errors' => true,
          'content' => $q = http_build_query([
              'auth' => "012...def",
              'account_key' => "myteam",
              'action' => "lead_submit",
              'name' => "John Smith",
              'phone_number' => "15551234",
              'service_id' => 1,
              'service_name' => "Testing from web",
              'customer_id' => "12345678",
              'interaction_id' => "12345678",
              'email' => "[email protected]",
          ]),
          'header' => "Content-Length:".strlen($q)."\r\nContent-Type: application/x-www-form-urlencoded\r\n",
      ],
  ];
  $content = file_get_contents($url,false,stream_context_create($context));
  $retArr = json_decode($content,true);
  if ($retArr && $retArr['status'] == 'ok') {
      // Success
  } else {
      // Error
  }
  
  

HTTP Request

POST https://my.lucep.com/api/

Request Body Parameters

Response Body Parameters

Lucep Callback API

The Lucep Callback API Library is designed to allow any form on a website, or any specific interaction, to send leads directly to sales people so that customers can be converted faster. This could be from anything to with an enquiry form being completed, to a new signup being completed prompting the team to welcome the new registrant, all the way through to a registered user abandoning a cart.

Whatever the circumstance is that you believe requires immediate personalised attention, the Lucep library facilitates that exercise by driving immediate engagement from your team.

Loading the library

The JavaScript library can be loaded in two ways, and which one you choose will depend on your site and expected user interaction.

Dynamic loading (load speed friendly / default)

The following snippet will load the library as a dynamic script on the page; this is typically used when the primary focus is related to the speed of the page loading and is usually considered best practice. The reason why this helps perceived page load speed is because it is downloaded in parallel with all other page content – and does not prevent other scripts or objects being loaded before it. Where the functionality of the page does not depend on the library being immediately available, this is usually a good option.

(function (l,u,c,e,p){ ... })(a,b,c,d,e);

The callback is fired immediately after the browser has finished downloading the script (not necessarily completely loaded it) and is an opportune place to either fire any other dependent scripts, or bind buttons with events.

Included in the header (easiest)

Including the Lucep JS library in the header guarantees its availability on the page to every script called after it, but has the downside of blocking page load until it is downloaded. The impact of this is usually only seen once, and it is cached by the browser for subsequent loads.

To include the script in the page header simply add this between the <head> </head> tags:

<script type='text/javascript' src='https://cdn.lucep.com/js/L.SalesGorilla.stable.latest.min.js'></script>

A note on build channels

Two channels are actively maintained, and they are referred to as follows: Stable The stable channel contains the most thoroughly tested and reliable version of the library. It is updated more slowly, but only updated when backward compatibility is assured and has been tested as a working library. The stable library is available from

https://cdn.lucep.com/js/L.SalesGorilla.stable.latest.min.js

The bleeding channel contains builds that can be considered as being in the middle of development. Cool new features are added to this library on an ad hoc basis, but they may not completely work, may not even be documented, and almost always run the risk of breaking other functionality – some may never make it over to the stable channel. It is really only recommended for development purposes and to get a peek under the hood of what is coming next The bleeding library is available from:

https://cdn.lucep.com/js/L.SalesGorilla.bleeding.latest.min.js

Checking if the library is loaded

Depending on how the library is included, it may be necessary for you to check if the library is available before performing any actions with it.

Listening for the library announcement

The Lucep library will announce it is available by firing the event lucep-library-ready on the document, so it is possible to create an event listener for this:

document.addEventListener("lucep-library-ready", function(){ 
        //the library is ready, do something here 
  }, false);
  

NOTE: This is not compatible with browsers IE9 and before Please check compatibility with your target browsers.

Checking for object existence

Checking if $lucep is available as an object is a simple and effective way to validate the library is available for use

if ($lucep) {
       //the library is available, do something
  }
  

A combined approach to work with the library

A reliable way to work with the library is to combine these two ways of checking for the availability of the library:

if ($lucep){
       //launch your custom event
   } else {
       document.addEventListener("lucep-library-ready", function(){ 
        //the library is ready, do something here 
  }, false);
  

Initialising the library

The Lucep library requires to be initialised before it can be used, and it can be initialised by providing only the account name with which it should be used.

$lucep.init( { domain: YOUR-DOMAIN-HERE } );

The init function can be called repeatedly without any adverse impact, as only the first call is processed. Once the init method is fired, all of the other library methods can be used. It is recommended that the init function is fired as early as possible as this will prevent long waiting times for other functions to complete.

$lucep.init ( params )

This method can be invoked multiple times – however only the variables passed in the first call are considered. All other subsequent calls are ignored. params should be a JavaScript object with the following properties:

$lucep.raise_lead ( params )

Immediately raises a lead to the appropriate team based on the service_id supplied. Notifications are pushed directly to the relevant users as defined in the Lucep console.

$lucep.send_intelligence ( params )

Sending intelligence instructs the server to maintain a record of a specific significant event with this particular customer. This event is communicated to the sales person when a lead is raised by user in question. This could be anything from a customer scrolling past a particular point on a page, to the customer viewing a specific image. The general guidance is to send events that will be relevant, and helpful, the person that is going to be reviewing the lead ahead of engaging with the customer.

NOTE: It is important to recognise that personally identifiable information should not be sent as data in this method

params should be a JavaScript object with the following properties:

$lucep.put_data ( params )

This method stores data in the browser for retrieval between sessions. It allows for custom identifiers or references to be placed within browser storage using your custom key references. The library will detect if the browser supports WebStorage and use that if available, else it will fall back to Cookies.

This method can be called any number of times, it does not return any data. If the method is called multiple times with the same key, it will overwrite the data stored by the previous call. params should be a JavaScript object with the following properties:

$lucep.get_data ( params )

This method retrieves data that has been stored using $lucep.put_data method. It returns the value associated with the key as a result of the function call. params should be a JavaScript object with the following properties:

The method will then return the value string that was previously associated with the key (if any)

$lucep.get_kiosk_details ( params )

Once initialisation has completed, the details of the kiosk can be passed to a callback so that necessary actions can be taken to render it or incorporate it into the page as needed. This function can be called as many times as needed, and as soon as the kiosk is available, all the callbacks will be fired sequentially. params should be a JavaScript object with the following properties:

When the callback is triggered, an object describing the kiosk properties will be supplied. Kiosk properties can be customised as needed on the Lucep console – this means that a kiosk can return as many, or as few, properties as needed for your implementation. An example of how this object can be structured is as follows:

The extra_fields property

Extra fields is a kiosk configuration property that is used to instruct the webpage that some additional data is required in order for the submission to be useful to the person processing the customer’s request. Enforcement and use of this is down to your implementation, and it is not validated by the Lucep library or servers. In most circumstances, the accompanying data is fired as additional_info when a lead is raised – but this must be implemented by you.

Within the dom-property-id another object is nested that contains additional descriptors:

$lucep.get_ticket_status

Performs a check on the last known lead processing status. Returns synchronously with an object describing the state. The object looks as follows

$lucep.create_profile ( params )

This method should not need to be called on a regular basis.

create_profile purges any record of the existing customer profile from the browser, and requests for the server to create an entirely one. This forces references to any previous intelligence or leads to be lost.

As customer behaviour profile identifiers are securely generated, and correlating them with leads is a one-way process this process can not be undone, and once executed, past customer information is only available in an anonymised aggregated format.

params should be a JavaScript object with the following properties:

If you have any queries or suggestions or complaints, please reach out to us at this email address: [email protected]

Status responses

Sometimes a "msg" parameter will be returned to help to understand details about why a request has failed or got error.