Purchase a Phone Number

Path Parameter

• id

  integer required

  Phone number to purchase. The number must be in 11-digit E.164 format with the first digit being the country code 1; e.g. 12061231234.

• cnam_lookups_enabled

  boolean

  If set to True, every time you receive an inbound call, Flowroute will contact one of the CNAM databases across the country and attempt to retreive the Caller Id for the number. This will incur a charge called a 'CNAM Dip'. If set to False, this will not happen. If left unset, this will default to the "CNAM Lookups by Default" setting in your account preferences (found in Preferences->Features). For more information on how this works, see the Flowroute article What is CNAM and how can it work for your business?.

• messaging_enabled

  boolean

  If set to True, sends an external request to the Message Provision API to change the enablement state of the number after purchase is complete. If not set, the default value is False.
  
  Please see Flowroute Pricing for the costs associated with enabling a number to send and receive messages.
  
  The purchase endpoint will validate the parameters provided. If successful it will return a 201 Created and the message_provisioning_status from the Message Provision API is added to the included list.
  
  Since this is a separate task, the messaging_enabled boolean in the response object will be false until the Message Provision task has successfully completed.
  
  If invalid values are supplied or there is an error with Numbers API, then the header status code is an error code and the response body contains an array of error objects.
  
  If messaging_enabled is set to True and the Message Provision API is unavailable, the status code will be 207 Multi-Status. This indicates that the number purchase succeeded and the Message Provision API returned an error.
  
  Enabling a number for SMS/MMS can be retried via the Message Provision API or Update Details for a Phone Number. For more information on how sending SMS/MMS Messages works, see the Flowroute articles Flowroute Messaging API Overview or our Two-factor Authentication Quickstart.
  
  

• messaging_email

  boolean

  If this optional parameter is set to True in combination with messaging_enabled, once the Message Provision API has finished, it will send an email with the results of the task whether the numbers were provisioned successfully or failed provisioning to the email address associated with your account.

• messaging_callback_url

  string

  If this optional parameter is set to a valid URL in combination with messaging_enabled, the Message Provision API will send a message_provisioning_status or message_bulk_provisioning_status payload to the callback URL specified.
  
  Please see the Look up a Message Provision Task documentation for descriptions of these JSON objects.
  
  For information about how callbacks work, see the Callbacks page.

Response Fields

On success, the HTTP status code in the response header is 201 CREATED and the response body contains a phone number object in JSON format. On partial success, the HTTP status code in the response header is 207 Multi-Status and the response body contains a phone number object in JSON format. On error, the header status code is an error code and the response body contains an array of error objects.

• data

  object

  Phone number object composed of the following:

• attributes

  object

  Object composed of attributes defined in "List Account Phone Numbers".

• id

  integer

  ID of the phone number object which is equal to its value.

• links

  object

  Links object pointing to the phone number's URI. For example, https://api.flowroute.com/v2/numbers/16502390214.

• relationships

  object

  Object describing the different relationships your phone number can have such as CNAM Presets, e911 Addresses, and Primary and Failover Routes all of which are represented as individual JSON objects.

  The message_provision object is only returned in this purchase response if messaging_enabled was supplied with additional optional parameters.

• type

  string

  This will always be number.

• included

  array

  An array of route objects associated with the phone number that you have purchased.

  If messaging_enabled was set to True, also includes a message_provisioning_status object, as described in Look up a Message Provision Task

• attributes

  object

  Route object composed of the following properties:

• alias string- Alias for the route.

• edge_strategy_id integer- The edge strategy ID associated with your inbound route. To see the list of different edge strategies, run this curl command: curl -u accessKey:secretKey https://api.flowroute.com/v2/routes/edge_strategies

• route_type string- Indicates the type of route: host, number, uri, or sip-reg. sip-reg is the default route type assigned to a phone number's primary voice route which you can change via Update Primary Voice Route for a Phone Number. To create a new route to be assigned to your newly purchased phone number, see Create an Inbound Route.

• value stringValue that the route was set to.

• id

  integer

  ID of the default route object for your newly purchased phone number.

• links

  object

  Links object pointing to the route's URI. For example, https://api.flowroute.com/v2/routes/0.

• type

  string

  This will always be route.

• links

  string

  Links object pointing to the purchased phone number's URI. For example, https://api.flowroute.com/v2/numbers/16502390214.