This article describes the process of updating standard and custom lead information in the system, in real time.
Required Fields
The following information is required for every call to this API method.
function: Used to indicate which API method to execute. Must be set to: update_lead
company_id: The ID of your company as provided when you initially registered to Qubicles. This is commonly used to log into the Qubicles manager interface.
user: A valid user in your organization used to authenticate the request.
list_id: internal id of list to dump web lead into. This can be found in the Census app - simply hover over a list's name to find it's internal list id. If a list doesn't exist for the specific feed, create one using Census.
dnc_check: set to YES to filter against the system-wide DNC list for this phone
campaign_dnc_check: set to YES to filter against the campaign-specific DNC list for this phone
phone_code: country code prefix to use for phone number (e.g. "1" for USA, "92" for Pakistan, etc)
Lookup Options
A combination of one or more of these fields must be supplied in order for this API method to function:
lead_id: The system-generated internal ID of the lead being updated. If not known, you may use phone_number or vendor_lead_code.
vendor_lead_code: Used in place of the lead_id or phone_number to look up the lead.
phone_number: Used to look up the lead by their phone_number.
search_method: The search method is used to specify what type of lookup to perform. The three options available for this field are as follows (defaults to phone_number):
lead_id: tells the system to search for the lead by its internal id
vendor_lead_code: tells the system to search for the lead by a custom vendor lead code
phone_number: tells the system to search for the lead by phone number
For example, the following URL string will instruct the system to search for a lead by its phone number:
&search_method=phone_number
search_location: Search location instructs the system where to search for leads. You can supply one of the following values to this field (defaults to list):
list: Use this option to search a specific list. You must also supply a list_id as part of the API call.
campaign: User this option to search all the lists for a specific campaign. When in use, you must also pass in the 'campaign_id' to search and 'list_id_field' to add the record to if not found on any of the campaign's lists.
Example: Search_location=campaign&campaign_id=TEST&list_id_field=1234&
records: Use this option to tell the system how many records to update if more than one is found. By default, will update only the most recent lead found.
Additional Settings
custom_fields: if your list contains custom fields, set this option to Y or N to also update any custom field data. Custom fields could be simply passed in as the custom field name and the new value. For example, if you had a custom field called balance that you wanted to update to $125.00, you would simply pass the following along to the API:
&balance=125.00
no_update: This option is used to instruct the system whether it should NOT update the record, and to only return whether or not the record exists. Possible values are Y or N, with the default being N.
insert_if_not_found: This option is used to instruct the system whether it should insert the record if it could not find a matching lead. Possible values are Y or N, with the default being N.
delete_lead: Setting this option to Y will delete the lead from the database. Possible values are Y or N, with the default being N.
callback: Setting this option to Y will attempt to schedule a callback for the lead. Setting this option to DELETE will remove all existing callbacks associated with the lead. Possible values are Y, N or DELETE, with the default being N.
callback_status: Set this to a valid Scheduled Callback disposition code, such as "CALLBK".
callback_datetime: The full date and time to set the scheduled callback to following the "yyyy-MM-dd HH:mm:ss" format.
callback_type: Setting this option to MyCallback will tie this callback to the user specified in callback_user. Setting it to CampaignCallback will add the scheduled callback and make it available to anyone on the campaign. Possible values are MyCallback or CampaignCallback, with the default being MyCallback.
callback_user: Optional. The user to associate with the scheduled callback. Required if callback_type is set to MyCallback.
callback_comments: Arbitrary comments to associate with the scheduled callback.
Lead Fields Available to Update
user_field: This updates the 'user' field associated with the lead and is limited to 1-20 characters.
list_id_field: This updates the 'list_id' field for the lead, essentially moving it to another list. It is limited to 3-12 digits.
status: This updates the current disposition for the lead and is limited to 1-6 characters. Punctuation or spaces are not allowed.
vendor_lead_code: A user-defined identifier for the vendor of your lead, this updates the lead code for the lead and is limited to 1-20 characters.
vendor_id: customer-specified identifier used to identify phone number in vendor's system
source_id: A user-defined identifier for the source of your lead, this updates the source Id of the lead and is limited to 1-50 characters.
title: This is limited to 1-4 characters
first_name: This is limited to 1-30 characters
middle_initial: This is limited to 1 character
last_name: This is limited to 1-30 characters
address1: This is limited to 1-100 characters
address2: This is limited to 1-100 characters
city: This is limited to 1-50 characters
state: This is limited to 2 characters
province: This is limited to 1-50 characters
postal_code: This is limited to 1-10 characters
date_of_birth: This is limited to the following format: YYYY-MM-DD
alt_phone: This is limited to 1-12 characters
email: This is limited to 1-70 characters
comments: This is limited to 1-255 characters
Please note that special characters are not allowed in any of these fields.
Sample API Calls
https://cloud.qubicles.io/agent/api.php?company_id=ABCInc&user=JDoe&function=update_lead&lead_id=200&last_name=Williams&status=B
https://cloud.qubicles.io/agent/api.php?company_id=ABCInc&user=JDoe&function=update_lead&search_method=vendor_lead_code&vendor_lead_code=12345&last_name=Noel
https://cloud.qubicles.io/agent/api.php?company_id=ABCInc&user=JDoe&function=update_lead&search_method=phone_number&records=5&list_id=1234&search_location=list&phone_number=9876543210&last_name=Hall
https://cloud.qubicles.io/agent/api.php?company_id=ABCInc&user=JDoe&function=update_lead&search_location=LIST&search_method=phone_number&phone_number=9876543210&phone_code=1&list_id=0000&first_name=Jason&last_name=Doe&city=Miami&custom_fields=Y&balance=125.00
https://cloud.qubicles.io/agent/api.php?company_id=ABCInc&user=JDoe&function=update_lead&lead_id=200&no_update=Y
https://cloud.qubicles.io/agent/api.php?company_id=ABCInc&user=JDoe&function=update_lead&lead_id=200&no_update=Y&callback=Y&callback_status=CALLBK&callback_datetime=2017-03-10 16:00:00&callback_type=MyCallback&callback_user=JDoe&callback_comments=Scheduled via the API
Sample Responses
Error: No valid search method was specified.
Notice: No matches were found in the system.
Success: Lead has been updated.
Comments
0 comments
Article is closed for comments.