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:
- The target prospect is contacted and confirms their interest, resulting in the lead being categorised as qualified
- The prospect elects to opt-out from being contacted, in which case the lead is categorised as rejected.
- 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:
- Attempts to call the prospect fail
- The prospect hangs up after taking the call
- 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:
- 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.
- 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.
- 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 | |
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 |
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.