json

{
  "ValueUnit": "MB",
  "NotifyValue": 10,
  "ThrottleValue": 15,
  "ThrottleSpeed": "1-mbps",
  "LimitValue": 20,
  "PhoneNumbers": [
    { "Number": "+12016093801" },
    { "Number": "+12232233180" }
  ]
}

{
  "Status": "Complete",
  "StatusMessage": "",
  "ValueUnit": "MB",
  "NotifyValue": 10,
  "ThrottleValue": 15,
  "ThrottleSpeed": "1-mbps",
  "LimitValue": 20,
  "PhoneNumbers": [
    {
      "Number": "+12016093801"
    },
    {
      "Number": "+12232233180"
    }
  ]
}

Numbers

Data Usage Limit

Prerequisites:

Required: Bearer token — POST /v1.0/oauth2/tokens
Required: Provisioned number ID (NID) with DataEnabled: true — POST /v1.0/numbers/provision

Set data usage limits, notification thresholds, and throttling parameters for IoT/MVNO numbers. Configure when subscribers are notified and at what usage level data speeds are throttled. Important: NotifyValue, ThrottleValue, and LimitValue must be in ascending increments and cannot be the same value (e.g., NotifyValue < ThrottleValue < LimitValue). Unless a LimitValue is specified, the default data limit is 20 MB.

What this does: Returns the updated data usage configuration for each number in the batch. Settings take effect at the next billing cycle or usage event. A NotifyValue triggers a notification webhook when usage reaches that threshold; LimitValue hard-caps usage; ThrottleValue reduces speed instead of cutting off.

Next steps:

Confirm the new settings — POST /v1.0/numbers/data-usage/settings
Check current consumption — POST /v1.0/numbers/data-usage/info

POST

v1.0

numbers

data-usage

json

{
  "ValueUnit": "MB",
  "NotifyValue": 10,
  "ThrottleValue": 15,
  "ThrottleSpeed": "1-mbps",
  "LimitValue": 20,
  "PhoneNumbers": [
    { "Number": "+12016093801" },
    { "Number": "+12232233180" }
  ]
}

{
  "Status": "Complete",
  "StatusMessage": "",
  "ValueUnit": "MB",
  "NotifyValue": 10,
  "ThrottleValue": 15,
  "ThrottleSpeed": "1-mbps",
  "LimitValue": 20,
  "PhoneNumbers": [
    {
      "Number": "+12016093801"
    },
    {
      "Number": "+12232233180"
    }
  ]
}

Body

application/json

ValueUnit

enum<string>

required

Unit of data measurement

Available options:

MB

Example:

"MB"

LimitValue

integer

required

Maximum data cap/limit

Example:

20

PhoneNumbers

object[]

required

Array of phone numbers to apply data limits to

Show child attributes

NotifyValue

integer

Data usage threshold for subscriber notification

Example:

10

ThrottleValue

integer

Data usage threshold for speed throttling

Example:

15

ThrottleSpeed

enum<string>

Throttled speed limit

Available options:

1-mbps,

5-mbps,

20-mbps,

50-mbps,

100-mbps

Example:

"1-mbps"

Response

Data Usage Limit Set

The response is of type object.

Numbers Status Data Usage Settings

⌘I