Callbox

The Callbox Developer Hub

Welcome to the Callbox developer hub. You'll find comprehensive guides and documentation to help you start working with Callbox as quickly as possible, as well as support if you get stuck. Let's jump right in!

Guides
Suggest Edits

Introduction

 

usecallbox.com API Version 1.0 documentation.

The Callbox API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

 
Suggest Edits

Authentication

 

Authenticate your account when using the API by including your API ID and your secret API key in the http request header.

You can retrieve your API keys in under My Account Tab > Api Section

Authentication to the API is performed via HTTP Basic Auth. Provide your API ID and API key as the basic auth username and password values respectively.

The Authorization field is constructed as follows:

1. The API ID and API Key are combined  with a single colon. (:)
       example: acc_123456789012345678901234567890:a1b2c3d4e5f6g7h8i9j0k1l2m3n4opqrst

2. The resulting string is encoded into an octet sequence.

3. The resulting string is encoded using a variant of Base64.

4. The authorization method and a space is then prepended to the encoded string, separated with 
    a space (e.g. "Basic ").
-H "Authorization: Basic IDKjXzYyODE4YjYzNaZjY2RlNjA4OWQ5MGRiYTZkM2FhMzlmOjE4P"

All API request must include API ID and API Key in the HTTP Authorization header

 
Suggest Edits

Pagination

 

All top-level API resources have support for pagination. These API calls share a common structure, taking one parameters: page which specifies the page of resource you would like to receive.

The Pagination details is included in dictionary response with the meta property.

{
	...,
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 4
  }
}

The pagination keys are:
current_page: The current page of the resource
total_pages: The total number of pages
total_count: The total number of resources

 
 
 
Suggest Edits

Call list

GET /api/v1/publisher/calls

Get list of calls

 

Basic Auth

 Authentication is required for this endpoint.
gethttp://usecallbox.com/api/v1/publisher/calls

Query Params

from
date
required

Search for calls that started after this datetime. The time is formatted in 24 hour format. (yyyy-mm-dd hh:mm:ss)

to
date
required

Search for calls that started before this datetime. The time is formatted in 24 hour format. (yyyy-mm-dd hh:mm:ss)

source_number
string

Search for calls which originated from this caller's number

publisher_number
string

Search for calls which originate from this publisher number

campaign_id
string

Search for calls belonging to this campaign

status
string

Search for calls with a given state: Possible states are active, dropped, qualified, unqualified, fallbacked

Returns
A dictionary with a data property that contains an array of up to limit calls, starting after from. Each entry in the array is a separate call object. If no more calls are available, the resulting array will be empty.

curl --request GET \
  --url 'http://usecallbox.com/api/v1/publisher/calls?from=from&to=2017-06-26%2023%3A59%3A50'
var request = require("request");

