About Searching for Leads
You can search for leads using Primary Search Fields and Extended Search Fields. The Primary Search Fields can be used for performing basic searches on leads such as the campaign or list they are found in, while the Extended Search Fields provide search parameters that you can use to get more granular with your lead search.
Primary Search Fields
The primary search fields include a selection of basic search parameters. You can search for leads by campaign, or you can search only for leads whose status is SUPPRESSED. You can look for leads that have been orphaned, or you can search for leads by loaded lists, according to disposition, or whether they were inserted by an agent or supplied by the system.
API Property | UI Display | UI Default | Description |
---|---|---|---|
campaignId |
Campaign | first available campaign  | Search from a list of available dial groups and campaigns. Use Dial Groups and Campaigns to retrieve valid values. |
suppressed |
Suppressed | first available campaign  | Suppressed leads are leads the system will not dial. They will still maintain their lead status, however, unlike paused or cancelled leads (whose lead status will change once they have been paused or cancelled). Allowed values include ONLY_SUPPRESSED , ONLY_UNSUPPRESSED , ALL |
listIds |
Loaded Lists | Select lists...  | Search from any loaded leads list by their ID. Please note that this parameter depends upon a campaign in the campaignId setting. Use Leads List to retrieve valid values. |
agentDispositions |
Agent Dispositions | Select agent dispositions...  | Search for leads from a list of agent dispositions by campaign. This parameters depends upon a campaign in the campaignId Use Campaign Dispositions to retrieve a valid list of values. |
systemDispositions |
System Dispositions | Select system dispositions...  | Search from a list of system dispositions by account. Use System Dispositions for a list of valid values. |
leadStates |
Lead Status | Select lead status...  | Search from a list of lead status by account. Use Lead Status for a list of valid values. |
physicalStates |
State | Select states...  | Search for leads by their (geographical) state. You can select one or more states via the dropdown list. The list includes all of the United States and all provinces and territories of Canada. Use States for a list of valid values |
leadTimezones |
Timezone | Select timezones...  | Search for leads by timezone. You need only include the name of the timezone, but the list must be written as an array of objects. Use Lead Timezones for a list of valid values |
Supporting Values and APIs
The following value lists and APIs are used to retrieve predefined values for certain fields. Use these values to populate the correct parameter values of fields.
The BASE_DIAL_GROUP_URL
is {BASE_URL}/api/v1/admin/accounts/{accountId}/dialGroups
Dial Groups and Campaigns
Gets a list of dial groups with associated campaigns created under this account. Campaigns are contained within Dial Groups and this call will retrieve both.
GET {BASE_DIAL_GROUP_URL}/withChildren
Leads List
Gets a list of leads that are part of this campaign. Multiple lead lists can be linked to a campaign and this command returns list IDs for each lead list.
GET {BASE_DIAL_GROUP_URL}/{dialGroupId}/campaigns/{campaignId}/lists
Campaign Dispositions
Gets a list of the agent dispositions for this campaign
GET {BASE_DIAL_GROUP_URL}/{dialGroupId}/campaigns/{campaignId}/campaignDispositions
System Dispositions
The parameter systemDispositions
can take on the following values:
Value | Description |
---|---|
ANSWER |
Search all calls that were answered by a lead and connected to a live agent |
NOANSWER |
Search all calls that rang without being answered by a lead |
BUSY |
Search all calls that the system dispositioned as a busy response |
MACHINE |
Search all calls that resulted in a machine answer |
INTERCEPT |
Search all calls for which the phone number was unreachable |
DISCONNECT |
Search all calls that were disconnected |
ABANDON |
Search all calls that ended because the system could not find an available agent after dialing the lead |
CONGESTION |
Search all calls that ended due to excessive network traffic or insufficient bandwidth |
MANUAL_PASS |
Search all calls that calls that had a manual pass applied to them |
INBOUND_CALLBACK |
Search all calls designated as (inbound) callbacks |
APP_DNC |
Search all calls that have been skipped due to a DNC list verification |
APP_REQUEUE |
Search all call legs that have been requeued via IVR (this setting only applies to certain accounts. Please contact your CSM for more information) |
APP_REQUEUE_COMPLETE |
Search all call legs that have been requeued via IVR in which the call has been received in the new queue. |
APP_REQUEUE_ABANDON |
Search all call legs that have been requeued via IVR in which the call was abandoned before a connection was made |
INBOUND_ABANDON |
Search all calls where the caller abandoned the call while waiting in queue |
Lead Status
The parameter leadState
can take on the following values:
Value | Description |
---|---|
ACTIVE |
Search for all leads currently engaged on an active call |
AGENT_CALLBACK |
Search for all leads that have been flagged for an agent-specific callback |
CALLBACK_CANCELLED |
Search for all leads that have had a callback flag removed |
CALLBACK |
Search for all leads that have been flagged for a callback |
CANCELLED |
Search for all leads that have been cancelled from dialing |
COMPLETE |
Search for all leads that have been cancelled (and will not be requeued for dialing) |
DISCONNECTED |
Search for all leads that have been assigned a DISCONNECTED lead state |
DO_NOT_CALL |
Search for all leads whose phone number is on the DNC list |
INTERCEPT |
Search for all leads with a disconnected or otherwise unreachable number |
MAX_DIAL_LIMIT |
Search for all leads that have been dialed the maximum number of times |
PAUSED |
Search for all leads that have been paused from dialing |
PENDING_CALLBACK |
Search for all leads that are awaiting a scheduled callback time set by an agent-specific callback disposition |
PENDING_ERR |
Search for all leads that have been set to PENDING and remain in that state |
PENDING_HCI |
Search for all leads that have not yet been dialed by an HCI agent |
PENDING |
Search for all leads that have been fetched by the preview dialer or are actively being dialed by the predictive dialer |
READY |
Search for all leads that are ready for dialing (including leads that have reached the maximum number of passes) |
TRANSITIONED |
Search for all leads that have been copied in transition mode and sent to another campaign. Please note that when a lead is copied in Transition mode, the original lead retains the original Lead ID, while the copied version gets a new Lead ID |
WHITELIST |
Search for all leads that have been whitelisted via the Whitelist Manager |
Lead Timezones
The parameter leadTimezones
can take on the following values:
Value | Description |
---|---|
ADT |
ADT - Atlantic Daylight Time |
AKDT |
AKDT - Alaska Daylight Time |
AKST |
AKST - Alaska Standard Time |
AST |
AST - Atlantic Standard Time |
CDT |
CDT - Central Daylight Time |
CST |
CST - Central Standard Time |
EDT |
EDT - Eastern Daylight Time |
EST |
EST - Eastern Standard Time |
HADT |
HADT - Hawaii-Aleutian Daylight Time |
HAST |
HAST - Hawaii-Aleutian Standard Time |
MDT |
MDT - Mountain Daylight Time |
MST |
MST - Mountain Standard Time |
NDT |
NDT - Newfoundland Daylight Time |
NST |
NST - Newfoundland Standard Time |
PDT |
PDT - Pacific Daylight Time |
PMDT |
PMDT - Pierre/Miquelon Daylight Time |
PMST |
PMST - Pierre/Miquelon Standard Time |
PST |
PST - Pacfic Standard Time |
WSDT |
WSDT - Samoa Daylight Time |
WSST |
WSST - Somoa Standard Time |
States
Get a list of states from the United States and all provinces and territories of Canada.
GET {BASE_URL}/api/v1/admin/states
Request
Be sure to set the proper BASE_URL and authorization header for your deployment.
POST {BASE_URL}/api/v1/admin/accounts/{accountId}/campaignLeads/leadSearch
Authorization: bearer <myAccessToken>
Content-Type: application/json;charset=UTF-8
Accept: application/json
{
"firstName":"Jon",
"campaignId":136785,
"listIds":[],
"agentDispositions":[],
"systemDispositions":[],
"leadStates":[],
"physicalStates":[],
"leadTimezones":
[
{"name":"CST"},
{"name":"PST"}
],
"suppressed":"ALL",
"campaignIds":[136785]
}
curl -XPOST 'https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/ campaignLeads/leadSearch' \
-H 'Authorization: Bearer {myAccessToken}' \
-d '{"firstName":"John"}' \
-H 'Content-Type: application/json'
/****** Install Node JS SDK wrapper *******
$ npm install ringcentral-engage-voice-client
*******************************************/
const RunRequest = async function () {
const EngageVoice = require('ringcentral-engage-voice-client').default
// Instantiate the SDK wrapper object with your RingCentral app credentials
const ev = new EngageVoice({
clientId: "RINGCENTRAL_CLIENTID",
clientSecret: "RINGCENTRAL_CLIENTSECRET"
})
try {
// Authorize with your RingCentral Office user credentials
await ev.authorize({
username: "RINGCENTRAL_USERNAME",
extension: "RINGCENTRAL_EXTENSION",
password: "RINGCENTRAL_PASSWORD"
})
// Search Leads with first name John
const endpoint = "/api/v1/admin/accounts/{accountId}/campaignLeads/leadSearch"
const postBody = {
"firstName": "John"
}
const response = await ev.post(endpoint, postBody)
console.log(response.data);
}
catch (err) {
console.log(err.message)
}
}
RunRequest();
#### Install Python SDK wrapper ####
# $ pip3 install ringcentral_engage_voice
# or
# $ pip install ringcentral_engage_voice
#####################################
from ringcentral_engage_voice import RingCentralEngageVoice
def search_leads():
try:
postBody = {
"firstName": "John"
}
response = ev.post("/api/v1/admin/accounts/{accountId}/campaignLeads/leadSearch", postBody). json()
print(response)
except Exception as e:
print(e)
# Instantiate the SDK wrapper object with your RingCentral app credentials
ev = RingCentralEngageVoice(
"RINGCENTRAL_CLIENTID",
"RINGCENTRAL_CLIENTSECRET")
try:
# Authorize with your RingCentral Office user credentials
ev.authorize(
username="RINGCENTRAL_USERNAME",
password="RINGCENTRAL_PASSWORD",
extension="RINGCENTRAL_EXTENSION"
)
search_leads()
except Exception as e:
print(e)
/****** Install PHP SDK wrapper **
$ composer require engagevoice-sdk-wrapper:dev-master
*************************************/
<?php
require('vendor/autoload.php');
// Instantiate the SDK wrapper object with your RingCentral app credentials
$ev = new EngageVoiceSDKWrapper\RestClient("RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET");
try{
// Login your account with your RingCentral Office user credentials
$ev->login("RC_USERNAME", "RC_PASSWORD", "RC_EXTENSION_NUMBER");
$endpoint = "admin/accounts/~/campaignLeads/leadSearch";
$params = array ( "firstName" => "John" );
$response = $ev->post($endpoint, $params);
print ($response."\r\n");
}catch (Exception $e) {
print $e->getMessage();
}