Order Numbers & Keywords

Overview

In this guide, you'll find information and code examples on how to order numbers and/or keywords in the CallFire platform. CallFire allows you to purchase local and toll-free numbers, as well as keywords, through the API or the Developers' UI.

How to Find Numbers Available for Purchase

Before you can assign a number to your account, you need to find ones that are available. If you need to find and purchase a number quickly, use the Developers' UI and:

go to the 'Phone Numbers' page and click on the 'Buy Numbers' button
on the'Purchase Numbers' page, you can find numbers either by area code or by location information such as ZIP code or city name.

Add Numbers or Keywords to Account

After you choose the numbers you are going to purchase, click on the 'Purchase' button and fill in the billing information.

Find Available Numbers

If you are building an integration, you can use the corresponding API methods to find available numbers. CallFire provides different filtering options to refine your search. You can filter numbers by the following fields:

State - A two character state abbreviation code, such as AZ for Arizona.
City - The full name of a US city, such as Phoenix.
Zipcode - A 5 digit, US ZIP code, such as 85001, which is located in Phoenix, Arizona.
Prefix - The 3 digit prefix of number
LATA - A 3 digit US LATA code
Rate Center - The RateCenter to use. It’s important to choose the right Rate Center, because when numbers are assigned from local Rate Centers, they’ll be billed as local calls. Otherwise, there’s a risk of incurring long distance call charges.

The following code examples show how to find two local numbers from the 90401 zipcode area:

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u "username:password" -H "Content-Type:application/json" -X GET "https://api.callfire.com/v2/numbers/local?prefix=14245&city=Los Angeles&state=CA&zipcode=90940&lata=123&rateCenter=123&offset=0&limit=10&fields=items(number,nationalFormat,leaseBegin,leaseEnd,region/city)"

response:

[
  {
    "number": "13102308654",
    "nationalFormat": "(310) 230-8654",
    "tollFree": false,
    "region": {
      "prefix": "1310230",
      "city": "SANTA MONICA",
      "state": "CA",
      "zipcode": "90401",
      "lata": "730",
      "rateCenter": "SNMN SNMN",
      "latitude": 34.0428,
      "longitude": -118.5249,
      "timeZone": "America/Los_Angeles"
    }
  },
  {
    "number": "13102301603",
    "nationalFormat": "(310) 230-1603",
    "tollFree": false,
    "region": {
      "prefix": "1310230",
      "city": "SANTA MONICA",
      "state": "CA",
      "zipcode": "90401",
      "lata": "730",
      "rateCenter": "SNMN SNMN",
      "latitude": 34.0428,
      "longitude": -118.5249,
      "timeZone": "America/Los_Angeles"
    }
  }
]

[-curl] [+java]

import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.numbers.model.Number;
import com.callfire.api.client.api.numbers.model.request.FindNumbersLocalRequest;

import java.util.List;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        FindNumbersLocalRequest request = FindNumbersLocalRequest.create()
            .prefix("14245")
            .city("Los Angeles")
            .state("CA")
            .zipcode("90940")
            .lata("123")
            .rateCenter("123")
            .offset(0L)
            .limit(10L)
            .fields("items(number,nationalFormat,leaseBegin,leaseEnd,region/city)")
            .build();
        List<Number> numbers = client.numbersApi().findNumbersLocal(request);
    }
}

[-java] [+csharp]

using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.Numbers.Model;
using CallfireApiClient.Api.Numbers.Model.Request;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var request = new FindNumbersLocalRequest
        {
            Prefix = "14245",
            City = "Los Angeles",
            State = "CA",
            Zipcode = "90940",
            Lata = "123",
            RateCenter = "123",
            Offset = 0,
            Limit = 10,
            Fields = "items(number,nationalFormat,leaseBegin,leaseEnd,region/city)"
        };
        IList<Number> numbers = client.NumbersApi.FindNumbersLocal(request);
    }
}

[-csharp] [+js]

