Create an Inbound Route

Creates a new inbound route which can then be assigned as either a primary or a failover voice route for a phone number on your account. Please see List Inbound Routes to review the route values that you can associate with your Flowroute phone numbers.

Endpoint

POST /routes

Body Parameters

  • data
    required

    Data object composed of the following:

    • type
      required

      This will always be route.

    • attributes
      required

      Object composed of the following route attributes:

      • alias
        required

        Unique friendly name for the inbound route to be created.

      • route_type
        required

        Indicates the type of route: host, number, uri

      • value
        required

        Value of the route, dependent on the route_type:

        • If the route_type is host, the value must be an IP address or URL
          with an optional port number. For example, an IP address could be 24.239.23.40:5060 or a URL could be myphone.com. If no port is specified, the server will attempt to use DNS SRV records.

        • If the route_type is number, the value must be an 11-digit number in E.164 format. e.g.,16476998778.

        • If the route_type is uri, the value must be formatted as protocol:user@domain[:port][;transport=<tcp/udp/tls>.

          For example, sip:alice@atlanta.com, sip:16476998778@215.122.69.152:5060;transport=tcp, or sips:securecall@securedserver.com.

          Additionally, you can specify that your SIP traffic be TLS encrypted. To enable this feature, in th HOST or URI specified, indicate the transport protocol desired - tcp, upd or tls ;transport=tls.

          Advanced Feature - Weight Based Routing Using Parameters

          Flowroute's traditional routing parameters; primary and failover, allow customers to specify a route that takes 100% of traffic unless an issue is detected with the primary route and then 100% of traffic is directed to the failover route. The Weight Based Routing feature allows customers to utilize primary and failover route specification as a percentage of traffic spread across both routes.

          By adding a ;weight=X parameter to both routes, traffic can be conditionally spread across the two.

          Weights must be applied to both primary and failover routes for the DID in question.

          Weight values are specified between 0 and 1000 with 1000 being the heaviest weight and calculated as an overall percentage.

          For example:

          • route1@example.com;weight=400
            route2@example.com;weight=100
          • 100/(400+100) = 20%
            400/(400+100) = 80%
      • edge_strategy_id

        The PoP to receive traffic from. See the section on PoPs for more information.

        If not specified, the Preferred PoP for the account will be used. If there is no Preferred PoP set, then the Edge Strategy defaults to US-West-OR. This may result in 403 FORBIDDEN results if a Route with the same parameters for alias, value, and edge_strategy_id already exists.

Response Fields

On success, the HTTP status code in the response header is 200 OK and the response body contains a route 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

    Route object composed of the following:

    • attributes
      object

      Object composed of attributes described above.

    • id
      integer

      ID of the newly created route object.

    • links
      object

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

    • type
      string

      This will always be route.

  • links
    object

    Links object pointing to your newly created route. For example, https://api.flowroute.com/v2/routes/98396.

Example Request

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

{
  "data": {
    "type": "route",
    "attributes": {
      "route_type": "host",
      "value": "www.getouttahere.com",
      "alias": "new_route_5000",
      "edge_strategy_id": "4"
    }
  }
}

Example Request

curl https://api.flowroute.com/v2/routes -X POST -u accessKey:secretKey \
 -d '{"data": {"type":"route", "attributes": {"route_type": "host", "value": "www.getouttahere.com", "alias":"new_route_5000", "edge_strategy_id": "4"}}}' \
-H 'Content-Type':'application/vnd+api.json'

Example Responses

201 CREATED


{
  "data": {
    "attributes": {
      "alias": "new_route_5000",
      "route_type": "host",
      "value": "www.getouttahere.com",
      "edge_strategy_id": 4
    },
    "id": "98396",
    "links": {
      "self": "https://api.flowroute.com/routes/98396"
    },
    "type": "route"
  },
  "links": {
    "self": "https://api.flowroute.com/routes/98396"
  }
}

422 UNPROCESSABLE ENTITY

{
  "errors": [
    {
      "detail": "Invalid host: 123",
      "id": "f3a378a2-60ac-42d6-8915-bbd5cf2229bf",
      "status": 422
    }
  ]
}