var options = { method: 'GET',
  url: 'http://usecallbox.com/api/v1/publisher/calls',
  qs:
   { from: 'from',
     to: '2017-06-26 23:59:50' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://usecallbox.com/api/v1/publisher/calls?from=from&to=2017-06-26%2023%3A59%3A50")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://usecallbox.com/api/v1/publisher/calls?from=from&to=2017-06-26%2023%3A59%3A50");

xhr.send(data);
import requests

url = "http://usecallbox.com/api/v1/publisher/calls"

querystring = {"from":"from","to":"2017-06-26 23:59:50"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "data": [
  {
    "id": "f43e00af-4ae1-4d3c-a86f-331334327063",
    "source_phone_number": "US Auto Insurance",
    "campaign_title": "Super adipisci - 3",
    "publisher_number": "+18309039201",
    "connected_duration": 766,
    "called_at": "2019-03-09T18:33:51 Z",
    "payout": 10.0,
    "status": "Qualified"
  },
  {
    "id": "0fe538ca-3dbe-4586-a22e-20ddcf31fe75",
    "source_phone_number": "+16329488360",
    "campaign_title": "LA Plumber Services",
    "publisher_number": "+17007317337",
    "connected_duration": 324,
    "called_at": "2019-03-08T18:33:51 Z",
    "payout": 9.0,
    "status": "Qualified"},
    {  
      "id": "daaab6da-ea9e-482f-9e2c-f42343e882ac",
      "source_phone_number": "+13001328096",
      "campaign_title": "US Auto Insurance",
      "publisher_number": "+18327362273",
      "connected_duration": 231,
      "called_at": "2019-03-08T17:33:51 Z",
      "payout": 0.0,
      "status": "Unqualified"
    },
    {  
      "id": "93a3bf11-8a36-4943-8a76-41b2a176db75",
      "source_phone_number": "+17928494121",
      "campaign_title": "US Auto Insurance",
      "publisher_number": "+18309039201",
      "connected_duration": 42,
      "called_at": "2019-03-06T18:33:51 Z",
      "payout": 7.0,
      "status": "Qualified"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 4
  }
}
 
Suggest Edits

Campaigns

 
 
 
Suggest Edits

Campaign list

GET /api/v1/publisher/campaigns

Retrieves approved publisher campaigns

 

Basic Auth

 Authentication is required for this endpoint.
gethttp://usecallbox.com/api/v1/publisher/campaigns

Returns
A dictionary with a data property that contains an array of up to limit campaigns. Each entry in the array is a separate campaign object. If no more campaigns are available, the resulting array will be empty.

curl --request GET \
  --url http://usecallbox.com/api/v1/publisher/campaigns
var request = require("request");

var options = { method: 'GET',
  url: 'http://usecallbox.com/api/v1/publisher/campaigns' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://usecallbox.com/api/v1/publisher/campaigns")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://usecallbox.com/api/v1/publisher/campaigns");

xhr.send(data);
import requests

url = "http://usecallbox.com/api/v1/publisher/campaigns"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "data": [
  {
    "id": "ad12fde0-f711-46b4-b779-e1d1f125d251",
    "title": "LA Plumber Services",
    "pool_id": "14b9abe6-4365-42ca-99d7-cf37669918d3",
    "capacity": 0,
    "dids": ["+18309039201","+18327362273"]
  },
  {
    "id": "805fad05-c1f4-4130-8148-bc3627fb8050",
    "title": "LA Plumber Services",
    "pool_id": "af5e766a-28ae-4187-91ce-cdb6b532fafa",
    "capacity": 3,
    "dids": ["+17007317337"]
  }
 ],
 "meta": {
   "current_page": 1,
   "total_pages": 1,
   "total_count": 2
 }
}
 
 
 
Suggest Edits

Create Lead

POST https://labs.usecallbox.com/api/leads

Create a lead in the system

 
posthttps://labs.usecallbox.com/api/leads

Body Params

source_id
string
required

Source ID given to you by your manager, i.e. f475407b-a30f-4052-80dc-ea6cc409bc5f

payload
object

Contains a hash of key/value pairs describing the lead

 
payload.tag
string
required

Add a tag to your lead

payload.number
string
required

Lead's phone numbe

payload.name
string

Lead's name

 
$.post('https://labs.usecallbox.com/api/lead/',{
  	payload: {
  		name: "John Doe",
	  	number: "1234567890",
  		tag: "cb-labs-test",
  	},
  	source_id: "f475407b-a30f-4052-80dc-ea6cc409bc5f",
  }, function(data) {
    console.log(data);
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://labs.usecallbox.com/api/lead")
header = {'Content-Type' => 'application/json', 'Accept' => 'application/json'}
data = {
  source_id: "f475407b-a30f-4052-80dc-ea6cc409bc5f",
  payload:{
    name: "John Doe",
    number: "1234567891",
    tag: "cb-labs-test"
    }
  }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = data.to_json

# Send the request
response = http.request(request)
A binary file was returned

You couldn't be authenticated

{
    "success": "store"
}