CallFire Solutions

05. Search Available Numbers

Follow

Before you can assign a number to your account, you need to find ones which are available. To do so, you need to use the /number/search endpoint to find a set of numbers which are available. The endpoint takes a series of parameters which you can find in the table below.

Endpoint

https://www.callfire.com/api/1.1/rest/number/search

Request Type

GET

Request Headers

Content-Type application/xml
Accepts application/xml

Request Arguments

ArgumentTypeDescription
Prefix string A 4-7 digit phone number prefix. A full telephone number is made up of a country code, area code, prefix, and subscriber number, for example, 1 (378) 400-1234.
City string The full name of a US city, such as Phoenix.
State string A two character state abbreviation code, such as AZ for Arizona.
Zipcode string A 5 digit, US, zip code, such as 85001 which is located in Phoenix, Arizona.
Country string An international 2 digit country code.
Lata string A 3 digit US LATA code
RateCenter string The RateCenter to use. It’s important to choose the right Rate Center, because when numbers are assigned from Rate Centers local to the premises they’ll be used at they will be deemed as local. Otherwise, there’s the risk of creating a long distance number and incurring long distance call charges.
Latitude float Filter the results returned by latitude. For example: 33.5443.
Longitude float Filter the results returned by longitude. For example: -112.049.
TimeZone string The timezone of the city which the RateCenter is in. The values which can be supplied are any that are supported by the java.util.TimeZone TimeZone.getTimeZone method. Essentially this is either an abbreviation such as “PST”, a full name such as “America/Los_Angeles”, or a custom ID such as “GMT-8:00”. Note that the support of abbreviations is for JDK 1.1.x compatibility only and full names should be used.
TollFree boolean boolean.
Whether to search for toll-free numbers or not.
Count long required - int.
The maximum number of records to return.

Example Request

Curl

curl -i https://www.callfire.com/api/1.1/rest/number/search?Count=5&City=Phoenix&State=AZ&Country=US&Lata=666 \
  -H "Accept: application/xml" \
  --user <YOUR_LOGIN>:<YOUR_PASSWORD>

PHP SDK

<?php

require 'vendor/autoload.php';

use CallFire\Api\Rest\Request,                                                                                                                                                                                                              
    CallFire\Api\Rest\Response;

// Initialize the CallFire REST Api Client
$callfireNumberClient = CallFire\Api\Client::Rest(
    'YOUR_LOGIN', 'YOUR_PASSWORD', 'Number'
);

// Initialize a \CallFire\Api\Rest\Request\SearchAvailableNumbers object to search
// with city, state, country and count parameters
$searchAvailableNumbers = new Request\SearchAvailableNumbers();
$searchAvailableNumbers->setCity('Los Angeles')
        ->setCount(12)
        ->setState('CA')
        ->setCountry('US')
        ->setLata('666');

// Make the request against the endpoint
$response = $callfireNumberClient->SearchAvailableNumbers(
    $searchAvailableNumbers
);

// Marshall the response into a \CallFire\Api\Rest\Response\ResourceList object,
// which contains a list of \CallFire\Common\Resource\Number objects
$result = $callfireNumberClient::response($response);

Node.js

var querystring = require('querystring');
var https = require('https');

// Create the query string to pass to the request      
var endpoint = '?' + querystring.stringify({ 
    Count: 5,
    City: 'Los Angeles',
    State: 'CA',
    Country: 'US',
    Lata: '666'
});

// Initialize the request parameters
var options = {
    host: 'www.callfire.com',
    path: '/api/1.1/rest/number/search',
    query: endpoint,
    // Specify the authorization credentials
    auth: 'YOUR_LOGIN' + ':' + 'YOUR_PASSWORD'  
};
  
// Initialize a GET request 
var req = https.get(options, function(res) {
        // Print the response payload to stdout, if available
    res.on('data', function(d) {
        process.stdout.write(d);
    });
}).on('error', function(e) {
    console.error(e);
});

req.end();

Go

package main

import (
    "fmt"
    "github.com/google/go-querystring/query"
    "github.com/settermjd/callfire"
    "io/ioutil"
    "log"
)

func main() {
    // Initialise the search parameters, which will form the query string
    opt := callfire.RequestOptions{
        Count: 5, City: "Los Angeles", State: "CA", Country: "US", Lata: "666"
    }
    v, _ := query.Values(opt)

    // Make a GET request against the endpoint
    requestOptions := callfire.CallFireRequestOptions{
        Url:           "https://www.callfire.com/api/1.1/rest/number/search?",
        Login:         "YOUR_LOGIN",
        Secret:        "YOUR_PASSWORD",
        ReqType:       "GET",
        RequestOptions: v.Encode(),
    }
    client, req := callfire.InitHttpClient(requestOptions)
    
    resp, err := client.Do(req)

    if err != nil {
        log.Fatal(err)
    }

    // Retrieve the body of the response
    body, err := ioutil.ReadAll(resp.Body)
    resp.Body.Close()

    if err != nil {
        log.Fatal(err)
    }

    // Dump the response
    fmt.Printf("%s", body)
}

Example Response

Here are two possible responses which can be received from calls to this endpoint.

Successful, Without Results

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceList xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource" totalResults="0"/>

Successful, With Results

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceList xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource" totalResults="2">
      <Number>
            <Number>19284826590</Number>
            <NationalFormat>(928) 482-6590</NationalFormat>
            <TollFree>false</TollFree>
            <Region>
                  <Prefix>1928482</Prefix>
                  <City>PHOENIX</City>
                  <State>AZ</State>
                  <Zipcode>85013</Zipcode>
                  <Country>US</Country>
                  <Lata>666</Lata>
                  <RateCenter>GILA BEND</RateCenter>
                  <Latitude>33.4959</Latitude>
                  <Longitude>-112.068</Longitude>
                  <TimeZone>America/Phoenix</TimeZone>
            </Region>
      </Number>
      <Number>
            <Number>19284826588</Number>
            <NationalFormat>(928) 482-6588</NationalFormat>
            <TollFree>false</TollFree>
            <Region>
                  <Prefix>1928482</Prefix>
                  <City>PHOENIX</City>
                  <State>AZ</State>
                  <Zipcode>85013</Zipcode>
                  <Country>US</Country>
                  <Lata>666</Lata>
                  <RateCenter>GILA BEND</RateCenter>
                  <Latitude>33.4959</Latitude>
                  <Longitude>-112.068</Longitude>
                  <TimeZone>America/Phoenix</TimeZone>
            </Region>
      </Number>
</r:ResourceList>

You can see in the response a range of information. Likely most essential is the Number/Number element. You can also see the region information allocated to that number.

Have more questions? Submit a request

Comments