PHP API Wrapper

The Flowroute PHP API Wrapper provides methods for interacting with Number Management v1 and Messaging v2 of the Flowroute API.

Topics

Requirements


Numbers SDK (v1)

View Repo

Installation

  1. First, open a terminal window and clone the SDK.
  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. The Numbers SDK for PHP 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 SDK.

    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.

    ' '
                
                

    Messaging SDK (v2)

    View Repo

    Installation

    First, open a terminal window and clone the SDK.

    git clone https://github.com/flowroute/flowroute-messaging-php.git 
    
                

    Switch to the newly-created flowroute-messaging-php directory. The Messaging SDK for PHP comes with a requirements file listing the required Python libraries. Click here to learn more about different ways to install Python packages.

    pip install -r requirements.txt
    
                

    Usage

    In Flowroute's approach to building the Messaging (v2) API wrapper, HTTP requests are handled by the APIController, which contains the functions used to perform tasks with the PHP SDK.

    APIController

    The following shows how you can instantiate the Controllers and import the Models:

    #Require Flowroute Messaging
    <?php
     
       require_once('vendor/autoload.php');
       
       #Instantiate the Controllers
       use FlowrouteMessagingLib\Controllers\MessagesController;
       use FlowrouteMessagingLib\Models\Message;
    
                

    Credentials

    In your PHP file, replace accessKey:secretKey with your API credentials from the Flowroute Manager.

    #Pass your API credentials
    $controller_name = new MessagesController('Access Key','Secret Key');
    
                

    Methods

    createMessage()

    The method accepts the msg, to, from, and body parameters which you can learn more about in the API reference.

    #Create and send the message
    $mymessage = new Message('18444205700', '12062092844', 'Get some exercise!');
    $response = $controller->createMessage($mymessage);
    
                
    Example Response
    (
    [data] => stdClass Object
       (
           [id] => mdr1-6bdb954473d249308d43debd4735b493
       )
    
    )
    
                
    getMessageLookup()

    The method accepts the record_id parameter which you can learn more about in the API reference.

    #Get the MDR
    $response = $controller->getMessageLookup('mdr1-6bdb954473d249308d43debd4735b493');
    
                
    Example Response
    (
       [data] => stdClass Object
         (
             [attributes] => stdClass Object
                (
                    [body] => Get some exercise!
                    [direction] => outbound
                    [timestamp] => 2016-05-20T17:07:46.322587+00:00
                    [amount_nanodollars] => 4000000
                    [from] => 12062092844
                    [message_encoding] => 0
                    [has_mms] =>
                    [to] => 18444205700
                    [amount_display] => $0.0040
                    [callback_url] =>
                    [message_type] => long-code
                )
    
            [type] => message
            [id] => mdr1-6bdb954473d249308d43debd4735b493
        )
    )
    
                

    Errors

    In the Numbers SDK, 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
            )
    
    )