Overview
The Vicidial Lead Archive API is designed to facilitate the archiving of leads within the Vicidial system. This API allows users to manage leads efficiently, ensuring streamlined operations and improved lead data management practices.
| Info |
|---|
To use this API, contact TForge. |
| Note |
|---|
Do not use this API during production hours, as it will affect dialling agents. |
Base URL Endpoint
Use the following URL and endpoint to initiate your request:
| Code Block |
|---|
https://api.tforge.co.za |
Method | URL | Description |
|---|---|---|
POST | /vicidial/lead/archive/ | Lead archive endpoint |
Authentication
To access the Lead Archive API, you must authenticate using an API key.
Include the following headers in your request:
| Code Block |
|---|
Authorization: Key=YOUR_KEY Content-Type: application/json |
Request
When making a request, you must post the following JSON object.
| Code Block | ||
|---|---|---|
| ||
{
"insert_leads": true,
"update_leads": true,
"delete_leads": true,
"lead_ids": [
12345,
67890
]
} |
JSON Object key | Datatype | Description |
|---|---|---|
insert_leads | true|false | This feature facilitates the insertion of leads into the vicidial_list_archive table. Leads that are already present in the vicidial_list_archive table will not be inserted again. Use update_leads to ensure the lead data is synchronized for leads that were not inserted. It is recommended to always set this feature to true. |
update_leads | true|false | If a lead is already present in the vicidial_list_archive table, the API will update the lead data with the most recent information retrieved from the vicidial_list table. It is recommended to always set this feature to true for optimal data synchronization. |
delete_leads | true|false | This feature enables the deletion of leads from the vicidial_list table in a safe manner. Before deleting, the API checks if the lead exists in the vicidial_list_archive table and ensure the column data matches vicidial_list table lead. Setting this feature to false will result in leads remaining in the vicidial_list table. |
lead_ids | Interger values | Specify the lead IDs that you wish to archive. Ensure that the number of lead ID values does not exceed 500. |
API always runs operations in the following sequential order.
insert_leads
update_leads
delete_leads
The below CURL request example actions the following:
Insert leads into the vicidial_list_archive table.
Update leads in the vicidial_list_archive table with lead data from the vicidial_list table.
Delete leads from the vicidial_list table. Performs safe delete by checking if the lead exists in the vicidial_list_archive table.
| Code Block | ||
|---|---|---|
| ||
curl -k -X POST https://api.tforge.co.za/vicidial/lead/archive/ \
-H "Authorization: Key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"insert_leads": true,
"update_leads": true,
"delete_leads": true,
"lead_ids": [
12345,
67890
]
}' |
Response
General HTTP response status codes do apply to this API.
HTTP status code - 200
Returns the following successful response If there are no errors with the request or the specified lead IDs. The data will be processed based on the options specified in the JSON object.
| Code Block | ||
|---|---|---|
| ||
{
"success": "lead batch was successfully processed",
"select_count": 1,
"insert_count": 1,
"update_count": 1,
"delete_count": 1,
"status_code": 200
} |
HTTP status code - 432
Returns the following error response if the value passed for insert_leads is not a bool value or no value was provided.
| Code Block | ||
|---|---|---|
| ||
{
"error": "insert_leads must be a boolean value",
"status_code": 432
} |
HTTP status code - 433
Returns the following error response if the value passed for update_leads is not a bool value or no value was provided.
| Code Block | ||
|---|---|---|
| ||
{
"error": "update_leads must be a boolean value",
"status_code": 433
} |
HTTP status code - 434
Returns the following error response if the value passed for delete_leads is not a bool value or no value was provided.
| Code Block | ||
|---|---|---|
| ||
{
"error": "delete_leads must be a boolean value",
"status_code": 434
} |
HTTP status code - 435
Returns the following error response if the value passed for lead_ids is not an integer value or was passed with double quotes.
| Code Block | ||
|---|---|---|
| ||
{
"error": "lead_ids must only contain integer values",
"lead_ids": [
"56712"
],
"status_code": 435
} |
HTTP status code - 436
Returns the following error response if no value was passed for lead_ids.
| Code Block | ||
|---|---|---|
| ||
{
"error": "lead_ids must contain atleast 1 value",
"status_code": 436
} |
HTTP status code - 437
Returns the following error response if the values passed for lead_ids exceed 500 values.
| Code Block | ||
|---|---|---|
| ||
{
"error": "lead_ids cannot exceed 500 values",
"status_code": 437
} |
HTTP status code - 438
Returns the following error response if the values passed for lead_ids contain duplicate values.
| Code Block | ||
|---|---|---|
| ||
{
"error": "lead_ids cannot contain duplicate values",
"lead_ids": [
56928
],
"status_code": 438
} |
HTTP status code - 439
Returns the following error response for any other errors not mentioned above.
| Code Block | ||
|---|---|---|
| ||
{
"error": "Unexpected character encountered while parsing number: s. Path 'lead_ids[97]', line 104, position 5.",
"status_code": 439
} |