Cancelling Numbers

🚧 Alpha — upcoming in v1.0.16 (target: October 8, 2026). This feature is not yet live in production. The flow and payloads below are final per stage testing but may change until go-live. This page is published early so the link stays stable; it will be promoted to live once v1.0.16 ships.

Cancelling a number deactivates it with the carrier immediately. To stop numbers being cancelled by mistake, cancellation always takes two API calls:

Request the cancellation — you get back an AuthCode.
Submit the cancellation with that AuthCode — only then are the numbers cancelled.

⚠️ You cannot cancel a number without an AuthCode.

Every cancellation needs the AuthCode returned by cancel-order-request.

The AuthCode is valid for 5 minutes only.

Each AuthCode works once, for one order.

If the code expires or is used up, send a new cancel-order-request to get a new one.

How it works

Step	Call	What happens	Anything cancelled?
1	`POST /v1.0/numbers/cancel-order-request`	Your numbers are checked and a cancel order is created. You receive an `OrderId` and an `AuthCode`.	No
2	`POST /v1.0/numbers/cancel-order-submit`	The `AuthCode` is checked. The numbers are deactivated with the carrier.	Yes, immediately

Before you start

Authentication: API tokens are bound to one endpoint, so you need a token for each of the two endpoints: /v1.0/numbers/cancel-order-request and /v1.0/numbers/cancel-order-submit.
Cancel is no longer accepted on /numbers/status. Sending "StatusChange": "cancel" there returns HTTP 400: Cancel has moved to POST /numbers/cancel-order-request.
No future-dated cancellations. There is no effective date — a submitted cancellation happens right away.

Step 1 — Request the cancellation

POST /v1.0/numbers/cancel-order-request
Content-Type: application/json
Authorization: Bearer <token for cancel-order-request>

{
  "PhoneNumbers": [
    { "Number": "+12015550101" },
    { "Number": "+12015550102" }
  ]
}

Every number must exist, belong to your account, and be Active. If any number fails these checks, the whole request is refused and no order is created. A number that is already cancelled is not Active, so it is rejected here with Number is not active '...' (see Errors). The only time an already-cancelled number appears in FailedChange instead is when it is cancelled by something else between your request and your submit — see Step 2.

Response

{
  "OrderId": "JNUOID-6b1e2c4a-7d3f-4b2a-9c1e-2f5a8d9e0b11",
  "OrderDate": "2026-10-08T16:05:00Z",
  "OrderStatus": "Pending Confirmation",
  "AuthCode": "7K4Q9M",
  "AuthCodeExpiresAt": "2026-10-08T16:10:00Z",
  "NumbersChange": [
    { "Number": "+12015550101" },
    { "Number": "+12015550102" }
  ],
  "ConsentStatement": "I confirm that the 2 number(s) listed (+12015550101, +12015550102) will be cancelled and deactivated with the carrier immediately, and service on them will stop. A cancelled number can be reactivated within 30 days for a $5 recovery fee per number; after 30 days it is permanently released and cannot be recovered.",
  "Instructions": "To proceed, submit POST /v1.0/numbers/cancel-order-submit with this OrderId and AuthCode within 5 minutes. Submitting confirms the consent statement above. If the code expires, send a new cancel-order-request."
}

Keep both OrderId and AuthCode — you need both for step 2.

Check NumbersChange. These are exactly the numbers that will be cancelled. If anything is wrong, simply don’t submit — the order expires on its own.
Read the ConsentStatement. Submitting in step 2 counts as accepting it.

The AuthCode

The AuthCode is what turns a cancel request into an actual cancellation.

Rule	Detail
Required	`cancel-order-submit` will not cancel anything without the correct AuthCode.
Valid for 5 minutes	Counted from the request. The exact deadline is in `AuthCodeExpiresAt` (UTC). After that, the order is expired and the code no longer works.
One order only	The code only works with the `OrderId` it was issued with.
Single use	Once an order is submitted, the same code can’t be used again, even within the 5 minutes.
5 wrong attempts	After 5 incorrect codes for an order, that order is expired.
Newer request replaces older	A new `cancel-order-request` that includes any of the same numbers expires the earlier order and its code. Only the newest code works.
Format	6 characters: capital letters and digits. Look-alike characters (`0`, `O`, `1`, `I`, `L`) are never used. Not case-sensitive.
Not shown again	The AuthCode is only returned once, in the step 1 response. Telegent stores only a hashed form, so it can’t be looked up later.

💡 Best practice: submit straight after you’ve reviewed the request, well inside the 5 minutes. If you need longer (for example to get approval), send a new request when you’re ready.

Step 2 — Submit the cancellation

POST /v1.0/numbers/cancel-order-submit
Content-Type: application/json
Authorization: Bearer <token for cancel-order-submit>

{
  "OrderId": "JNUOID-6b1e2c4a-7d3f-4b2a-9c1e-2f5a8d9e0b11",
  "AuthCode": "7K4Q9M"
}

You don’t send the numbers again — they come from the order created in step 1.

Response