'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.numbers.findNumbersLocal({
      // filter by 4-7 digit prefix
      prefix: '14245',
      // filter by city
      city: 'Los Angeles',
      // filter by state
      state: 'CA',
      // filter by zipcode
      zipcode: '90940',
      // filter by local access and transport area (LATA)
      lata: '123',
      // filter by rate center
      rateCenter: '123',
      // search offset
      offset: 0,
      // return 10 items per request
      limit: 10,
      // return only specific fields
      fields: 'items(number,nationalFormat,leaseBegin,leaseEnd,region/city)'
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);

[-js] [+python]

from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.numbers.findNumbersLocal(
    # filter by 4-7 digit prefix
    prefix='14245',
    # filter by city
    city='Los Angeles',
    # filter by state
    state='CA',
    # filter by zipcode
    zipcode='90940',
    # filter by local access and transport area (LATA)
    lata='123',
    # filter by rate center
    rateCenter='123',
    # search offset
    offset=0,
    # return 10 items per request
    limit=10,
    # return only specific fields
    fields='items(number,nationalFormat,leaseBegin,leaseEnd,region/city)'
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)

[-python] [+php]

<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->findNumbersLocal();
        $request->getOperationConfig()->setQueryParameters(array("prefix" => "14245",
                                                                 "city" => "Los Angeles",
                                                                 "state" => "CA",
                                                                 "zipcode" => "90940",
                                                                 "lata" => "123",
                                                                 "rateCenter" => "123",
                                                                 "offset" => 0,
                                                                 "limit" => 10,
                                                                 "fields" => "items(number,nationalFormat,leaseBegin,leaseEnd,region/city)"));
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();

[-php] [[/code-container]]

The API method is described on the documentation page

These examples show how to find available toll-free numbers:

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u "username:password" -H "Content-Type:application/json" -X GET "https://api.callfire.com/v2/numbers/tollfree?pattern=87*&limit=10&fields=number"

response:

[
  {
    "number": "18665552017",
    "nationalFormat": "(866) 555-2017",
    "tollFree": true
  },
  {
    "number": "18665553366",
    "nationalFormat": "(866) 555-3366",
    "tollFree": true
  }
]

[-curl] [+java]

import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.numbers.model.Number;
import com.callfire.api.client.api.numbers.model.request.FindTollfreeNumbersRequest;

import java.util.List;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        FindTollfreeNumbersRequest request = FindTollfreeNumbersRequest.create()
            .pattern("87*")
            .limit(10L)
            .fields("number")
            .build();
        List<Number> numbers = client.numbersApi().findNumbersTollfree(request);
    }
}

[-java] [+csharp]

using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.Numbers.Model;
using CallfireApiClient.Api.Numbers.Model.Request;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var request = new FindTollfreeNumbersRequest
        {
            Pattern = "87*",
            Limit = 10,
            Fields = "number"
        };
        IList<Number> numbers = client.NumbersApi.FindNumbersTollfree(request);
    }
}

[-csharp] [+js]

'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.numbers.findNumbersTollfree({
      // filter toll free numbers by prefix, pattern must be 3 char long and should end with '*'.
      // examples: 8**, 85*, 87* (but 855 will fail because pattern must end with '*').
      pattern: '87*',
      // return 10 items per request
      limit: 10,
      // return only specific fields
      fields: 'number'
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);

[-js] [+python]

from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.numbers.findNumbersTollfree(
    # filter toll free numbers by prefix, pattern must be 3 char long and should end with '*'.
    # examples: 8**, 85*, 87* (but 855 will fail because pattern must end with '*').
    pattern='87*',
    # return 10 items per request
    limit=10,
    # return only specific fields
    fields='number'
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)

[-python] [+php]

<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->findNumbersTollfree();
        $request->getOperationConfig()->setQueryParameters(array("pattern" => "87*",
                                                                 "limit" => 10,
                                                                 "fields" => "number"));
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();

[-php] [[/code-container]]

The API method is described on the documentation page

How to Purchase Available Numbers

CallFire provides varied ways to purchase one or more numbers in a single API call, so you can:

