Purchase a Phone Number

Use this endpoint to purchase a phone number from available Flowroute inventory.

Endpoint

POST /numbers/:id

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.

Example Request

            POST /v2/numbers/16502390214 HTTP/1.1
              Content-Type: application/vnd.api+json
              Accept: application/vnd.api+json
            
          

Example Response

201 CREATED

            
{
  "data": {
    "attributes": {
      "alias": null,
      "cnam_lookups_enabled": true,
      "messaging_enabled": false,
      "number_type": "longcode",
      "rate_center": "millbrae",
      "state": "ca",
      "value": "16502390214"
    },
    "id": "16502390214",
    "links": {
      "self": "https://api.flowroute.com/v2/numbers/16502390214"
    },
    "relationships": {
      "cnam_preset": {
        "data": null
      },
      "e911_address": {
        "data": null
      },
      "failover_route": {
        "data": null
      },
      "primary_route": {
        "data": {
          "id": "0",
          "type": "route"
        }
      }
    },
    "type": "number"
  },
  "included": [
    {
      "attributes": {
        "alias": "sip-reg",
        "edge_strategy_id": null,
        "route_type": "sip-reg",
        "value": null
      },
      "id": "0",
      "links": {
        "self": "https://api.flowroute.com/v2/routes/0"
      },
      "type": "route"
    }
  ],
  "links": {
    "self": "https://api.flowroute.com/v2/numbers/16502390214"
  }
}
            
          

Example Request

            curl -X POST https://api.flowroute.com/v2/numbers/16502390214 -u accessKey:secretKey
            
          

Example Response

201 CREATED

            
{
  "data": {
    "attributes": {
      "alias": null,
      "cnam_lookups_enabled": true,
      "messaging_enabled": false,
      "number_type": "longcode",
      "rate_center": "millbrae",
      "state": "ca",
      "value": "16502390214"
    },
    "id": "16502390214",
    "links": {
      "self": "https://api.flowroute.com/v2/numbers/16502390214"
    },
    "relationships": {
      "cnam_preset": {
        "data": null
      },
      "e911_address": {
        "data": null
      },
      "failover_route": {
        "data": null
      },
      "primary_route": {
        "data": {
          "id": "0",
          "type": "route"
        }
      }
    },
    "type": "number"
  },
  "included": [
    {
      "attributes": {
        "alias": "sip-reg",
        "edge_strategy_id": null,
        "route_type": "sip-reg",
        "value": null
      },
      "id": "0",
      "links": {
        "self": "https://api.flowroute.com/v2/routes/0"
      },
      "type": "route"
    }
  ],
  "links": {
    "self": "https://api.flowroute.com/v2/numbers/16502390214"
  }
}
            
          

Example Request with POST Parameters for Messaging Enablement

Purchase a number with messaging enabled.

            curl https://api.flowroute.com/v2/numbers/16502390214 -X POST \
              -H 'Content-Type':'application/json' -u accessKey:secretKey \
              -d '{"messaging_enabled": true, "messaging_callback_url": "http://my-callback.com"}'
            
          

Example Response

201 CREATED

            
{
  "data": {
    "attributes": {
      "alias": null,
      "cnam_lookups_enabled": true,
      "inbound_rate": 0.012,
      "iso_country": "US",
      "messaging_enabled": false,
      "monthly_cost": 1.25,
      "number_type": "longcode",
      "rate_center": "wshngtnzn1",
      "rate_type": "local",
      "setup_cost": 1.0,
      "state": "dc",
      "status": "PURCHASED",
      "tier": "Standard",
      "value": "12023819746"
    },
    "id": "12023819746",
    "links": {
      "self": "https://api.flowroute.com/v2/numbers/12023819746"
    },
    "relationships": {
      "cnam_preset": {
        "data": null
      },
      "e911_address": {
        "data": null
      },
      "failover_route": {
        "data": null
      },
      "message_provision": {
        "data": {
          "id": "8afe0a20108c4219bc37cca866f7455e",
          "type": "message_provision"
        }
      },
      "primary_route": {
        "data": {
          "id": "0",
          "type": "route"
        }
      }
    },
    "type": "number"
  },
  "included": [
    {
      "attributes": {
        "alias": "sip-reg",
        "edge_strategy_id": null,
        "route_type": "sip-reg",
        "value": null
      },
      "id": "0",
      "links": {
        "self": "https://api.flowroute.com/v2/routes/0"
      },
      "type": "route"
    },
    {
      "attributes": {
        "status": "processing",
        "tn": "12023819746"
      },
      "id": "8afe0a20108c4219bc37cca866f7455e",
      "links": {
        "self": "https://api.flowroute.com/v2/message-provision/status/8afe0a20108c4219bc37cca866f7455e"
      },
      "type": "message_provisioning_status"
    }
  ],
  "links": {
    "self": "https://api.flowroute.com/v2/numbers/12023819746"
  }
}
            
          

Example Request

Purchase a number with messaging enabled with invalid values for messaging_email and messaging_callback_url.

            curl https://api.flowroute.com/v2/numbers/16502390214  -X POST \
              -H 'Content-Type':'application/json' -u accessKey:secretKey \
              -d '{"messaging_enabled": true, "messaging_email": "test@example.com", \
              "messaging_callback_url": "invalid_link"}'
            
          

Example Response

422


{
  "errors": [
    {
      "detail": {
        "messaging_callback_url": [
          "Not a valid URL."
        ],
        "messaging_email": [
          "Not a valid boolean."
        ]
      },
      "id": "7f30fa1e-3451-4333-ad61-a3f3a684ab42",
      "status": 422
    }
  ]
}

          

Example Error

404 NOT FOUND

          
{
  "errors": [
    {
      "detail": "Number: 6391723423456 is not purchasable.",
      "id": "78b36546-600e-4bc0-8797-dd1177edeb1a",
      "status": 404
    }
  ]
}