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