Overview
This article will guide you on how to search for Leads through API.
Contents
Before You Begin
To learn more about API and Convoso's API Menu options, see API Menu Options Documentation.
There is one required Argument for the vendor's Request Query String:
- API Authentication Token
Note: Our system accepts HTTP POST in RAW format. We do not support nested parameters or multilevel arrays.
Search Leads via API
1.) Click the API main menu.
2.) Click the Leads menu option.
The Leads API page will open on the Insert Leads tab.
3.) Click the Search Leads tab.
Under this tab, you will see the POST Fields that vendors need when creating their Request Query String.
The required Arguments are marked in red and are the minimum requirements for the request to work.
Note: When creating a Request Query String, make sure that you have values for the required fields.
Below the Arguments list are the Example PHP Usage and Example JSON Response sections.
4.) Click the Test Request tab to run a test.
5.) Configure the fields for your test search.
Select the Authentication Token and enter Lead details to find the correct Lead or Leads. In this example, we will search for Leads by the User who owns them.
- (A) auth_token: Choose the correct Authentication Token in this drop-down.
- (B) owner_id: Enter the identification number of the User who owns the Leads.
- (C) offset: Defaults to zero; enter a different number if you want the search to skip a certain number of items.
- (D) limit: Defaults to ten; enter a different number if you want the search to return a different number of items.
6.) Check the Show Query checkbox.
7.) Click the green Run button.
If everything is configured correctly, the JSON Response will show as a success and display all of the information about the searched Leads.
Note: When you configure your Lead Search API with updated_at_start_date or updated_at_end_date parameters, your Response will be in ascending order by the date a User updated them.
JSON Response
Below, we have defined many standard fields in your JSON Response.
Note: You may see different results depending on your Lead form and test configurations.
| id | The Lead's identification number assigned by the system. |
| created_at | The time and date stamp for the Lead's creation in the Account. |
| modified_at | The time and date stamp for when an Admin or API last modified this Lead. |
| status | The Lead's current Status/Disposition Code. |
| user_id | The User's identification number. |
| owner_id | The identification number of the Agent that owns the Lead using Lead Ownership. |
| vendor_code | The unique identification number of the vendor, if applicable. |
| source_id | The identification number of the Source List for the Lead. |
| list_id | The identification number of the Lead's current List. |
| locale_gmt | The difference between the local time and GMT in hours. |
| called_since_last_reset | Whether the Lead has been called since an Admin last reset its List, Yes or No. |
| phone_code | The Lead's Country Code. |
| phone_number | The Lead's Primary Phone Number. |
| called_count | The number of times a Campaign or Agent dialed the Lead. |
| called_count_inbound | The number of Inbound Calls from this Lead. |
| state | The State from the Lead Form. |
| object_type | Identifies the response data as being for a Lead. |
| created_by | The identification number of the User who created the Lead in the system. |
| carrier_name | The name of the Carrier used for the last call to this Lead. |
| carrier_type | The type of Carrier used for the last call to the Lead. |
| lead_json_object | The Lead's JSON Object. |
| last_local_call_time | The time and date stamp of the last call placed to the Lead. |
| last_called | The time and date stamp of the last call placed to the Lead. |
| gmt_offset_now | The difference between the current time and Greenwich Mean Time. |
| lead_id | The identification number of the Lead. |
| user_uid | The User’s unique identifier. |
| user_name | The name of the User that created the Lead. |
| owner_uid | The Lead Owner's unique identifier. Only applicable when using Lead Ownership. |
| owner_name | The name of the Lead Owner when using Lead Ownership. |
| created_by_user_uid | The User Identification number of the User who created the Lead. |
| created_by_user_name | The Name of the User who created the Lead. |
| directory_uid | The directory's unique identifier. |
| directory_name | The name of the List containing this Lead. |
| source_uid | The unique identifier for the Source List. |
| source_name | The name of the Source List. |
| campaign_uid | The Campaign's unique identifier. |
| campaign_name | The name of the Campaign that contains this Lead's List. |
| status_name | The name of the Lead's current Status/Disposition. |
Please sign in and vote to let us know if you found this article helpful!
👇