Step 1: Create an API User
In ycc.ytel.com navigate to Settings >> Users >> API, then click
Read the NOTE "Please Copy and Save the password for the new API user. Or you will be forced to set new password" and type Confirm and then click Submit
Important: Copy and Save both the New User ID and the Password
Step 2: Select the Parameters to be used in your posting string depending on the intended use case
1. Identify the Function intended for your use case. Most customers will use "Add Lead" or "Update Lead" NOTE: We will be using the "Non Agent" API and "Add Lead" for posting leads. The separate "Agent" API is used mostly for controlling the Agents Interface.
2. For Adding Leads via API you will need to include the PARAMS that apply to your use case. Find the list here. Most Customers will need the following PARAMS:
function *Required | add_lead |
user *Required | created in Step 1 of this Article. Ex. Ytel1 |
pass *Required | created in Step 1 of this Article Ex. 1234 |
source *Required | description of what originated the API call maximum 20 characters. Ex. Website |
phone_number *Required | Must be all numbers, (USA - North America 10 Digits Only) Ex. 9991231234 |
list_id *Required | The List the leads will be posted to. Must be all numbers, 3-12 digits. Ex. 5555 |
dnc_check |
Not Required but Recommended. Values expected: Y, N or AREACODE, default is N |
add_to_hopper | Used to post the lead directly to the hopper. If your intention is for this lead to be called faster than simple List dialing, then this needs to be set to Y. Values expected: Y or N, default is N |
hopper_priority | Important setting for calling a lead ahead of other leads in the hopper. 99 is used by customers who wish to call leads "Real Time" after they are posted to the hopper. Values Expected: 99 to -99, the higher number the higher priority, default is 0 |
duplicate_check | Check for duplicate records in the system. Values Expected: 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. If this PARAM is used and there is a match the lead being posted will produce an error and not be added to the system. More Duplicate check options here. NOTE: Most customers will use one of the 3 options above. |
Lead PARAMS
vendor_lead_code | 1-20 characters. Often used to link contact IDs with another system. Ex. SF3214 |
source_id | 1-20 characters. Often used for drilling down further on sources. Ex. LandingPage21 |
title |
1-4 characters Ex. Sr. |
first_name | 1-30 characters Ex. John |
middle_initial | 1 character Ex. A |
last_name | 1-30 characters Ex. Doe |
address1 | 1-100 characters Ex. 31 Main Street |
address2 | 1-100 characters Ex. Apt. 21 |
address3 | 1-100 characters |
city | 1-50 characters Ex. Dallas |
state |
2 characters Ex. TX |
postal_code
|
1-10 characters Ex. 76002 |
1-70 characters Ex. johndoe@dallas.com | |
security_phrase | 1-100 characters |
comments | 1-255 characters |
rank | 1-5 digits. Advanced field, used in Rank Dialing |
Custom Fields PARAM
If you are using Custom Fields in Lists and you wish to post values into those custom fields for the particular list, see below:
custom_fields | Y or N, default is N. Defines whether the API will accept custom field data when inserting leads into the ytel 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" |
Step 3: Design the Posting String.
1. Identify the system URL. This is not ycc.ytel.com. This is the site your agents log into. For example: companyname.ytel.com
Posting string that will be used in this example will be: https://companyname.ytel.com/x5/api/non_agent.php?
NOTE: "https" secure connection
2. The API will except either a POST or a GET. For the purposes of this example, we will design a GET String.
Here is an example Posting String using the Example data above and the most important/Required Params. The usecase for the example below is the lead will be duplicate checked system-wide and inserted to the hopper with a priority of 99 so it is called ASAP or "Real Time". There will also be a custom field of favorite_color (as in the example above).
NOTE:
Parameters will be in blue
Values will be in bold black
Example Posting String:
https://companyname.ytel.com/x5/api/non_agent.php?function=add_lead&user=Ytel1&pass=1234&source=Website&phone_number=9991231234&list_id=5555&dnc_check=Y&add_to_hopper=Y&hopper_priority=99&duplicate_check=DUPSYS&first_name=John&last_name=Doe&address1=31+Main+Street&city=Dallas&state=TX&postal_code=76002&custom_fields=Y&favorite_color=blue