add_lead

gistfile1.txt

add_lead - adds a new lead to the vicidial_list table with several fields and options

NOTE: api user for this function must have modify_leads set to 1 and user_level
      must be set to 8 or higher

REQUIRED FIELDS-
phone_number -		must be all numbers, 6-16 digits
phone_code -		must be all numbers, 1-4 digits, defaults to 1 if not set
list_id -		must be all numbers, 3-12 digits, defaults to 999 if not set
source -		description of what originated the API call (maximum 20 characters)

SETTINGS FIELDS-
dnc_check -		Y, N or AREACODE, default is N
campaign_dnc_check -	Y, N or AREACODE, default is N
campaign_id -		2-8 Character campaign ID, required if using campaign_dnc_check or callbacks
add_to_hopper -		Y or N, default is N
hopper_priority -	99 to -99, the higher number the higher priority, default is 0
hopper_local_call_time_check - Y or N, default is N. Validate the local call time and/or state call time before inserting lead in the hopper
duplicate_check -	Check 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
				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
usacan_prefix_check -	Y or N, default is N. Check for a valid 4th digit for USA and Canada phone numbers (cannot be 0 or 1)
usacan_areacode_check -	Y or N, default is N. Check for a valid areacode for USA and Canada phone numbers
nanpa_ac_prefix_check -	Y or N, default is N. Check for a valid NANPA areacode and prefix, if optional NANPA data is on the system
custom_fields -		Y 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
callback -		Y or N, default is N. Set this lead as a scheduled callback. campaign_id field is REQUIRED for callbacks
callback_status -	1-6 Character, callback status to use, default is CALLBK (vicidial_list status will be set to CBHOLD to lock)
callback_datetime -	YYYY-MM-DD+HH:MM:SS, date and time of scheduled callback. REQUIRED if callback is set. NOW can be used for current datetime.
callback_type -		USERONLY or ANYONE, default is ANYONE
callback_user -		User ID the USERONLY callback is assigned to
callback_comments -	Optional comments to appear when the callback is called back

(for fields with spaces in the values, you can replace the space with a plus + sign[address, city, first_name, etc...])
OPTIONAL FIELDS- 
vendor_lead_code -	1-20 characters
source_id  -		1-50 characters
gmt_offset_now -	overridden by auto-lookup of phone_code and area_code portion of phone number if applicable
title -			1-4 characters
first_name -		1-30 characters
middle_initial -	1 character
last_name -		1-30 characters
address1 -		1-100 characters
address2 -		1-100 characters
address3 -		1-100 characters
city -			1-50 characters
state -			2 characters
province -		1-50 characters
postal_code -		1-10 characters
country_code -		3 characters
gender -		U, M, F (Undefined, Male, Female) - defaults to 'U'
date_of_birth -		YYYY-MM-DD
alt_phone -		1-12 characters
email -			1-70 characters
security_phrase -	1-100 characters
comments -		1-255 characters
multi_alt_phones -	5-1024 characters (see examples for more info)
rank -			1-5 digits
owner -			1-20 characters (user ID, Territory or user group)
entry_list_id -		WARNING! 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)


Multi-ALT-Phones format:

7275551212_1_work!7275551213_1_sister+house!1234567890_1_neighbor

The multi-alt-phones field is formatted as a field of phone-number/phone-code/phone-note set of data(phone code and alt_note are both optional and the phone code can be overridden by the force phone code flag). The record delimiter is an exclamation point with the optional phone code and note delimited within the record by an underscore character _.


Example URL strings for API calls:
http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=add_lead&phone_number=7275551111

http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=add_lead&phone_number=7275551212&phone_code=1&list_id=999&dnc_check=N&first_name=Bob&last_name=Wilson

http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=add_lead&phone_number=7275551111&phone_code=1&list_id=999&dnc_check=N&first_name=Bob&last_name=Wilson&add_to_hopper=Y&hopper_local_call_time_check=Y

http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=add_lead&phone_number=7275551111&phone_code=1&list_id=999&dnc_check=N&campaign_dnc_check=Y&campaign_id=TESTCAMP&first_name=Bob&last_name=Wilson&address1=1234+Main+St.&city=Chicago+Heights&state=IL&add_to_hopper=Y&hopper_local_call_time_check=Y&multi_alt_phones=7275551212_1_work!7275551213_1_sister+house!1234567890_1_neighbor

http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=add_lead&phone_number=7275551212&phone_code=1&list_id=999&dnc_check=N&first_name=Bob&last_name=Wilson&duplicate_check=DUPLIST-DUPNAMEPHONELIST

http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=add_lead&phone_number=7275551212&phone_code=1&list_id=999&custom_fields=Y&favorite_color=blue

http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=add_lead&phone_number=7275551111&campaign_id=TESTCAMP&callback=Y&callback_status=CALLBK&callback_datetime=NOW&callback_type=USERONLY&callback_user=6666&callback_comments=Comments+go+here

Example responses:
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

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