NAV Navbar
shell python

Getting Started

Introduction

Welcome to SquadStack API! SquadStack 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 SquadStack’s services to reach out to their potential customers.

Lead

Lead refers to the person(your potential customer) that SquadStack performs the outreach to. All the necessary details of the lead are passed on to SquadStack’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 SquadStack’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@squadstack.com to create your campaign.

Leads

Create Leads

import requests

url = "https://api.squadstack.com/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.squadstack.com/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 SquadStack Campaign.

HTTP Request

POST https://api.squadstack.com/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 SquadStack Dashboard

Path Parameters

Parameter Required Description
{campaign_id} True Unique Identifier of the Campaign (You can get your campaign_id by contacting voicesales@squadstack.com)

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.

Lead Processed Webhook

SquadStack 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.squadstack.com/",
    "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.squadstack.com/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.squadstack.com/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 SquadStack Campaign. Disabling the lead will stop all reach-outs to that lead.

HTTP Request

POST https://api.squadstack.com/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 SquadStack Dashboard

Request Path Parameters

Parameter Required Description
{campaign_id} True Unique Identifier of the Campaign (You can get your campaign_id by contacting voicesales@squadstack.com)

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.squadstack.com/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.squadstack.com/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.squadstack.com/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 SquadStack Dashboard

Request Path Parameters

Parameter Required Description
{campaign_id} True Unique Identifier of the Campaign (You can get your campaign_id by contacting voicesales@squadstack.com)

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.squadstack.com/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.squadstack.com/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.squadstack.com/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 SquadStack Dashboard

Request Path Parameters

Parameter Required Description
{campaign_id} True Unique Identifier of the Campaign (You can get your campaign_id by contacting voicesales@squadstack.com)

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.squadstack.com/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.squadstack.com/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.squadstack.com/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 SquadStack Dashboard

Request Path Parameters

Parameter Required Description
{campaign_id} True Unique Identifier of the Campaign (You can get your campaign_id by contacting voicesales@squadstack.com)

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 SquadStack 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@squadstack.com