Skip to main content
You can see Freespee's Service Status page here

Search

Browse our Knowledge Base

Build a call bidding platform

Nils Höglund
  • Updated

In this example, we will assume that you are running your own price comparison site for mortgages.

Let's say you're already asking your visitors to indicate what type of mortgage they are interested in and, based on that input, your site displays a list of the top five institutes with the best rates. The visitor can then click through into the desired institute's landing page or sign up for more information directly on your page. It would not be surprising if you are even now allowing your customers (the institutes) to bid on the order in which they are displayed in your search result; that is, the commission they pay to your site for supplying leads.

Users seeking new mortgages are very price sensitive, but because of the nature of a mortgage, there is a lot of information required to sign up a new client. It's likely that you've already thought of displaying phone numbers in your search result to help your institute customers to sign up new clients more efficiently, but by doing that you are giving away leads for free. And no one wants to do that.

It usually is where basic call tracking comes in place. But let's face it, call tracking has been around for decades and what you really want is the ability for your customers to bid on calls just as easily as they bid on form sign-ups.

Starting to get a feel for how you could enable bidding on calls from your current platform by using the Freespee API? We'll show you!

1. Create a customer

Since you've already learned how to create a customer, let's simply use the customer “DailyLoans” from previous examples.

2. Create a pricing model

To activate call bidding, you must create at least one pricing model and one campaign. Pricing models are used by campaigns to verify, classify and set a commission for each lead. We must first create a pricing model:

POST /pricing_models
name=MyCPLModel&type=0&unique_caller_time=0&conditions=[{"cost_per_lead":"100.00","min_duration":"10","from_time":"00:00","to_time":"24:00","weekdays":"mon,tue,wed,thu,fri,sat,sun"}]
{
 "pricing_models":[{
  "pricing_model_id":"4b708225-1ccb-4d30-95af-a64d721657c6",
  "name":"MyCPLModel",
  "unique_caller_time":"0",
  "type":"0",
  "conditions":[{
   "cost_per_lead":"100.00",
   "min_duration":"10",
   "from_time":"00:00",
   "to_time":"24:00",
   "weekdays":"mon,tue,wed,thu,fri,sat,sun"
  }],
  "used_by":[]
 }]
}

Okay, so now we've created a type 0 (CPL) pricing model. This customer is willing to pay $100 for a call lasting longer than 10 seconds, all day, any day.

3. Create a campaign

Now we need to create a campaign and attach our freshly created pricing model:

POST /customers/407382/campaigns
name=MyCampaign&pricing_model_id=4b708225-1ccb-4d30-95af-a64d721657c6
{
 "campaigns":{
  "campaign_id":"21",
  "timestamp":"2012-01-13 10:03:53",
  "expire":null,
  "pricing_model_id":"4b708225-1ccb-4d30-95af-a64d721657c6",
  "notify_on_missed_call":"0",
  "notify_on_new_voicemail":"0",
  "vm_divert_all":"0",
  "vm_divert_busy":"0",
  "vm_divert_noanswer":"0",
  "sources":null,
  "partner_campaign_id":null,
  "name":"MyCampaign",
  "email":null,
  "smsnumber":null,
  "vm_greeting_id":null,
  "state":"0"
 }
}

4. Create a source

Now we want to create a source for our customer “DailyLoans”, but since we are doing call bidding, we also attach this source to our campaign:

POST /sources
customer_id=407390&name=CallBidding&phonenr=0890510&campaign_id=21
{
 "sources":[{
  "source_id":"643971",
  "name":"CallBidding",
  "email":null,
  "smsnumber":null,
  "media":null,
  "customer_id":"407390",
  "phonenr":"+46890510",
  "destnr":"+4612345678",
  "timestamp":"2011-11-14 23:00:00",
  "expire":null,
  "created":"2011-10-15 16:09:31",
  "modified":"2011-10-15 16:09:31",
  "class":"0",
  "status":"active",
  "vm_greeting_id":null,
  "notify_on_missed_call":"0",
  "vm_divert_all":"0",
  "vm_divert_busy":"0",
  "vm_divert_noanswer":"0",
  "alt_numbers":[],
  "campaign_id":"21"
 }]
}

Now, what happened? We created a normal source but passed our campaign_id to enable the possibility to do a call bidding. In this case, we choose to have a minimum call duration of 10 seconds and a cost per lead of $100. It means that a call longer than 10 seconds will cost this customer $100. Nice, huh?

5. Numbers on your site

Remember that you previously choose to remove phone numbers from your listing since you would give away leads for free? Since you now are really close to having your own call bidding platform, you show now start putting your Freespee numbers in your search result.

6. Fetch call data records

Okay, so now you've had phone numbers on your site for a day during 2011-10-20. Now we will access the /statistics/cdrs resource with parameter extended=1 to get each call and its details from the API:

