NAV

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

Parameter Type Required Default Description
action string yes Must be "lead_create"
account_key string yes Account Key or “team name” which will receive the information for the new lead
apikey string yes Free text about comments that the user who is requesting for callback may want to give to customer support teller who is going to call this customer
for_action string yes Specify what API action is going to be used for (for example, "lead_submit").

Response Body Parameters

Parameter Type Required Default Description
status string yes "ok" if the operation successfully did run.
token string yes The token to be consumed by the Callback operations.

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

Parameter Type Required Default Description
action string yes Must be "lead_submit"
account_key string yes Account Key or "team name" which will receive the information for the new lead
auth string yes This is the token generated by the "token_create" API that will be consumed on this call, whether the submission succeeds or not
comments string no null Free text about comments that the user who is requesting for callback may want to give to sales team member who gets the notification to call this customer
custom_data string no Empty object If given, it needs to be previously encoded with JSON format
customer_id string yes Use any hexadecimal string to identify the customer across multiple interactions
email string no The email of the customer who is requesting the callback
interaction_id string yes Use any hexadecimal string to identify the submission of this customer as different from previous usage of this API
kiosk_id number no null If given, it is for identifying the kiosk from where the lead has been risen
langcode string no null 3 characters lowercase string in ISO 639-2 Code
location string no null Geolocation. If given, it will be curated as stated above.
name string no null Customer name. If given, it will be curated as stated above.
nps integer no null Used for Net Promoter Scoring
payload string no Empty object If given, it needs to be previously encoded with JSON format. Use this to associate any values and details that your integrating system may need. This is usually used to extend the information that a lead carries by default. For example, if you are integrating this with a car renting website, you could use this payload to associate a car model or a specific car from the list of cars of your website.
phone_number string yes This field is curated before being recorded in the system. For example, special characters from UTF8 that mimic dashes (-) and their ASCII counterpart are removed. Format is also checked against the regular expression /^[a-zA-Z0-9 ().-+#,]{2,30}$/
service_id number yes The service identified where the lead will be registered, and also identifies the clearance campaign
service_name string no null If given, it will be curated as stated above.
sharecontent_id string no null If giver, the lead will be linked with the social sharing link created using the Lucep app identified by the value of this field.

Response Body Parameters

Parameter Type Required Default Description
status string yes "ok" if the operation successfully did run
validation_id numeric yes The ID representing this submission
out_of_working_hours bool no true If this parameter appears, the lead has been submitted outside of the working hours for today
skip_ivr_call_counter numeric no If this parameter appears, this will be indicating the number of rounds without IVR calls

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:

Parameter Type Required Default Description
domain string yes The account to bind all subsequent actions to
id numeric Recommended 1 The kiosk identifier which contains all the settings that should be applied to this instance. This can also impact the widget UI if it is loaded, as the ID drives what menu is loaded, and associated visual config
lang string Recommended eng The default language to load any UI components in, and request strings from the server in
no_ui bool no true Instructs the library to load the default UI when set to false, by default no UI is loaded as the parameter is set to true
mobile bool no false Instructs the library to not load any of its own dependencies from the internet, and reference relative URLs only, by default this is not the case
load_ui bool no false Path to a custom UI library to load. See CornerWidgetUI for an example of how such a library can be structured
callback bool no Callback function to receive updates on the various components that the library will load as it starts up

$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.

Parameter Type Required Default Description
phone_number string yes The international dialling number that the customer should be called back on.
name string yes The name of the customer to be asked for when calling back
service_id numeric yes The ID of the requested service by the customer. This ID determines which group of people in the organisation receive the lead/notification
service_name string yes The user-friendly name of the service that the customer has requested for
additional_info object no Any additional personal information about the user that would be useful for the company representative. To be sent in JSON name/value pairs.
callback function no A callback to receive confirmation of lead creation, and updates on the lead processing status as it progresses through the lifecycle of being created, retrieved by a representative, and then closed. If supplied, the callback is supplied in the format `{“ticket-status”: [new / processing / finished ], “server”: true

$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:

Parameter Type Required Default Description
event_type string yes A user friendly headline description of what the event type is
payload object Recommended A JSON formatted set of key/value pairs that describe the event
callback function no A callback to your function once the server has acknowledged receipt of the intelligence

$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:

Parameter Type Required Default Description
key string yes The key to store the data with
value object Recommended The value to store (text only)

$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:

Parameter Type Required Default Description
key string yes The key the data has been stored with

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:

Parameter Type Required Default Description
callback function yes A custom function to handle the kiosk information when it is successfully loaded/retrieved from the Lucep server

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:

Property Name Description Reference Example
default_lang The default language that the kiosk text should be displayed in, and the language pack guaranteed to have all necessary text eng
kiosk_id The unique identifier for the kiosk that has been retrieved. Multiple different types of kiosks can be configured on the server, each with different properties as needed 1
button_cta The text desired on the call to action button Call me!
color The desired colour properties of the widget in hexadecimal format. Different properties can be configured for each kiosk as needed. {"background": "#000"}
extra_fields Additional fields to solicit information on from the user. This will be a structured object. Enforcement is up to your implementation and will not be validated by the server or the Lucep library. { "dom-property-id": { "label": "User friendly label","type":"text/checkbox/dropdown", "help_txt": "Any applicable help text (optional)","options": {"option1-id":"Option 1 User Text"}] }}
closed_txt The text to be displayed by the widget when it is minimised. This may not be applicable in all scenarios. Click here to get a callback!
open_txt The text to be displayed by the widget when it is expanded. This may not be applicable in all scenarios. Tell us how to contact you!

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.

Property Name Description Reference Example
dom-property-id This is the property-id that is expected to be submitted email

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

Property Name Description Reference Example
label The user-friendly label for this field Your email address
type The type of field that should be presented to the user. This can be customised by you on the Lucep console, but a few default options exist, e.g. text, checkbox, dropdown text
help_txt Some additional help text to supply to the user (if any) An email address looks like "[email protected]"
options For checkboxes or dropdowns, options need to be provided. By default, these are supplied as id/reference pairs in an object array. [{"my-option1": "A nice option 1"},{"awesome-option2" : "get me a number 2"}]

$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

Property Name Description Reference Example
status A descriptor of the lead state that can be any one of the following: new, processing, finished, no-ticket processing
server An indicator if this return is fresh from the server, or if it is a cached response based on the last action taken. Cached responses are the standard and are generally reliable indicators, and so expect a false in this field false

$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:

Parameter Type Required Default Description
callback function Recommended A custom function to receive notification when the old customer profile has been purged and a new one has been created function (resp){ ...}(no default)

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

Status responses

Status Description
ok Usually all worked as expected
fail Usually some parameters in the request are not valid. Please verify your values and try again
error Usually some gear internally drop off. If you continuously get this value, please contact us

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