Set the list of particular numbers to purchase.
Set either tollFreeCount or localCount to purchase random toll-free or local numbers. If you would like to purchase numbers from specific areas, this API method provides the same filtering options as in the Find API method: city, state, zipcode, prefix, etc.

Available numbers will be purchased using the preferred credit card in your CallFire account. If you do not have one set, you will need to add one through the UI. The following examples show how to purchase two particular numbers from the list and two numbers from 90401 zipcode area:

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u "username:password" -H "Content-Type:application/json" -X POST -d '
    {
        "numbers":
        [
            "12131234567",
            "12131234568"
        ]
    }' "https://api.callfire.com/v2/orders/numbers"

curl -u "username:password" -H "Content-Type:application/json" -X POST -d '
    {
        "localCount":"2",
        "zipcode":"90401"
    }' "https://api.callfire.com/v2/orders/numbers"

response:

{
  "id": 10
}

[-curl] [+java]

import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.common.model.ResourceId;
import com.callfire.api.client.api.numbers.model.request.NumberPurchaseRequest;

import java.util.Arrays;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient callfireClient = new CallfireClient("api_login", "api_password");
        // request for buying particular numbers
        NumberPurchaseRequest request1 = NumberPurchaseRequest.create()
            .numbers(Arrays.asList("12131234567", "12131234568"))
            .build();
        ResourceId resourceId1 = callfireClient.ordersApi().orderNumbers(request1);

        // request for buying numbers in specific area
        NumberPurchaseRequest request2 = NumberPurchaseRequest.create()
            .zipcode("90401")
            .localCount(2)
            .build();
        ResourceId resourceId2 = callfireClient.ordersApi().orderNumbers(request2);
    }
}

[-java] [+csharp]

using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.Common.Model;
using CallfireApiClient.Api.Numbers.Model.Request;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        // request for buying particular numbers
        var request1 = new NumberPurchaseRequest
        {
            Numbers = new List<string> {"12131234567", "12131234568"}
        };
        ResourceId resourceId1 = client.OrdersApi.OrderNumbers(request1);

        // request for buying numbers in specific area
        var request2 = new NumberPurchaseRequest {Zipcode = "90401", LocalCount = 2};
        ResourceId resourceId2 = client.OrdersApi.OrderNumbers(request2);
    }
}

[-csharp] [+js]

'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.orders.orderNumbers({
      body: {
        // order particular numbers
        numbers: ['12131234567', '12131234568']
        // or find and order area-specific numbers
        // localCount: '2',
        // zipcode: '90401'
      }
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);

[-js] [+python]

from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.orders.orderNumbers(
    body={
        # order particular numbers
        'numbers': ['12131234567', '12131234568']
        # or find and order area-specific numbers
        # localCount: '2',
        # zipcode: '90401'
    }
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)

[-python] [+php]

<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request1 = $client->orderNumbers();
        $body = '{
                    "numbers":
                    [
                        "12131234567",
                        "12131234568"
                    ]
                 }';
        $request1->getOperationConfig()->setBodyParameter($body);
        $result1 = $client->request($request1);
        $json = json_decode($result1->getBody());

        $request2 = $client->orderNumbers();
        $body = '{
                    "localCount":"2",
                    "zipcode":"90401"
                 }';
        $request2->getOperationConfig()->setBodyParameter($body);
        $result2 = $client->request($request2);
        $json = json_decode($result2->getBody());
    }
}

ApiClientSample::main();

[-php] [[/code-container]]

The API method is described on the documentation page

CallFire is also provisioning short codes, read this page about how to order a short code.

How to Find Keywords Available for Purchase

CallFire also has an API method for searching and purchasing available keywords. It is very easy to use this API. You can check multiple keywords for availability, and if a keyword returns in the response, it is available for purchase. The following samples show how to do this:

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u username:password -H "Content-Type:application/json" -X GET "https://api.callfire.com/v2/keywords?keywords=SUN&keywords=MOON"

response:

{
  "items": [
    {
      "shortCode": "67076",
      "keyword": "SUN"
    },
    {
      "shortCode": "67076",
      "keyword": "MOON"
    }
  ]
}

