> ## Documentation Index > Fetch the complete documentation index at: https://docs.telegent.com/llms.txt > Use this file to discover all available pages before exploring further. # Cancelling Numbers > The two-stage number cancellation flow — request, review the consent statement, and submit with an auth code. Immediate carrier deactivation with a 30-day recovery window. > 🚧 **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**: 1. **Request** the cancellation — you get back an **AuthCode**. 2. **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
```mermaid theme={null} sequenceDiagram autonumber participant You participant API participant TMO as Carrier You->>API: cancel-order-request (PhoneNumbers) API-->>You: OrderId + AuthCode (5-min) + Consent Note over You: Review numbers + consent rect rgba(255, 200, 0, 0.15) Note over You,API: ⏱ Submit within 5 min You->>API: cancel-order-submit (OrderId + AuthCode) end API->>TMO: Deactivate numbers API-->>You: OrderStatus Complete / Failed Note over API: "Cancelled - Pending Delete" 30 days → "Cancelled" ```
| 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 ```http theme={null} POST /v1.0/numbers/cancel-order-request Content-Type: application/json Authorization: Bearer { "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](#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](#step-2--submit-the-cancellation). ### Response ```json theme={null} { "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.
```mermaid theme={null} stateDiagram-v2 [*] --> PendingConfirmation: cancel-order-request
(AuthCode issued, 5-min clock starts) PendingConfirmation --> Submitted: cancel-order-submit
with correct AuthCode in time PendingConfirmation --> Expired: 5 minutes passed PendingConfirmation --> Expired: 5 wrong AuthCodes PendingConfirmation --> Expired: newer request for the same number(s) Submitted --> Complete: carrier deactivated the numbers Submitted --> Failed: carrier refused every number Expired --> [*]: send a new cancel-order-request Complete --> [*] Failed --> [*] PendingConfirmation: Pending Confirmation ```
## Step 2 — Submit the cancellation ```http theme={null} POST /v1.0/numbers/cancel-order-submit Content-Type: application/json Authorization: Bearer { "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 ```json theme={null} { "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: ```http theme={null} 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.