Getting Started
Introduction
Welcome to SquadIQ API! SquadIQ provides businesses with an omni-channel outreach engine + distributed team of expert calling reps. Our platform qualifies your Leads faster and provides more sales opportunities. You can use this API to access our API endpoints such as Leads API to add Leads to your campaigns or Response API to know status of your Leads.
Prerequisites
Throughout the documentation certain words will be used to describe relevant parties involved. The definitions are given down below.
Customer/Client/You
Refers to the individual/organisation who’ll be using SquadIQ’s services to reach out to their potential customers.
Lead
Lead refers to the person(your potential customer) that SquadIQ performs the outreach to. All the necessary details of the lead are passed on to SquadIQ’s backend which will be used in the process of the reach out.
Campaign
Campaign refers to the flow that you have pre-configured on SquadIQ’s backend as per your business needs. Any campaign would define a sequence of events and every lead associated to that campaign would follow these sequence of events. Reach out to voicesales@squadiq.in
to create your campaign.
Leads
Create Leads
import requests
url = "https://api.squadiq.in/api/v4/leads/create/{campaign_id}/"
payload = [
{
"lead_id": "uniqueleadid1",
"phone_number": "{valid phone number}",
"contact_name": "John Doe",
"{custom_field_1}": "{custom_value}",
"{custom_field_2}": "{custom_value}"
},
{
"lead_id": "uniqueleadid2",
"phone_number": "{valid phone number}",
"contact_name": "John Smith",
"{custom_field_1}": "{custom_value}",
"{custom_field_2}": "{custom_value}"
}
]
headers = {
"Authorization": "Bearer test_token",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
response.json()
curl 'https://api.squadiq.in/api/v4/leads/create/{campaign_id}/' \
-H 'Authorization: Bearer test_token' \
-H 'Content-Type: application/json' \
--data-binary $'[{"lead_id": 1, "phone_number": "{valid phone number}", \
"contact_name": "John Doe", \
"{custom_field_1}": "{custom_value}", "{custom_field_2}": "{custom_value}"}]'
Json payload example:
{
"lead_id":"XXXXXXXX",
"phone_number":"XXXXXXXXXX",
"contact_name": "John Doe",
"is_KYC":"YES",
"product_plan":"Lite",
"is_squadlead":true,
}
In the above example, is_KYC, product_plan, is_squadlead are custom fields.
Use this API to create new Leads in your preconfigured SquadIQ Campaign.
HTTP Request
POST https://api.squadiq.in/api/v4/leads/create/{campaign_id}/
Request Headers
Parameter | Value |
---|---|
Content-Type | application/json |
Authorization | Bearer {access_token} |
You will have to replace {access_token}
with access token you get from SquadIQ Dashboard
Path Parameters
Parameter | Required | Description |
---|---|---|
{campaign_id} |
True | Unique Identifier of the Campaign (You can get your campaign_id by contacting voicesales@squadiq.in ) |
Request Body Parameters
Parameter | Required | Description |
---|---|---|
lead_id |
True | Unique Identifier of the Lead for the campaign. |
phone_number |
True | A valid indian phone number of the Lead. |
contact_name |
True | Name of the Lead being contacted |
custom_field |
True | Any data in key value pair about the lead required for the campaign |
custom_field |
True | Any data in key value pair about the lead required for the campaign |
Response
201 Created
if the leads were successfully created.
403 Forbidden
if the request authentication was not successful.
400 Bad Request
if the request payload had some error. Specific error is provided in the response.
Get Leads
import requests
url = "https://api.squadiq.in/api/v4/leads/responses/{campaign_id}/?page_size=1"
headers = {"Authorization": "Bearer test_token"}
params = {
"lead_id": "test_lead_id"
}
response = requests.get(url, params=params, headers=headers)
response.json()
curl
-H "Authorization: Bearer test_token"
-H 'Content-Type: application/json' \
-X GET "https://api.squadiq.in/api/v4/leads/responses/{campaign_id}/?lead_id=test_lead_id&page_size=1"
The above script returns JSON structured like this:
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"phone_number": "+91xxxxxxxxxx",
"lead_id": "test_lead_id",
"latest_recording_url": "https://www.squadiq.in/",
"campaign_id": "{campaign_id}",
"latest_called_at": "2018-12-03T14:36:38+00:00",
"lead_outcome": "Connected : Objective Met",
"processed_at": "2018-12-03T14:37:54+00:00",
"contact_name": "John Doe",
"created_at": "2018-12-03T14:36:01+00:00",
"lead_responses": {
"response_key_1": "response_value_1",
"response_key_2": "response_value_2",
"response_key_3": "response_value_3"
}
}
]
}
Use this API to get information about a Lead/Leads that has been processed by SquadIQ.
HTTP Request
GET https://api.squadiq.in/api/v4/leads/responses/{campaign_id}/
Request Content-Type
application/json
Request Headers
Parameter | Value |
---|---|
Content-Type |
application/json |
Authorization |
Bearer {access_token} |
You will have to replace {access_token}
with access token you get from SquadIQ Dashboard
Request Path Parameters
Parameter | Required | Description |
---|---|---|
{campaign_id} |
True | Unique Identifier of the Campaign (You can get your campaign_id by contacting voicesales@squadiq.in ) |
Request Query Parameters
Parameter | Required | Default | Description |
---|---|---|---|
lead_id |
False | - | Unique Identifier of the Lead for the campaign. |
processed_after |
False | - | Epoch timestamp |
processed_before |
False | - | Epoch timestamp |
page |
False | - | Page number to return |
page_size |
False | 100 | Number of leads to return per page |
Response Structure
Key | Description |
---|---|
lead_id |
Unique Identifier of the Lead for the campaign. |
phone_number |
Phone number of the Lead |
contact_name |
Name of the Lead |
created_at |
Epoch timestamp |
campaign_id |
Campaign ID which you sent in the URL too |
latest_recording_url |
Latest call recording of the conversation with the lead. |
latest_called_at |
Date and time at which latest call was made to the lead. ISOFORMAT(%Y-%m-%dT%H:%M:%S ) |
lead_outcome |
Outcome for the lead. |
processed_at |
Date and time at which the lead was processed. ISOFORMAT(%Y-%m-%dT%H:%M:%S ) |
lead_responses |
JSON object containing responses captured for the lead as key-value pairs. |
Response Status Code
200 OK
for a successful request.
403 Forbidden
if the request authentication was not successful.
400 Bad Request
if the request payload had some error. Specific error is provided in the response.
Lead Processed Webhook
SquadIQ also supports a webhook that is triggered when the lead is processed and the necessary information is sent through this webhook(hosted on your backend). This API endpoint of yours is to be shared with our Ops team during the process of campaign configuration.
Payload of webhook is of the following format
{
"phone_number": "+91xxxxxxxxxx",
"lead_id": "test_lead_id",
"latest_recording_url": "https://www.squadiq.in/",
"campaign_id": "{campaign_id}",
"latest_called_at": "2018-12-03T14:36:38+00:00",
"lead_outcome": "Connected : Objective Met",
"processed_at": "2018-12-03T14:37:54+00:00",
"contact_name": "John Doe",
"created_at": "2018-12-03T14:36:01+00:00",
"lead_responses": {
"response_key_1": "response_value_1",
"response_key_2": "response_value_2",
"response_key_3": "response_value_3"
}
}
HTTP POST Request
POST https://your_webhook_end_point_here
Webhook Headers
Parameter | Value |
---|---|
Content-Type |
application/json |
Webhook Payload Structure
Key | Description |
---|---|
lead_id |
Unique Identifier of the Lead for the campaign. |
phone_number |
Phone number of the Lead |
contact_name |
Name of the Lead |
created_at |
Epoch timestamp |
campaign_id |
Campaign ID which you sent in the URL too |
latest_recording_url |
Latest call recording of the conversation with the lead. |
latest_called_at |
Date and time at which latest call was made to the lead. ISOFORMAT(%Y-%m-%dT%H:%M:%S ) |
lead_outcome |
Outcome for the lead. |
processed_at |
Date and time at which the lead was processed. ISOFORMAT(%Y-%m-%dT%H:%M:%S ) |
lead_responses |
JSON object containing responses captured for the lead as key-value pairs. |
Response Status Code
We expect following responses status code for the webhook requests
201 OK
for a successful webhook request.
403 Forbidden
if the request authentication was not successful.
400 Bad Request
if the request payload had some error. Specific error is provided in the response.
Disable one or more leads.
import requests
url = "https://api.squadiq.in/api/v4/leads/disable/{campaign_id}/"
payload = [
{"lead_id": "uniqueleadid1"},
{"lead_id": "uniqueleadid2"}
]
headers = {
"Authorization": "Bearer test_token",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
response.json()
curl 'https://api.squadiq.in/api/v4/leads/disable/{campaign_id}/' \
-H 'Authorization: Bearer test_token' \
-H 'Content-Type: application/json' \
--data-binary $'{"lead_id": 1}'
Use this API to disable a Lead in your SquadIQ Campaign. Disabling the lead will stop all reach-outs to that lead.
HTTP Request
POST https://api.squadiq.in/api/v4/leads/disable/{campaign_id}/
Request Headers
Parameter | Value |
---|---|
Content-Type |
application/json |
Authorization |
Bearer {access_token} |
You will have to replace {access_token}
with access token you get from SquadIQ Dashboard
Request Path Parameters
Parameter | Required | Description |
---|---|---|
{campaign_id} |
True | Unique Identifier of the Campaign (You can get your campaign_id by contacting voicesales@squadiq.in ) |
Request Body Parameters
Parameter | Required | Description |
---|---|---|
lead_id |
True | Unique Identifier of the Lead |
Response Status Code
201 OK
for a successful request.
403 Forbidden
if the request authentication was not successful.
400 Bad Request
if the request payload had some error. Specific error is provided in the response.
Delete a lead
import requests
url = "https://api.squadiq.in/api/v4/leads/delete/{campaign_id}/"
payload = {
"lead_id": "uniqueleadid1"
}
headers = {
"Authorization": "Bearer test_token",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
response.json()
curl 'https://api.squadiq.in/api/v4/leads/delete/{campaign_id}/' \
-H 'Authorization: Bearer test_token' \
-H 'Content-Type: application/json' \
--data-binary $'{"lead_id": "uniqueleadid1"}'
Use this API to delete all Personally Identifiable Information (PII) of a Lead from our platform including the data collected by us on the lead during the process of reach-out. If the lead is in-process, all reach-outs to it would be stopped.
HTTP Request
POST https://api.squadiq.in/api/v4/leads/delete/{campaign_id}/
Request Headers
Parameter | Value |
---|---|
Content-Type |
application/json |
Authorization |
Bearer {access_token} |
You will have to replace {access_token}
with access token you get from SquadIQ Dashboard
Request Path Parameters
Parameter | Required | Description |
---|---|---|
{campaign_id} |
True | Unique Identifier of the Campaign (You can get your campaign_id by contacting voicesales@squadiq.in ) |
Request Body Parameters
Parameter | Required | Description |
---|---|---|
lead_id |
True | Unique Identifier of the Lead |
Response Status Code
202 Accepted
for a successful request.
403 Forbidden
if the request authentication was not successful.
404 Not Found
if the given lead_id doesn't exist on our platform.
400 Bad Request
if the request payload had some error. Specific error is provided in the response.
Update a lead
import requests
url = "https://api.squadiq.in/api/v4/leads/update/{campaign_id}/"
payload = {
"lead_id": "uniqueleadid1",
"phone_number": "{new_valid phone number}",
"{custom_field_1}": "{new_custom_value}",
}
headers = {
"Authorization": "Bearer test_token",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
response.json()
curl -i -X PATCH 'https://api.squadiq.in/api/v4/leads/update/{campaign_id}/' \
-H 'Authorization: Bearer test_token' \
-H 'Content-Type: application/json' \
--data '{"lead_id": "uniqueleadid1", "phone_number": "{valid phone number}", "{custom_field}": "{custom_value}"}'
You can use this endpoint to update detail of the lead, which has been previously created using the create lead endpoint.
HTTP Request
PATCH https://api.squadiq.in/api/v4/leads/update/{campaign_id}/
Request Headers
Parameter | Value |
---|---|
Content-Type |
application/json |
Authorization |
Bearer {access_token} |
You will have to replace {access_token}
with access token you get from SquadIQ Dashboard
Request Path Parameters
Parameter | Required | Description |
---|---|---|
{campaign_id} |
True | Unique Identifier of the Campaign (You can get your campaign_id by contacting voicesales@squadiq.in ) |
Request Body Parameters
Parameter | Required | Description |
---|---|---|
lead_id |
True | Unique Identifier of the Lead, This value cannot be changed. |
phone_number |
False | A valid indian phone number of the Lead. |
contact_name |
False | Name of the Lead being contacted |
custom_field |
False | Any data in key value pair about the lead required for the campaign |
Response Status Code
200 OK
for a successful request.
403 Forbidden
if the request authentication was not successful.
404 Not Found
if the given lead_id doesn't exist on our platform.
Mark a lead converted
import requests
url = "https://api.squadiq.in/api/v4/leads/convert/{campaign_id}/"
payload = {
"lead_id": "uniqueleadid1",
"detail": "{conversion detail}",
}
headers = {
"Authorization": "Bearer test_token",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
response.json()
curl -i 'https://api.squadiq.in/api/v4/leads/convert/{campaign_id}/' \
-H 'Authorization: Bearer test_token' \
-H 'Content-Type: application/json' \
--data '{"lead_id": "uniqueleadid1", "detail": "{conversion_detail}"}'
This endpoint can be used to mark a lead as end converted(reached the desired outcome) from your side.
HTTP Request
POST https://api.squadiq.in/api/v4/leads/convert/{campaign_id}/
Request Headers
Parameter | Value |
---|---|
Content-Type |
application/json |
Authorization |
Bearer {access_token} |
You will have to replace {access_token}
with access token you get from SquadIQ Dashboard
Request Path Parameters
Parameter | Required | Description |
---|---|---|
{campaign_id} |
True | Unique Identifier of the Campaign (You can get your campaign_id by contacting voicesales@squadiq.in ) |
Request Body Parameters
Parameter | Required | Description |
---|---|---|
lead_id |
True | Unique Identifier of the Lead |
detail |
True | code string representing why the conversion happened (max 32 chars) |
Response Status Code
200 OK
for a successful request.
403 Forbidden
if the request authentication was not successful.
404 Not Found
if the given lead_id doesn't exist on our platform.
Status and Errors
The SquadIQ API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Authentication failed. API credentials are incorrect. |
403 | Forbidden -- You do not have permission to perform this action. |
404 | Not Found |
405 | Method Not Allowed -- You tried to access an endpoing with an invalid method. |
429 | Too Many Requests -- You hit a rate limit! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Rate Limiting
Only 100 hits are allowed per minute for a business. Specific error is provided in the response if the rate limit exceeds. NOTE: You can increase your rate limit by contacting voicesales@squadiq.in