[-curl] [+java]

import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.keywords.model.Keyword;

import java.util.Arrays;
import java.util.List;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient client = new CallfireClient("api_login", "api_password");
        List<Keyword> keywords = client.keywordsApi().find(Arrays.asList("SUN", "MOON"));
    }
}

[-java] [+csharp]

using System.Collections.Generic;
using CallfireApiClient;
using CallfireApiClient.Api.Keywords.Model;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        List<string> keywords = new List<string> {"SUN", "MOON"};
        IList<Keyword> avaialbeKeywords = client.KeywordsApi.Find(keywords);
    }
}

[-csharp] [+js]

'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.keywords.findKeywords({
      keywords: ['SUN', 'MOON']
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);

[-js] [+python]

from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.keywords.findKeywords(
    keywords=['SUN', 'MOON']
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)

[-python] [+php]

<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->findKeywords();
        $request->getOperationConfig()->setQueryParameters(array("keywords" => "SUN",
                                                                 "keywords" => "MOON"));
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();

[-php] [[/code-container]]

The API method is described on the documentation page

How to Purchase Available Keywords

You can order one or more keywords by sending a list of available keywords into this API. Be sure to set a preferred credit card in your CallFire account before trying to purchase.

[[code-container]] [+curl] request:

#!/usr/bin/env bash

curl -u "username:password" -H "Content-Type:application/json" -X POST -d '
    {
        "keywords":
        [
            "SUN", "MOON"
        ]
    }' "https://api.callfire.com/v2/orders/keywords"

response:

{
  "id": 12
}

[-curl] [+java]

import com.callfire.api.client.CallfireClient;
import com.callfire.api.client.api.common.model.ResourceId;
import com.callfire.api.client.api.keywords.model.request.KeywordPurchaseRequest;

import java.util.Arrays;

class ApiClientSample {
    public static void main(String[] args) {
        CallfireClient callfireClient = new CallfireClient("api_login", "api_password");
        KeywordPurchaseRequest request = KeywordPurchaseRequest.create()
            .keywords(Arrays.asList("SUN", "MOON"))
            .build();
        ResourceId resourceId = callfireClient.ordersApi().orderKeywords(request);
    }
}

[-java] [+csharp]

using CallfireApiClient;
using CallfireApiClient.Api.Common.Model;
using CallfireApiClient.Api.Keywords.Model.Request;

public class ApiClientSample
{
    public static void Main(string[] args)
    {
        var client = new CallfireClient("api_login", "api_password");
        var request = new KeywordPurchaseRequest
        {
            Keywords = { "SUN", "MOON" }
        };
        ResourceId resourceId = client.OrdersApi.OrderKeywords(request);
    }
}

[-csharp] [+js]

'strict'

const CallfireClient = require('callfire-api-client-js');
const client = new CallfireClient('api-login', 'api-password');

client.ready(() => {
    client.orders.orderKeywords({
      body: {
        keywords: ['SUN', 'MOON']
      }
    })
      .then((response) => {
        console.log(response.obj);
      })
      .catch((err) => {
        console.log('request error ' + err.data);
      });
  },
  (clientError) => {
    console.log('client error ' + clientError);
  }
);

[-js] [+python]

from callfire.client import CallfireClient

client = CallfireClient('api-login', 'api-password')
response = client.orders.orderKeywords(
    body={
        'keywords': ['SUN', 'MOON']
    }
).result()

# see sample JSON response for this API
# on 'curl' samples tab
print(response)

[-python] [+php]

<?php

class ApiClientSample {

    public static function main() {
        $client = \CallFire\Api\DocumentedClient::createClient("login", "password");
        $request = $client->orderKeywords();
        $body = '{
                    "keywords":
                    [
                        "SUN", "MOON"
                    ]
                 }';
        $request->getOperationConfig()->setBodyParameter($body);
        $result = $client->request($request);
        $json = json_decode($result->getBody());
    }
}

ApiClientSample::main();

[-php] [[/code-container]]

The API method is described on the documentation page