PHP Library v1

View Repo

The Flowroute PHP Library v1 provides methods for interacting with Numbers v1 of the Flowroute API.

Topics

Requirements




Installation

  1. First, open a terminal window and clone the PHP library.
  2. git clone https://github.com/flowroute/flowroute-numbers-php.git
    
                

  3. Switch to the newly-created flowroute-numbers-php directory.
  4. Download Composer in the same directory. PHP Library v1 comes with a composer.json listing the project dependencies and other metadata. Run the following:
  5. php composer.phar install
    
                

    Usage

    In Flowroute's approach to building the Numbers (v1) API wrapper, HTTP requests are handled by controllers, which contain the methods used to perform tasks with the PHP library.

    Controllers

    • PurchasablePhoneNumbersController

      Contains all of the methods necessary to search through Flowroute's phone number inventory.

    • TelephoneNumbersController

      Contains all of the methods necessary to purchase a new phone number and manage your owned phone number inventory.

    • InboundRoutesController

      Contains the methods required to create new routes and view your current routes.

      • mlist() - List existing inbound routes from your account
      • createNewRoute() - Create a new inbound route that can then be assigned as either a primary or failover route for a phone number

    The following shows an example of a single PHP file that imports and instantiates all three Controllers:

    <?php
    require_once('vendor/autoload.php');
    
    use FlowrouteNumbersLib\Controllers\InboundRoutesController;
    use FlowrouteNumbersLib\Controllers\PurchasablePhoneNumbersController;
    use FlowrouteNumbersLib\Controllers\TelephoneNumbersController;
    use FlowrouteNumbersLib\APIException;
    
    $irc = new InboundRoutesController();
    $pnc = new PurchasablePhoneNumbersController();
    $tnc = new TelephoneNumbersController();
    
    use FlowrouteNumbersLib\Models\BillingMethod;
    use FlowrouteNumbersLib\Models\Route;
    
                

    Credentials

    Switch to the srcdirectory. In Configuration.php, replace accessKey:secretKey with your API credentials from the Flowroute Manager.

    <?php
    namespace FlowrouteNumbersLib;
    
    class Configuration {
    public static $BASEURI = 'https://api.flowroute.com/v1';
    public static $username = 'AccessKey';
    public static $password = 'SecretKey';
    }
    
            

    Methods

    listAvailableNPAs()

    The method accepts the limit and page parameters which you can learn more about in the API reference. The following example limits the number of NPAs returned to 3:

    #List Available NPAs
    $response = $pnc->listAvailableNPAs(3, 2);
    
                
    Example Response
    [npas] => stdClass Object
    (
        [201] => stdClass Object
            (
                [nxxs] => /v1/available-tns/npanxxs/?npa=201
                [tns] => /v1/available-tns/tns/?npa=201
            )
    
        [203] => stdClass Object
            (
                [nxxs] => /v1/available-tns/npanxxs/?npa=203
                [tns] => /v1/available-tns/tns/?npa=203
            )
    
        [202] => stdClass Object
            (
                [nxxs] => /v1/available-tns/npanxxs/?npa=202
                [tns] => /v1/available-tns/tns/?npa=202
            )
    
    )
    
    [links] => stdClass Object
    (
        [next] => /v1/available-tns/npas/?limit=3&page=2
    )
                
                
    listAreaAndExchange()

    The method accepts the limit, npa, and page parameters which you can learn more about in the API reference. The following example sets the limit to 2, the npa to 203, and the display page to 2:

    #List NPA and NXX
    $response = $pnc->listAreaAndExchange(2,203,2);
    
                
    Example Response

    Results are returned in numerical order, starting with the lowest NPA number. The npaxxs parameter variable is formatted as a combination of the NPA and NXX. In the following example, 206258 is the combination of NPA 206 and NXX 258.

    (
    [npanxxs] => stdClass Object
    (
        [203583] => stdClass Object
            (
                [tns] => /v1/available-tns/tns/?npa=203&nxx=583
            )
        [203567] => stdClass Object
            (
                [tns] => /v1/available-tns/tns/?npa=203&nxx=567
            )
    )
        [links] => stdClass Object
        (
            [prev] => /v1/available-tns/npanxxs/?npa=203&limit=2&page=2
            [next] => /v1/available-tns/npanxxs/?npa=203&limit=2&page=4
        )
    )
                
                
    search()

    The search() method is the most robust option for searching through Flowroute's purchasable phone number inventory. It allows you to search by NPA, NXX, Ratecenter, State, and/or TN (telephone number). The method accepts the limit, page, npa, nxx, rate center, state, and tn parameters which you can learn more about in the API reference.

    In the following example, a search request sets the limit to 3, the npa to 206, the nxx to 641, the display page to 2, the ratecenter to seattle, the state to wa, and the tn to null.

    #Search
    $response = $pnc->search(3,206,641,2,seattle,wa,null);
    
                
    Example Response
    (
    [tns] => stdClass Object
    (
        [12066417848] => stdClass Object
            (
                [initial_cost] => 1.00
                [monthly_cost] => 1.25
                [billing_methods] => Array
                    (
                       [1] => METERED
                    )
                [ratecenter] => SEATTLE
                [state] => WA
            )
        [12066417632] => stdClass Object
            (
                [initial_cost] => 1.00
                [monthly_cost] => 1.25
                [billing_methods] => Array
                    (
                        [1] => METERED
                    )
                [ratecenter] => SEATTLE
                [state] => WA
            )
        [12066417664] => stdClass Object
            (
                [initial_cost] => 1.00
                [monthly_cost] => 1.25
                [billing_methods] => Array
                    (
                        [1] => METERED
                    )
                [ratecenter] => SEATTLE
                [state] => WA
            )
    )
    [links] => stdClass Object
        (
            [next] => /v1/available-tns/tns/?npa=206&nxx=641&state=wa&ratecenter=seattle&limit=3&page=2
        )
    )
                
                
    purchase()

    The purchase() method is used to purchase a telephone number from Flowroute's inventory. The method accepts the billing_method (within the BillingMethod object) and telephone_number parameters which you can learn more about in the API reference.

    #Purchase a Telephone Number
    $billing = new BillingMethod('METERED');
    $number = '12066417848';
    $response = $tnc->purchase($billing, $number);
    
                
    Example Response

    If the purchase is successful, a 201 CreatedHTTP response and empty body are returned indicating the date on which the purchase occurred:

    (
    [code] => 201
            [raw_body] =>
       [body] =>
       [headers] => Array
          (
              [0] => HTTP/1.1 201 Created
              [Content-Type] => application/json
              [Date] => Thu, 30 March 2017 18:32:36 GMT
              [Server] => nginx
             [Content-Length] => 0
              [Connection] => keep-alive
            )
      )
    
              
    list_account_telephone_numbers()

    The method accepts the limit, page, and pattern parameters which you can learn more about in the API reference. The following example sets the limit to 1, the page to null, and the search pattern to 206:

    #List Account Telephone Numbers
    $response = $tnc->listAccountTelephoneNumbers(1,null,206);
    
                
    Example Response
    (
    [tns] => stdClass Object
    (
      [12066417848] => stdClass Object
       (
           [billing_method] => METERED
           [routes] => Array
               (
                   [0] => stdClass Object
                       (
                           [type] => SIP-REG
                           [name] => sip-reg
                       )
    
                   [1] => stdClass Object
                       (
                           [type] => SIP-REG
                           [name] => sip-reg
                       )
               )
           [detail] => /v1/tns/12066417848
       )
    )
    [links] => stdClass Object
        (
            [next] => /v1/tns/?pattern=206&limit=1&page=2
        )
    )    
                
                
    telephone_number_details()

    The method accepts the telephone_number_details parameter which you can learn more about in the API reference. In the following example, details are requested for the telephone number just purchased using the purchase method.

    #Telephone Number Details
    $number = '12065551234';
    $response = $tnc->telephoneNumberDetails($number);
    
                
    Example Response
    ( 
       [billing_method] => METERED 
       [routes] => Array 
       ( 
          [0] => stdClass Object (
             [type] => SIP-REG 
             [name] => sip-reg 
          ) 
          [1] => stdClass Object ( 
             [type] => SIP-REG 
             [name] => sip-reg 
          ) 
       ) 
    )
                
                
    update()

    The method accepts the routes and telephone_number parameters which you can learn more about in the API reference.

    #Update Telephone Number Routes
    $rtes = '{"routes": [{"name": "HOSTroute1"}, {"name": "PSTNroute1"}]}'; 
    $response = $tnc->update('12064205780',$rtes);
    
                
    Example Response

    An empty line is returned for a successful update. No other message is returned. To view the route changes on the phone number, run the listAccountTelephoneNumbers() or telephoneNumberDetails() methods.

    204 No Content
    ''
                
                
    mlist()

    The method accepts the limit and page parameters which you can learn more about in the API reference.

    #List Routes
    $response = $inbound->mlist(4,null);
    
                
    Example Response
    (
    [routes] => stdClass Object
        (
            [HOSTroute1] => stdClass Object
                (
                    [type] => HOST
                    [value] => 24.239.23.40:5060
                )
            [PSTNroute1] => stdClass Object
                (
                    [type] => PSTN
                    [value] => 178
                )
            [URIroute1] => stdClass Object
                (
                    [type] => URI
                    [value] => sip:16476998778@215.122.69.152:5060
                )
            [sip-reg] => stdClass Object
                (
                    [type] => SIP-REG
                    [value] =>
                )
        )
    )
                
                
    createNewRoute()

    The method accepts the route_name, mtype, and value parameters which you can learn more about in the API reference.

    You can pass as many createNewRoute methods in a single operation. The following example creates new PSTN, HOST, and URI routes:

    #Create New Routes
    $response = $irc->createNewRoute('PSTNroute2','PSTN','12066417848');
    $response = $irc->createNewRoute('HOSTroute2','HOST','4.239.23.40:5060');
    $response = $irc->createNewRoute('URIroute2','URI','sip:12066417848@215.122.69.152:5060');
    
                
    Example Response

    An empty string ('') is returned for each successfully created route; no other code or message is returned. An error encountered for a specific irc->createNewRoute() line does not prevent the other routes from being created.

    ' '
                
                

    Errors

    In the PHP Library v1, the error handling produces the following example error object:

    Example Error
    --Purchase a Phone Number
    Unirest\Response Object
    (
        [code] => 422
        [raw_body] => {"error": "Business Logic Error: The TN is not available for purchase."}
        [body] => stdClass Object
            (
                [error] => Business Logic Error: The TN is not available for purchase.
            )
    
        [headers] => Array
            (
                [0] => HTTP/1.1 422 Unknown Status
                [Content-Type] => application/json
                [Date] => Thu, 27 Apr 2017 00:02:45 GMT
                [Server] => nginx
                [Content-Length] => 72
                [Connection] => keep-alive
            )
    
    )