Enables the retrieval of leads from the Convoso account.
Endpoint:
GET https://api.convoso.com/v1/leads/search đź”’ Authentication
- Parameter Name: auth_token
- Type: Query Parameter
- Required: Yes
Query Parameters
Parameter | Type | Required | Description |
auth_token | string | Yes | Authentication token |
lead_id | string | No | Filter by specific Lead ID |
list_id | string | No | Filter by List ID |
user_id | string | No | Filter by User ID |
owner_id | string | No | Filter by Owner ID |
status | string | No | Filter by lead status |
offset | integer | No | Pagination offset. Default is 0 |
limit | integer | No | Number of leads to return. Default is 10, maximum is 2000 |
created_by | string | No | Filter by the user who created the lead |
| string | No | Filter by lead email | |
last_modified_by | string | No | Filter by last modifier |
first_name | string | No | Filter by lead first name |
last_name | string | No | Filter by lead last name |
phone_number | string | No | Filter by primary phone number |
alt_phone_1 | string | No | Filter by alternate phone 1 |
alt_phone_2 | string | No | Filter by alternate phone 2 |
address1 | string | No | Filter by address line 1 |
address2 | string | No | Filter by address line 2 |
city | string | No | Filter by city |
state | string | No | Filter by state |
province | string | No | Filter by province |
postal_code | string | No | Filter by postal code |
country | string | No | Filter by country |
gender | string | No | Filter by gender |
date_of_birth | string | No | Filter by date of birth (format:YYYY-MM-DD) |
created_at_start_date | string | No | Start date for created_at filter (format: YYYY-MM-DD) |
created_at_end_date | string | No | End date for created_at filter (format: YYYY-MM-DD) |
updated_at_start_date | string | No | Start date for updated_at filter (format: YYYY-MM-DD) |
updated_at_end_date | string | No | End date for updated_at filter (format: YYYY-MM-DD) |
Example Request
GET https://api.convoso.com/v1/leads/search? auth_token=YOUR_AUTH_TOKEN&lead_id=&list_id=&user_id=&owner_id=&status=&offset=0&limit=10&created_by=&email=&la st_modified_by=&first_name=&last_name=&phone_number=&alt_phone_1=&alt_phone_2=&address1=&address2=&city=&state= &province=&postal_code=&country=&gender=&date_of_birth=&created_at_start_date=&created_at_end_date=&updated_at_ start_date=&updated_at_end_date= Response Format JSON
{
"success": true,
"data": {
"offset": "0",
"limit": "10",
"total": "1",
"entries": [
{
"id": "1",
"created_at": "2025-06-02 21:09:36",
"modified_at": "2025-06-02 21:23:23",
"first_name": "",
"last_name": "",
"email": "",
"status": "NEW",
"owner_id": "0",
"source_id": "2705",
"list_id": "2705",
"locale_gmt": "-7.00",
"called_since_last_reset": "N",
"phone_code": "1",
"phone_number": "8182621448",
"alt_phone_2": "",
"postal_code": "",
"alt_phone_1": "",
"called_count": "0",
"called_count_inbound": "0",
"state": "",
"object_type": "LEAD",
"created_by": "0",
"last_modified_by": "0",
"carrier_name": "VERIZON WIRELESS",
"carrier_type": "mobile",
"updated_at": "2025-06-02 21:23:23",
"last_called": "0000-00-00 00:00:00",
"gmt_offset_now": "-7.00",
"lead_id": "1",
"address1": "",
"address2": "",
"city": "",
"province": "",
"country": "",
"gender": "",
"owner_uid": "",
"owner_name": "",
"last_modified_by_uid": "",
"last_modified_by_name": "",
"created_by_user_uid": "",
"created_by_user_name": "",
"directory_uid": "d95a6t7af8v8p6r5jl5zkiedtcz25fb8",
"directory_name": "API Lead Insert",
"source_uid": "d95a6t7af8v8p6r5jl5zkiedtcz25fb8",
"source_name": "API Lead Insert",
"campaign_uid": "28qbgcrtm6eapddf8yh58v43kil8t7ml",
"campaign_name": "Main Outbound",
"status_name": "New Lead"
}
]
}
} Response Field Definitions
Top-Level Data Object
Field | Type | Description |
| success | boolean | Identifies if the API was executed successfully |
| data | object | Contains lead data and metadata |
Data Object
| Field | Type | Description |
| offset | string | Current pagination offset. |
| limit | string | Current page size. |
| total | string | Total number of matching leads. |
| entries | array | Array of lead records. |
Entries - Lead Objects
| Field Type | Type | Description |
| id | string | Internal lead ID |
| lead_id | string | Public lead ID (same as id) |
| first_name | string | First name |
| last_name | string | Last name |
string | Email address | |
| status | string | Lead status (e.g. "NEW") |
| status_name | string | Label for lead status (e.g. "New Lead") |
| owner_id | string | Numeric ID of the lead owner |
| owner_uid | string | Unique user identifier of owner |
| owner_name | string | Name of the lead owner |
| source_id | string | Source ID the lead came from |
| source_uid | string | Unique source identifier |
| source_name | string | Source name (e.g., "API Lead Insert") |
| list_id | string | List ID the lead is assigned to |
campaign_uid | string | Campaign UID |
campaign_name | string | Campaign name |
locale_gmt | string | Timezone offset (e.g., -7.00 ) |
gmt_offset_now | string | Current GMT offset |
called_since_last_reset | string | Y or N |
phone_code | string | Country phone code (e.g. "1" for USA |
phone_number | string | Lead's main phone number |
| alt_phone_1 | string | Alternative phone number 1 |
| alt_phone_2 | string | Alternative phone number 2 |
| postal_code | string | ZIP/postal code |
| state | string | State |
| province | string | Province |
| city | string | City |
| address1 | string | Address line 1 |
| address2 | string | Address line 2 |
| country | string | Country |
| gender | string | Gender (if stored) |
| object_type | string | Typically "LEAD" |
called_count | string | Total times the lead was called |
called_count_inbound | string | Number of inbound calls |
carrier_name | string | Carrier (e.g., "VERIZON WIRELESS") |
carrier_type | string | "mobile" or "landline" |
last_called string | string | Last called date (0000-00-00 00:00:00 if never) |
created_by string | string | Creator's internal ID |
created_by_user_uid | string | UID of creator |
created_by_user_name | string | Name of creator |
last_modified_by | string | Modifier's internal ID |
last_modified_by_uid | string | UID of modifier |
last_modified_by_name | string | Name of modifier |
directory_uid | string | UID of lead source directory |
directory_name | string | Name of source directory |
created_at | string | Date/time lead was created YYYY-MM-DD HH:MM:SS) |
modified_at | string | Date/time lead was modified. |
updated_at | string | Last update timestamp. |
... | string | Customer Defined lead attributes based on customer definition. |