# Leads # Load Leads ## **API: Load Lead** ### **Description** The **Load Lead API** allows you to register, import, and distribute leads within a call center platform. Its purpose is to centralize the capture of potential customers coming from campaigns, web forms, external databases, or CRM integrations, so they can later be managed by agents, auto dialers, or follow-up workflows.

**Note:** Api user for this function must have modify\_leads set to 1 and user\_level must be set to 8 or higher

## 🔗 **URL** #### https://DOMAIN.croco-dial.net/API/lmapi.php

**Note:** Replace `DOMAIN` with the specific domain you want to query.

### **📝 Required Parameters**
**Parameter****Description**
phone\_numbermust be all numbers, 6-16 digits.
phone\_codemust be all numbers, 1-4 digits, defaults to 1 if not set.
list\_idmust be all numbers, 3-12 digits, defaults to 999 if not set.
sourcedescription of what originated the API call (maximum 20 characters).
campaingmust be the campaign to load the lead
### **Opcional Fields**
vendor\_lead\_code1-20 characters
source\_id1-50 characters
gmt\_offset\_nowoverridden by auto-lookup of phone\_code and area\_code portion of phone number if applicable
title 1-4 characters
first\_name1-30 characters
middle\_initial1 character
last\_name1-30 characters
address11-100 characters
address21-100 characters
address31-100 characters
city1-50 characters
state2 characters
province1-50 characters
postal\_code1-10 characters
country\_code3 characters
genderU, M, F (Undefined, Male, Female) - defaults to 'U'
date\_of\_birthYYYY-MM-DD
alt\_phone1-12 characters
email1-70 characters
security\_phrase1-100 characters
comments1-255 characters
multi\_alt\_phones5-1024 characters (see examples for more info)
rank1-5 digits
owner1-20 characters (user ID, Territory or user group)
entry\_list\_idWARNING! ONLY USE IF YOU KNOW WHAT YOU ARE DOING, CAN BREAK CUSTOM FIELDS! (must be all numbers, 3-12 digits, will not work if custom\_fields is set to Y)
### **Settings Fields**
dnc\_checkY, N or AREACODE, default is N
campaign\_dnc\_checkY, N or AREACODE, default is N
campaign\_id2-8 Character campaign ID, required if using campaign\_dnc\_check or callbacks
add\_to\_hopperY or N, default is N
hopper\_priority99 to -99, the higher number the higher priority, default is 0
hopper\_local\_call\_time\_checkY or N, default is N. Validate the local call time and/or state call time before inserting lead in the hopper
usacan\_prefix\_checkY or N, default is N. Check for a valid 4th digit for USA and Canada phone numbers (cannot be 0 or 1).
usacan\_areacode\_checkY or N, default is N. Check for a valid areacode for USA and Canada phone numbers(also checks for 10-digit length).
nanpa\_ac\_prefix\_checkY or N, default is N. Check for a valid NANPA areacode and prefix, if optional NANPA data is on the system.
custom\_fieldsY or N, default is N. Defines whether the API will accept custom field data when inserting leads into the vicidial\_list table For custom fields to be inserted, just add the field label as a variable to the URL string For example, if the field\_label is "favorite\_color" you would add "&favorite\_color=blue".
tz\_method<empty>, POSTAL, TZCODE or NANPA, default is <empty> which will use the country code and areacode for time zone lookups POSTAL relies on the postal\_code field TZCODE relies on the owner field being populated with a proper time zone code NANPA relies on the optional NANPA areacode prefix data being loaded on your system.
callbackY or N, default is N. Set this lead as a scheduled callback. campaign\_id field is REQUIRED for callbacks.
callback\_status1-6 Character, callback status to use, default is CALLBK (vicidial\_list status will be set to CBHOLD to lock.
callback\_datetimeYYYY-MM-DD+HH:MM:SS, date and time of scheduled callback. REQUIRED if callback is set. 'NOW' can be used for current datetime. 'xDAYS' can also be used where 'x' is replaced with a number of days in the future.
callback\_typeUSERONLY or ANYONE, default is ANYONE.
callback\_userUser ID the USERONLY callback is assigned to.
callback\_commentsOptional comments to appear when the callback is called back.
lookup\_stateY or N, default is N. Looks up state field from areacode list. Only works if the 'state' field is not populated.
list\_exists\_checkY or N, default is N. If the list\_id is not a defined list in the system, it will ERROR and not insert the lead.
duplicate\_checkCheck for duplicate records in the system, can select more than one (duplicate\_check=DUPLIST-DUPTITLEALTPHONELIST) If duplicate is found, will return error, the duplicate data and lead\_id and list\_id of existing record
#### **Here are the duplicate\_check options: ** - **DUPLIST** - check for duplicate phone\_number in same list - **DUPCAMP** - check for duplicate phone\_number in all lists for this list's campaign - **DUPSYS** - check for duplicate phone\_number in entire system - **DUPPHONEALTLIST** - check for duplicate phone against phone\_number and alt\_phone in same list - **DUPPHONEALTCAMP** - check for duplicate phone against phone\_number and alt\_phone in all lists for this list's campaign - **DUPPHONEALTSYS** - check for duplicate phone against phone\_number and alt\_phone in entire system - **DUPTITLEALTPHONELIST** - check for duplicate title and alt\_phone in same list - **DUPTITLEALTPHONECAMP** - check for duplicate title and alt\_phone in all lists for this list's campaign - **DUPTITLEALTPHONESYS** - check for duplicate title and alt\_phone in entire system - **DUPNAMEPHONELIST** - check for duplicate first\_name, last\_name and phone\_number in same list - **DUPNAMEPHONECAMP** - check for duplicate first\_name, last\_name and phone\_number in all lists for this list's campaign - **DUPNAMEPHONESYS** - check for duplicate first\_name, last\_name and phone\_number in entire system - " **1/2/3/7/14/15/21/28/30/60/90/180/360DAY** - Added to one of the above duplicate checks(i.e. "DUPSYS90DAY"), only checks leads loaded in last 90 days ### **Request Examples:** #### **GET :** ```bash curl -X GET "https://DOMAIN.croco-dial.net/API/lmapi.php?user=MyUser&pass=MyPass&function=add_lead&phone_number=number_client&source=MyUser ``` #### **POST (Form Data):** If you prefer to send the data as form parameters: ```bash curl -X POST "https://DOMAIN.croco-dial.net/API/lmapi.php" \ --data-urlencode "user=MyUser" \ --data-urlencode "pass=MyPass" \ --data-urlencode "function=add_lead" \ --data-urlencode "phone_number=number_client" \ --data-urlencode "source=MyUser" ``` #### **Example Response** ``` SUCCESS: add_lead LEAD HAS BEEN ADDED - 7275551111|6666|999|193715|-4 NOTICE: add_lead ADDED TO HOPPER - 7275551111|6666|193715|1677922 ``` ``` SUCCESS: add_lead LEAD HAS BEEN ADDED - 7275551111|6666|999|193716|-4 NOTICE: add_lead CUSTOM FIELDS VALUES ADDED - 7275551111|1234|101 NOTICE: add_lead CUSTOM FIELDS NOT ADDED, CUSTOM FIELDS DISABLED - 7275551111|Y|0 NOTICE: add_lead CUSTOM FIELDS NOT ADDED, NO CUSTOM FIELDS DEFINED FOR THIS LIST - 7275551111|1234|101 NOTICE: add_lead CUSTOM FIELDS NOT ADDED, NO FIELDS DEFINED - 7275551111|1234|101 NOTICE: add_lead MULTI-ALT-PHONE NUMBERS LOADED - 3|6666|193716 NOTICE: add_lead NOT ADDED TO HOPPER, OUTSIDE OF LOCAL TIME - 7275551111|6666|193716|-4|0 ``` ``` NOTICE: add_lead SCHEDULED CALLBACK ADDED - 1234|2011-09-29 12:00:01|TESTCAMP|6666|USERONLY|CALLBK NOTICE: add_lead SCHEDULED CALLBACK NOT ADDED, USER NOT VALID - 1234|TESTCAMP|6| NOTICE: add_lead SCHEDULED CALLBACK NOT ADDED, CAMPAIGN NOT VALID - 1234|XYZ ``` ``` NOTICE: add_lead NANPA options disabled, NANPA prefix data not loaded - 0|6666 ```

**Example Error**

``` ERROR: add_lead INVALID PHONE NUMBER LENGTH - 72755|6666 ERROR: add_lead INVALID PHONE NUMBER PREFIX - 72755|6666 ERROR: add_lead INVALID PHONE NUMBER AREACODE - 72755|6666 ERROR: add_lead INVALID PHONE NUMBER NANPA AREACODE PREFIX - 7275551212|6666 ``` ``` ERROR: add_lead USER DOES NOT HAVE PERMISSION TO ADD LEADS TO THE SYSTEM - 6666|0 ERROR: add_lead NOT AN ALLOWED LIST ID - 7275551212|98762 ERROR: add_lead NOT A DEFINED LIST ID, LIST EXISTS CHECK ENABLED - 7275551212|12344 ``` ``` ERROR: NO FUNCTION SPECIFIED ``` ``` ERROR: add_lead DUPLICATE PHONE NUMBER IN LIST - 7275551111|101|8765444 ERROR: add_lead DUPLICATE PHONE NUMBER IN CAMPAIGN LISTS - 7275551111|101|8765444|101 ERROR: add_lead DUPLICATE PHONE NUMBER IN SYSTEM - 7275551111|101|8765444|101 ERROR: add_lead DUPLICATE PHONE NUMBER IN LIST - 7275551111|101|8765444|PHONE ERROR: add_lead DUPLICATE PHONE NUMBER IN CAMPAIGN LISTS - 7275551111|101|8765444|101|ALT ERROR: add_lead DUPLICATE PHONE NUMBER IN SYSTEM - 7275551111|101|8765444|101|PHONE ERROR: add_lead DUPLICATE TITLE ALT_PHONE IN LIST - 1234|7275551111|101|8765444 ERROR: add_lead DUPLICATE TITLE ALT_PHONE IN CAMPAIGN LISTS - 1234|7275551111|101|8765444|101 ERROR: add_lead DUPLICATE TITLE ALT_PHONE IN SYSTEM - 1234|7275551111|101|8765444|101 ERROR: add_lead DUPLICATE NAME PHONE IN LIST - Bob|Smith|7275551113|101|8765444|101 ERROR: add_lead DUPLICATE NAME PHONE IN CAMPAIGN LISTS - Bob|Smith|7275551113|101|8765444|101 ERROR: add_lead DUPLICATE NAME PHONE IN SYSTEM - Bob|Smith|7275551113|101|8765444|101 ```