GET /statistics/cdrs?customer_id=407382&from_date=2011-10-20&to_date=2011-10-21&extended=1
{
 "total":5,
 "page":0,
 "pagesize":1000,
 "numpages":1,
 "cdrs":[{
  "cdr_id":"816010",
  "start":"2011-10-20 11:29:42",
  "duration":"0",
  "anum":"+46735177xxx",
  "bnum":"+46812345678",
  "cnum":"+46890510",
  "customer_id":"407382",
  "source_id":"643942",
  "custnr":"1412",
  "answered":"0",
  "quarantined":"0",
  "timestamp":"2011-10-19 22:00:00",
  "expire":"2011-10-30 12:27:38",
  "anum_ndc_name":"Sweden, Mobile",
  "media":null,
  "class":"0",
  "voicemail":"0",
  "publisher_id":null,
  "campaign_id":"21",
  "pricing_model_id":"4b708225-1ccb-4d30-95af-a64d721657c6",
  "commission":null,
  "cli_id":null,
  "order_id":null
 },{
  "cdr_id":"816011",
  "start":"2011-10-20 11:29:55",
  "duration":"105",
  "anum":"+46735177xxx",
  "bnum":"+46812345678",
  "cnum":"+46890510",
  "customer_id":"407382",
  "source_id":"643942",
  "custnr":"1412",
  "answered":"1",
  "quarantined":"0",
  "timestamp":"2011-10-19 22:00:00",
  "expire":"2011-10-22 23:29:42",
  "anum_ndc_name":"Sweden, Mobile",
  "media":null,
  "class":"0",
  "voicemail":"0",
  "publisher_id":null,
  "campaign_id":"21",
  "pricing_model_id":"4b708225-1ccb-4d30-95af-a64d721657c6",
  "commission":"100.00",
  "cli_id":null,
  "order_id":null
 },{
  "cdr_id":"816012",
  "start":"2011-10-20 11:37:40",
  "duration":"523",
  "anum":"",
  "bnum":"+46812345678",
  "cnum":"","customer_id":"407382",
  "source_id":"643943",
  "custnr":"1412",
  "answered":"1",
  "quarantined":"0",
  "timestamp":"2011-10-19 22:00:00",
  "expire":null,
  "anum_ndc_name":null,
  "media":null,
  "class":"0",
  "voicemail":"0",
  "publisher_id":null,
  "campaign_id":"21",
  "pricing_model_id":"4b708225-1ccb-4d30-95af-a64d721657c6",
  "commission":"100.00",
  "cli_id":null,
  "order_id":null
 },{
  "cdr_id":"816014",
  "start":"2011-10-20 11:54:12",
  "duration":"12",
  "anum":"+46735177xxx",
  "bnum":"+46812345678",
  "cnum":"+46890510",
  "customer_id":"407382",
  "source_id":"643943",
  "custnr":"1412","answered":"1",
  "quarantined":"0",
  "timestamp":"2011-10-19 22:00:00",
  "expire":null,"anum_ndc_name":"Sweden, Mobile",
  "media":null,
  "class":"0",
  "voicemail":"0",
  "publisher_id":null,
  "campaign_id":"21",
  "pricing_model_id":"4b708225-1ccb-4d30-95af-a64d721657c6",
  "commission":"100.00",
  "cli_id":null,
  "order_id":null
 },{
  "cdr_id":"816015",
  "start":"2011-10-20 13:25:54",
  "duration":"230",
  "anum":"+46735177xxx",
  "bnum":"+46812345678",
  "cnum":"+46890510",
  "customer_id":"407382",
  "source_id":"643956",
  "custnr":"1412",
  "answered":"1",
  "quarantined":"0",
  "timestamp":"2011-10-19 22:00:00",
  "expire":null,
  "anum_ndc_name":"Sweden, Mobile",
  "media":null,
  "class":"0",
  "voicemail":"0",
  "publisher_id":null,
  "campaign_id":"21",
  "pricing_model_id":"4b708225-1ccb-4d30-95af-a64d721657c6",
  "commission":"100.00",
  "cli_id":null,
  "order_id":null
 }]
}

Right, so again we got our 5 calls from 2011-10-20 for our customer, but note that this time the commission for each call values are also passed along to us. Again, with a short code snippet, we could aggregate this data:

<?php
$json = json_decode($input);
 
$leads = 0;
$commission = 0;
foreach ($json->cdrs as $k => $v) {
 if ($v->answered == 1 && $v->commission !== null) {
  $leads++;
  $commission += $v->commission;
 }
}
 
printf ("Customer DailyLoans have had %s verified leads and should pay a commission of $%s.", $leads, $commission);
?>

This would result in:

Customer DailyLoans have had 4 verified leads and should pay a commission of $400.

Isn't that just great?

7. Updating cost per call

Alright, so now your customers have started to bid against each other. But how would you update the Freespee platform with your new bidding price? The answer is simple, just update the cost per lead for your pricing model:

PUT /pricing_models/4b708225-1ccb-4d30-95af-a64d721657c6'
conditions=[{"cost_per_lead":"150.00"}]
{
 "pricing_models":[{
  "pricing_model_id":"4b708225-1ccb-4d30-95af-a64d721657c6",
  "name":"MyCPLModel",
  "unique_caller_time":"0",
  "type":"0",
  "conditions":[{
   "cost_per_lead":"150.00",
   "min_duration":"10",
   "from_time":"00:00",
   "to_time":"24:00",
   "weekdays":"mon,tue,wed,thu,fri,sat,sun"
  }],
  "used_by":[{
   "id":"21",
   "name":"MyCampaign"
  }]
 }]
}

8. Enable bidding

That's the basics for call bidding. Now you can introduce calls as a currency to your site!