Vicidial Lead Archiving API Documentation

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.

API will be set by TForge to operate outside of office hours only.

Endpoint

Server address will be provided by TForge.

Use the following endpoint to initiate your request:

Method	Endpoint	Description
POST	https://server/vicidial/lead/archive/	Lead archive endpoint

Authentication

API key will be provided by TForge.

To access the Lead Archive API, you must authenticate using an API key.

Include the following headers in your request:

Authorization: Key=YOUR_API_KEY
Content-Type: application/json

Request

The API consistently executes operations in the following sequential order:

insert_leads
update_leads
delete_leads

When making a request, you must post the following JSON object.

{
  "insert_leads": true,
  "update_leads": true,
  "delete_leads": true,
  "lead_ids": [
    0,
    1
  ]
}

JSON Object Key	Datatype	Description
insert_leads	true \| false	This feature enables 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	This feature enables the updation of leads. If a lead is already present in the vicidial_list_archive table, the API will update the lead data with the most recent lead 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 if the data matches the vicidial_list table lead. Setting this feature to false will result in leads remaining in the vicidial_list table.
lead_ids	Integer values	Specify the lead IDs that you wish to archive. Ensure that the number of lead ID values does not exceed 500.

CURL request example:

Disable SSL verification upon sending the request.

Insert leads into the vicidial_list_archive table. Ignores leads that exist in 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 and if the column data matches the vicidial_list table lead.

curl -k -X POST https://server/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": [
        0,
        1
      ]
    }'

Response

The API follows general HTTP response status codes. In addition to the status code included in the JSON response, you can also rely on the HTTP status code returned by the response.

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 option values specified in the request JSON object.

{
  "success": "lead batch was successfully processed",
  "select_count": 1,
  "insert_count": 1,
  "update_count": 0,
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "error": "lead_ids must only contain integer values",
  "lead_count": 1,
  "lead_ids": [
    "0"
  ],
  "status_code": 435
}

HTTP status code - 436

Returns the following error response if no value was passed for lead_ids.

{
  "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.

{
  "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.

{
  "error": "lead_ids cannot contain duplicate values",
  "lead_count": 1,
  "lead_ids": [
    0
  ],
  "status_code": 438
}

HTTP status code - 439

Returns the following error response if the values passed for lead_ids do not exist in the vicidial_list table.

{
  "error": "specified leads do not exist",
  "lead_count": 1,
  "values": [
    0
  ],
  "status_code": 439
}

HTTP status code - 440

Returns the following error response for any other errors not mentioned above.

{
  "error": "Unexpected character encountered while parsing number: s. Path 'lead_ids[97]', line 104, position 5.",
  "status_code": 440
}

HTTP status code - 441

Returns the following error response if the API was executed during office hours.

{
  "error": "api executed during office hours time condition",
  "status_code": 441
}

Conclusion

If you encounter any issues with the API, please log a ticket with our support department. You can also contact us at 010-035-0909 or email our dedicated Customer Experience team at cex@teleforge.co.za. Please ensure to include your ticket number for reference and expedited support.