Stop and restore service
Stop a customer's mobile data when they have used what they paid for, or suspend a lost phone's line, and restore either.
The Partner API gives you two levers on a customer's line. Pick by what happened:
| Situation | Call | What stops |
|---|---|---|
| The customer has used up what they paid for | Stop mobile data | Mobile data only; calls and texts keep working |
| The phone is lost or stolen | Suspend the line | All traffic on the line, domestic and international |
Both act on one line, named in the path. Lines are listed by GET /v1/numbers, and the id of each is what you name. Both return once the change has taken effect at the network, so a success means the service is genuinely stopped or restored. Nothing is queued for later. Both are real: there is no sandbox, and a call from the playground stops a real customer's service.
Neither lever is offered in every market. Check Markets before you offer one: where it says "Not supported", a stop returns 422 and a suspension 400, and nothing changes. Ending the line works everywhere.
Stop and restore mobile data
Send the change with an optional reason. It is kept with the change and shown to Telgea support if the customer calls.
POST /v1/numbers/{numberId}/data-restriction{
"reason": "Customer exceeded their agreed data allowance."
}The response lists the numbers the stop reached and when it took effect:
{
"numbers": ["+4520123456"],
"effectiveAt": "2026-09-14T09:30:00.000Z"
}- Stopping data that is already stopped returns
409and changes nothing. - A line in none of your data pools has no data to stop, and the call returns
422. - A line in a market that does not offer stopping data returns
422as well. The error'sdetailsays which of the two it was. - Telgea's own automated processes never undo a stop you made. Only you restore it.
To restore data, send DELETE on the same path, with an optional reason query parameter:
DELETE /v1/numbers/{numberId}/data-restriction?reason=Top-up%20receivedRestoring data that is not stopped returns 409. Data stays off if the customer is also over an allowance you set; clear that first.
Suspend and restore a line
Suspension acts on the whole line, so there is nothing to send with it and nothing for the response to report: both calls answer 204.
POST /v1/numbers/{numberId}/suspensionSuspending a line that is already suspended returns 409. A line in a market that does not offer suspension returns 400 and stays live. To restore it, send DELETE on the same path:
DELETE /v1/numbers/{numberId}/suspensionPermissions
Stopping data and suspending a line need numbers:suspend on your key; restoring either needs numbers:unsuspend.
Deciding when to act
Watch what your customers use with the usage feed and data pools, and stop data when a customer reaches what they paid for. To end a customer's line for good rather than pause it, end the line instead.
If a request times out, send it again with the same Idempotency-Key header: the API returns the original response instead of failing with a 409. See Retries and Idempotency.