Enables the insertion of Leads into a specified List and updates existing Leads if specified.
Endpoint:
POST https://api.convoso.com/v1/leads/insert
🔒 Authentication
- Parameter Name: auth_token
- Type: Query Parameter
- Required: Yes
🔎 Query Parameters
Required Lead Information
| Parameter | Type | Required | Description |
|---|---|---|---|
| auth_token | string | ✅ Yes | authorization token |
| list_id | integer | ✅ Yes | Target List ID |
| phone_number | phone | ✅ Yes | Primary phone number for the lead |
Optional Lead Attributes - Standard Fields
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_code | string | Optional | Phone code (default is 1) |
| status | string | Optional | Lead status |
| created_by | string | Optional | Creator user ID |
| last_modified_by | string | Optional | Modifier user ID |
| owner_id | string | Optional | Lead owner ID |
| first_name | string | Optional | First name |
| last_name | string | Optional | Last name |
| alt_phone_1 | string | Optional | Cell phone |
| alt_phone_2 | string | Optional | Work phone |
string | Optional | Email address | |
| address1 | string | Optional | Address line 1 |
| address2 | string | Optional | Address line 2 |
| city | string | Optional | City |
| state | string | Optional | State |
| province | string | Optional | Province |
| postal_code | string | Optional | ZIP/Postal Code |
| country | string | Optional | Country |
| gender | string | Optional | Gender |
| date_of_birth | string | Optional | Date of Birth |
Optional Lead Attributes - Customer Defined Fields
| Parameter | Type | Required | Description |
|---|---|---|---|
| ... | string | Optional | All customer defined fields based on customer defined record layout. |
Duplicate and Compliance Checks
| Parameter | Type | Required | Description |
|---|---|---|---|
| check_dup | integer | Optional | 1 = Check account-wide, 2 = Check that List the Lead is in, 3 = Check that Campaign the Lead is in, 4 = Check duplicates against Lists in the check_dup_list parameter. |
| check_dup_list | integer | Optional | This field is used to determine which lists are checked when check_dup is set to '4'. Please enter list ids which can be joined in conjunction separated by a comma. |
| check_dup_archive | boolean | Optional | Check for duplicate phone in archived leads (requires check_dup) |
| check_dnc | boolean | Optional | Check against Do Not Call list (if campaign allows) |
| check_wireless | boolean | Optional | Check if the phone is a wireless number |
| filter_phone_code | boolean | Optional | Strip country code from number and populate phone_code |
Hopper & Dialing
| Parameter | Type | Required | Description |
|---|---|---|---|
| hopper | boolean | Optional | Insert into hopper for immediate dialing |
| hopper_priority | integer | Optional | Hopper priority (0–99, default 99) |
| hopper_expires_in | integer | Optional | Hopper expiration in minutes (max 300) |
Update Behavior
| Parameter | Type | Required | Description |
|---|---|---|---|
| update_if_found | boolean | Optional | If true, updates the lead if phone_number or lead_id match |
| lead_id | integer | Optional | Lead ID to update (if update_if_found=true) |
| search_campaign_id | integer | Optional | Campaign ID to search within when updating |
| search_list_id | integer | Optional | List ID to search within (takes precedence over campaign ID) |
| update_order_by_last_called_time | string | Optional | Sort order when matching (ASC or DESC) |
Integrations
| Parameter | Type | Required | Description |
|---|---|---|---|
| blueinkdigital_token | string | Optional | Used to fetch phone number from Blue Ink Digital (requires predefined form field) |
| reject_by_carrier_type | string | Optional | Rejects based on carrier type (MOBILE, VOIP, LANDLINE; comma-separated if multiple) |
Example Request
POST https://api.convoso.com/v1/leads/insert?auth_token=your_auth_token&adaptor_id=&list_id=9999&check_dup=0&check_dup_archive=0&check_dnc=0&check_wireless=0&hopper=&hopper_priority=99&hopper_expires_in=0&update_if_found=&update_order_by_last_called_time=DESC&blueinkdigital_token=&reject_by_carrier_type=&filter_phone_code=&lead_id=0&phone_code=1&created_by=&email=&last_modified_by=&owner_id=&first_name=&last_name=&phone_number=8182621447&alt_phone_1=&alt_phone_2=&address1=&address2=&city=&state=&province=&postal_code=&country=&gender=&date_of_birth=&_call_server_ip=&_sip_header=
Response Format (JSON)
{
"success": true,
"data": {
"lead_id": 1
},
"id": 1
}Response Field Definitions
Top-Level Data Object
| Field | Type | Description |
|---|---|---|
| success | boolean | Identifies if the API was executed successfully |
| data | object | Response Object |
| id | integer | Lead identifier assigned to the newly created lead |
Data Object
| Field | Type | Description |
|---|---|---|
| lead_id | integer | Lead identifier assigned to the newly created list |