{
  "OrderId": "JNUOID-6b1e2c4a-7d3f-4b2a-9c1e-2f5a8d9e0b11",
  "OrderDate": "2026-10-08T16:05:00Z",
  "OrderStatus": "Complete",
  "NumbersChange": [
    { "Number": "+12015550101" },
    { "Number": "+12015550102" }
  ],
  "FailedChange": []
}

`OrderStatus`	Meaning
`Complete`	The carrier deactivated the numbers in `NumbersChange`. Any number in `FailedChange` was refused and is still Active.
`Failed`	The carrier refused every number. Nothing was cancelled; all numbers are still Active.

If you subscribe to Order_Update webhooks, you also receive one webhook with the order’s final status.

After cancellation — the 30-day window

Number status	When	Meaning
`Cancelled - Pending Delete`	Immediately after a successful cancellation	Deactivated with the carrier, but held for 30 days. It can still be reactivated, for a $5 recovery fee per number.
`Cancelled`	30 days after the cancellation date	Permanently released. It can’t be recovered.

List numbers still in the window with the inventory filter:

GET /v1.0/numbers/inventory?Filter=Cancelled%20-%20Pending%20Delete

ℹ️ Reactivation of a Cancelled - Pending Delete number (within 30 days, $5 recovery fee) is delivered by POST /v1.0/numbers/reactivate. Self-service reactivation ships in or shortly after v1.0.16 — see the Reactivate endpoint page for its status.

Errors

Business errors return HTTP 400 with a message, and nothing is cancelled.

⚠️ One non-400 case to watch. The two calls use separately scoped tokens. Sending the cancel-order-request token to cancel-order-submit (or vice versa) returns 401 Unauthorized — not a 400. If submit returns 401 while your AuthCode is counting down, check you’re using the submit token.

`cancel-order-request`

Message	What to do
`Invalid request. Please include phone-numbers to 'cancel'.`	Send at least one number.
`Number not found!`	Check the number.
`Number does not belong to account ...`	Only send numbers on your own account.
`Number is not active '...'.`	Only Active numbers can be cancelled — for example, reactivate a parked number first.

`cancel-order-submit`

Message	What to do
`Invalid request. OrderId and AuthCode are required.`	Send both `OrderId` and `AuthCode`.
`Cancel order not found.`	Check the `OrderId` — it must be a cancel order on your own account.
`Auth code has expired. Send a new cancel-order-request.`	The 5 minutes passed, there were 5 wrong attempts, or a newer request replaced this order. Start again from step 1.
`Invalid auth code.`	The code is wrong. Check it and try again. After 5 wrong attempts the order expires.
`Cancel order has already been submitted.`	This order was already processed. Check its status with `GET /v1.0/numbers/order?OrderId=...`.

An already-cancelled number is normally rejected earlier, at cancel-order-request, with Number is not active '...' (it is no longer Active). It only reaches FailedChange here when a number is cancelled by something else between your request and your submit — in that case it comes back with a clear error rather than being cancelled again, for example: Number is already cancelled '+12015550101' (Cancelled - Pending Delete).

Quick checklist

Get a token for cancel-order-request and one for cancel-order-submit.
Call cancel-order-request and keep the OrderId and AuthCode.
Check NumbersChange and read the ConsentStatement.
Call cancel-order-submit within 5 minutes (before AuthCodeExpiresAt).
Check OrderStatus and FailedChange in the response.
If the code expired, start again from step 1.

FAQ

Can I reuse an AuthCode? No. Each code works once, for the one order it was issued with. I lost the AuthCode — can Telegent resend it? No. Only a hashed form is stored. Send a new cancel-order-request, which also expires the old order. Can I get a longer expiry? No — the expiry is fixed at 5 minutes. Request the cancellation only when you’re ready to submit it. What if I change my mind after step 1? Do nothing. The order expires after 5 minutes and no numbers are affected. What if I change my mind after step 2? The numbers are already deactivated. During the 30-day pending-delete window, reactivate each one with POST /v1.0/numbers/reactivate for a $5 recovery fee per number. After 30 days they can’t be recovered. Can I schedule a cancellation for a future date? Not at the moment. Every cancellation happens when it’s submitted. Want to deactivate a number but keep it? Park it instead of cancelling — parking keeps the number reserved for you without deactivating it. See your MSA fee schedule.

MVNO Guide

Guides

Informational Documents

How it works

Before you start

Step 1 — Request the cancellation

Response

The AuthCode

Step 2 — Submit the cancellation

Response

After cancellation — the 30-day window

Errors

`cancel-order-request`

`cancel-order-submit`

Quick checklist

FAQ

​How it works

​Before you start

​Step 1 — Request the cancellation

​Response

​The AuthCode

​Step 2 — Submit the cancellation

​Response

​After cancellation — the 30-day window

​Errors

​cancel-order-request

​cancel-order-submit

​Quick checklist

​FAQ

How it works

Before you start

Step 1 — Request the cancellation

Response

The AuthCode

Step 2 — Submit the cancellation

Response

After cancellation — the 30-day window

Errors

`cancel-order-request`

`cancel-order-submit`

Quick checklist

FAQ