CallFire Solutions

02. Query Existing Labels

Follow

This endpoint allows for querying and retrieving the full details of one or more labels on an account; Labels may be associated with broadcasts or numbers.

Endpoint

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

Request Type

GET

Request Headers

Content-Type application/xml
Accepts application/xml

Returns

The request returns an XML payload containing a series of label data entries, matching the filters provided, if any labels did indeed match. In addition to this, a HTTP 200 OK status code is also returned. If there are labels available, the name property for each one will be rendered.

Request Arguments

ArgumentTypeDescription
Max Results long required - Default: 1000. The maximum number of results to return.
FirstResult long Default: 0. The starting record number for the next recordset.

Example Request

The below example shows how to make a request, using a set of the available request arguments with no pagination.

curl -i https://www.callfire.com/api/1.1/rest/label/?MaxResults=5&FirstResult=0 \
-H "Accept: application/xml" \
--user <YOUR_LOGIN>:<YOUR_PASSWORD>

PHP SDK

<?php
$query = new Request\QueryLabels();
$response = $app->callfireNumberRestClient->QueryLabels($query);
$result = $callfireNumberRestClient::response($response);

The following examples show how to make a request, with pagination. This example would, in effect, display 5 records per/page, and requesting the second page of results.

Curl

curl -i https://www.callfire.com/api/1.1/rest/label?MaxResults=5&FirstResult=5 \
  -H "Accept: application/xml" \
  --user <YOUR_LOGIN>:<YOUR_PASSWORD>

PHP SDK

<?php
$query = new Request\QueryLabels();
$query->setMaxResults(5);
$response = $app->callfireNumberRestClient->QueryLabels($query);
$result = $callfireNumberRestClient::response($response);

Node.js

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

var host = 'www.callfire.com';
var path = '/api/1.1/rest/label';
var login = 'YOUR_LOGIN';
var secret = 'YOUR_PASSWORD';
var data  = {
    MaxResults:  '5'
};
var endpoint = '?' + querystring.stringify(data);
var options = {
    host: host,
    path: path + endpoint,
    auth: login + ':' + secret
};

var req = https.get(options, function(res) {
    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/label?",
     Login:   "YOUR_LOGIN",
     Secret:  "YOUR_PASSWORD",
     ReqType: "GET",
     RequestOptions: "MaxResults=5&FirstResult=0",
}
client, req := callfire.InitHttpClient(requestOptions)
resp, err := client.Do(req)

Example Response

If there is information matching the request arguments, you can expect a response similar to the example below. It contains a Label element for each matching label found, along with the total amount of results matching the request arguments, should you wish to implement pagination over the top of the results.

In the response XML, will be an attribute called totalResults. This doesn’t relate to the total amount of results in your request, but the total amount of records overall. For example, if there were 10 labels on the account being queried,then totalResults would always be 10; even if MaxResults was 5. Please don’t be caught out by this. By using MaxResults, FirstResult and totalResults, you’re able to implement pagination when searching.

Standard Response

Here is an example of a successful response received from querying the API. It shows the total, unfiltered, results available.

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="11">
    <Label>
        <Name>four</Name>
    </Label>
    <Label>
        <Name>one</Name>
    </Label>
    <Label>
        <Name>six</Name>
    </Label>
    <Label>
        <Name>Test Labe</Name>
    </Label>
</r:ResourceList>

Specifying a FirstResult Greater Than the Total Number of Records

If the value you specify to FirstResult is greater than the number of results available, then you’ll receive a payload similar to that below. Here, it indicates that the FirstResult of 5 is greater than the total 4 results available.

HTTP/1.1 500 Internal Server Error
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<r:ResourceException xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">
    <r:HttpStatus>500</r:HttpStatus>
    <r:Message>fromIndex(5) &gt; toIndex(4)</r:Message>
</r:ResourceException>

Have more questions? Submit a request

Comments