CallFire Solutions

02. List Numbers Owned By Your Account

Follow

This endpoint returns, based on the request arguments supplied, all numbers assigned to an account. All of the request arguments are optional; if none are supplied, then all numbers listed on the account will be returned, up to a limit of 1,000. If any request arguments are supplied, any numbers not matching these criteria will be filtered out.

Endpoint

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

Request Type

GET

Request Headers

Content-Type application/xml
Accepts application/xml

Returns

If successful, the request returns an XML payload containing the phone number entries matching the provided request arguments.

Request Arguments

ArgumentTypeDescription
Max Results long required - Default: 0. The maximum number of results to return.
FirstResult long Default: 0. The starting record number for the next recordset.
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.
LabelName string Labels allow you to organize broadcasts, numbers, calls and texts into groups that make sense for your application. You can attach labels to any of these objects by using LabelNumber or LabelBroadcast. Labels use name as their identifier instead of id.

Note About FirstResult

When using this argument, the totalResults attribute in the XML payload will always display -1. Whereas, when it’s not used, then the total number of results which matched the supplied request arguments will be displayed. If this doesn’t quite make sense, refer to the two examples below.

Requests With Pagination
<r:ResourceList xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource" totalResults="944">
Requests Without Pagination
<r:ResourceList xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource" totalResults="-1">

Note: This is a known bug.

You can see in the examples above the difference in the attribute. We suggest that, if you’re going to implement pagination, first make a request without the FirstResult argument to get the total number of results in the result set, then pass the FirstResult argument to implement pagination of results.

Example Request

Curl

curl -i https://www.callfire.com/api/1.1/rest/number?MaxResults=2&City=Waterford&Lata=738 \
  -H "Accept: application/xml" \
  --user <YOUR_LOGIN>:<YOUR_PASSWORD>

PHP SDK

<?php

// Initialise a \CallFire\Api\Rest\Request\QueryNumbers object for querying
// the API for numbers on the account, specifying the country, state, and city.
$configureNumber = new Request\QueryNumbers();$configureNumber->setCity('Waterford')
    ->setLata('738')
    ->setMaxResults(2);

// Make a request for the numbers, based on the criteria in $configureNumber    
$response = $callfireNumberClient->QueryNumbers($configureNumber);$numbers = $callfireNumberClient::response($response);

Node.js

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

var endpoint = '?' + querystring.stringify({
    City: 'Waterford',
    Lata: '738',
    MaxResults: '2',
});
// Initialise the request parameters
var options = {
    host: 'www.callfire.com',
    path: '/api/1.1/rest/number',
    auth: 'YOUR_LOGIN' + ':' + 'YOUR_PASSWORD'
};

// Initialise 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

requestOptions := callfire.CallFireRequestOptions{
    Url:            "https://www.callfire.com/api/1.1/rest/number",
    Login:          "YOUR_LOGIN",
    Secret:         "YOUR_PASSWORD",
    ReqType:        "GET",
    RequestOptions: "City=Waterford&Lata=738&MaxResults=2",
}
client, req := callfire.InitHttpClient(requestOptions)
resp, err := client.Do(req)

Response

If there are phone numbers linked to the account, or there are numbers matching the request arguments, you can expect a response similar to the example below. It contains a Number element for each matching phone number found, along with the total amount of results matching the request arguments, should you wish to implement pagination over the top of the results.

Core Elements

ArgumentTypeDescription
Number string A phone number in E.164 format.
NationalFormat string A phone number in national format, minus the country code.
TollFree boolean Whether the number is toll-free or not.
Region - An element containing the region information for the phone number. For specifics on each element, please refer to the request arguments for the query region information endpoint.
Status string The status of the number. Status can be one of: ACTIVE, PENDING, RELEASED,UNAVAILABLE
LeaseInfo - An element containing details about purchase, or lease, of the phone number.
NumberConfiguration - An element containing details about configuration options set on this phone number. For specifics on each element, please refer to the core, call tracking andIVR request arguments in the configure phone number endpoint.

Lease Elements

ArgumentTypeDescription
LeaseBegin date The date which the lease (or purchase) starts on.
LeaseEnd date The date which the lease (or purchase) ends on.
AutoRenew boolean Whether the purchase will auto-renew every month, automatically.

Note: Other information is also available, but only if it’s configured by the number configuration request.

Example Response

HTTP/1.1 200 OK
Content-Type: application/xml

<?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>12092084590</Number>
            <NationalFormat>(209) 208-4590</NationalFormat>
            <TollFree>false</TollFree>
            <Region>
                  <Prefix>1209208</Prefix>
                  <City>WATERFORD</City>
                  <State>CA</State>
                  <Zipcode>95386</Zipcode>
                  <Country>US</Country>
                  <Lata>738</Lata>
                  <RateCenter>KNIGHTFRRY</RateCenter>
                  <Latitude>37.8248</Latitude>
                  <Longitude>-120.665</Longitude>
                  <TimeZone>America/Los_Angeles</TimeZone>
            </Region>
            <Status>ACTIVE</Status>
            <LeaseInfo>
                  <LeaseBegin>2015-01-22Z</LeaseBegin>
                  <LeaseEnd>2015-02-21Z</LeaseEnd>
                  <AutoRenew>false</AutoRenew>
            </LeaseInfo>
            <NumberConfiguration>
                  <CallFeature>DISABLED</CallFeature>
                  <TextFeature>ENABLED</TextFeature>
            </NumberConfiguration>
      </Number>
      <Number>
            <Number>12092084589</Number>
            <NationalFormat>(209) 208-4589</NationalFormat>
            <TollFree>false</TollFree>
            <Region>
                  <Prefix>1209208</Prefix>
                  <City>WATERFORD</City>
                  <State>CA</State>
                  <Zipcode>95386</Zipcode>
                  <Country>US</Country>
                  <Lata>738</Lata>
                  <RateCenter>KNIGHTFRRY</RateCenter>
                  <Latitude>37.8248</Latitude>
                  <Longitude>-120.665</Longitude>
                  <TimeZone>America/Los_Angeles</TimeZone>
            </Region>
            <Status>ACTIVE</Status>
            <LeaseInfo>
                  <LeaseBegin>2015-01-22Z</LeaseBegin>
                  <LeaseEnd>2015-02-21Z</LeaseEnd>
                  <AutoRenew>false</AutoRenew>
            </LeaseInfo>
            <NumberConfiguration>
                  <CallFeature>DISABLED</CallFeature>
                  <TextFeature>DISABLED</TextFeature>
                  <InboundCallConfigurationType>TRACKING</InboundCallConfigurationType>
                  <InboundCallConfiguration>
                        <CallTrackingConfig id="3979553003">
                              <TransferNumber>12092084590</TransferNumber>
                              <Screen>true</Screen>
                              <Record>true</Record>
                              <IntroSoundId>779688003</IntroSoundId>
                              <WhisperSoundId>779686003</WhisperSoundId>
                        </CallTrackingConfig>
                  </InboundCallConfiguration>
            </NumberConfiguration>
      </Number>
</r:ResourceList>

 

 

Have more questions? Submit a request

Comments