Update Details for a Phone Number

Allows you to update the Alias or CNAM Lookup parameters for your long code or toll-free phone number.

Endpoint

PATCH /numbers/:id

Request Parameters

Path Parameter

  • id
    string REQUIRED

    The phone number to which the alias will be assigned. This number must be in 11-digit North American format. e.g. 12065551234.

Body Parameters

  • type
    string REQUIRED

    Type of the data object to be updated. This will always be number.

  • alias
    string

    Nonunique friendly name to be assigned to the phone number.

  • cnam_lookups_enabled
    boolean

    Enable or Disable CNAM Lookups on inbound calls.

  • 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. Defaults to False.

    Please see Flowroute Pricing for the costs associated with enabling a number to send and receive messages.

    For more information on how sending SMS/MMS Messages works, see the Flowroute articles Flowroute Messaging API Overview, Send Your First SMS or our Two-factor Authentication Quickstart.

    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.

  • messaging_email
    boolean

    If set to True in combination with messaging_enabled, causes the Message Provision API to send an email to the account contact address on file when the Message Provision job finishes.

  • messaging_callback_url
    string

    If set to a valid URL in combination with messaging_enabled, causes the Message Provision API to send a notification via callback when the Provision request is finished. For information about how callbacks work, see the Callbacks page.

Response

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


Example Request

PATCH /v2/numbers/16463451234 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
    "type": "number",
    "alias": "NYC Number"
}

                  

Example Responses

200 OK

    {
      "data": {
        "attributes": {
          "alias": "My NYC number",
          "cnam_lookups_enabled": true,
          "messaging_enabled": true,
          "number_type": "longcode",
          "rate_center": "nwyrcyzn01",
          "state": "ny",
          "value": "16463451234"
        },
        "id": "16463451234",
        "links": {
          "self": "https://api.flowroute.com/v2/numbers/16463451234"
        },
        "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",
            "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/16463451234"
      }
    }
    
                  

Example Request

curl https://api.flowroute.com/v2/numbers/16463451234 -X PATCH \
-u accessKey:secretKey -H 'Content-Type':'application/json' -d \
'{"type":"number", "alias":"NYC Number"}'

                  

Example Responses

200 OK

    {
      "data": {
        "attributes": {
          "alias": "My NYC number",
          "cnam_lookups_enabled": true,
          "messaging_enabled": true,
          "number_type": "longcode",
          "rate_center": "nwyrcyzn01",
          "state": "ny",
          "value": "16463451234"
        },
        "id": "16463451234",
        "links": {
          "self": "https://api.flowroute.com/v2/numbers/16463451234"
        },
        "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",
            "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/16463451234"
      }
    }
    
                  

Example Request with PATCH Parameters for Messaging Enablement

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

Example Response with Message Enablement

200 OK

                
  {
  "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"
  }
}
                
              

401 Unauthorized

{
  "errors": [
    {
      "detail": "Authentication failed.",
      "id": "7fc8c70a-ca58-430c-b383-b89df84f8083",
      "status": 401,
      "title": "Unauthorized"
    }
  ]
}

          

403 Forbidden

{  "errors":
  [
    {
      "status": 403,
      "detail": "",
      "title": "ActionNotAuthorizedError"
    }
  ]
}