> ## 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. # Numbers - Cancel Order Request > > 🚧 **Alpha — upcoming in v1.0.16 (target October 8, 2026). Not yet live in production.** Stage 1 of the two-stage number cancellation flow. Validates the numbers, creates a cancel order, and returns an `AuthCode` (valid 5 minutes) plus the `ConsentStatement` to review. **No numbers are cancelled at this stage.** **What this does:** Checks that every number exists, belongs to your account, and is Active, then returns an `OrderId`, a single-use `AuthCode`, `AuthCodeExpiresAt`, the `NumbersChange` list, and the consent statement. If any number fails validation the whole request is refused and no order is created. See the [Cancelling Numbers guide](/guides/cancelling-numbers) for the full flow and AuthCode rules. **Next step:** - Confirm the cancellation — `POST /v1.0/numbers/cancel-order-submit` (within 5 minutes) ## OpenAPI ````yaml /api-reference/openapi.json post /v1.0/numbers/cancel-order-request openapi: 3.0.3 info: title: mPaaS Core APIs version: 1.0.8 description: >- The Telegent mPaaS (Mobile Platform as a Service) API gives you full programmatic control over mobile phone numbers, messaging, voice routing, subscribers, and account management. Use these APIs to provision MVNO and IoT numbers, send and receive SMS/MMS, configure intelligent call routing, manage subscriber accounts, and apply AI Guardian controls. All requests require a Bearer token obtained from the Authentication endpoint. For support, visit https://support.telegent.com/support/home contact: name: Support email: support@telegent.com termsOfService: https://telegent.com/terms license: name: Use under LICX url: https://telegent.com/license servers: - url: https://api.telegent.com security: - BearerAuth: [] tags: - name: OAuth2 - name: Accounts - name: Distributors - name: Message - name: Numbers - name: Voicemail - name: Packages - name: Products - name: Services - name: Sims - name: Subscribers - name: Subscriptions - name: Voice - name: Workgroups - name: Health Status paths: /v1.0/numbers/cancel-order-request: post: tags: - Numbers summary: Numbers - Cancel Order Request description: >- > 🚧 **Alpha — upcoming in v1.0.16 (target October 8, 2026). Not yet live in production.** Stage 1 of the two-stage number cancellation flow. Validates the numbers, creates a cancel order, and returns an `AuthCode` (valid 5 minutes) plus the `ConsentStatement` to review. **No numbers are cancelled at this stage.** **What this does:** Checks that every number exists, belongs to your account, and is Active, then returns an `OrderId`, a single-use `AuthCode`, `AuthCodeExpiresAt`, the `NumbersChange` list, and the consent statement. If any number fails validation the whole request is refused and no order is created. See the [Cancelling Numbers guide](/guides/cancelling-numbers) for the full flow and AuthCode rules. **Next step:** - Confirm the cancellation — `POST /v1.0/numbers/cancel-order-submit` (within 5 minutes) parameters: [] requestBody: required: true content: application/json: schema: type: object required: - PhoneNumbers properties: PhoneNumbers: type: array description: >- Numbers to cancel. Each must exist, belong to your account, and be Active. items: type: object required: - Number properties: Number: type: string description: Phone number in E.164 format. example: '+12015550101' responses: '200': description: Cancel order created — review and submit within 5 minutes content: application/json: schema: type: object properties: OrderId: type: string description: >- Identifier for this cancel order. Pass it to cancel-order-submit. OrderDate: type: string format: date-time description: When the order was created (UTC). OrderStatus: type: string description: Order state — `Pending Confirmation` until submitted. AuthCode: type: string description: >- Single-use confirmation code, valid 5 minutes. Returned once and only as a hash afterwards. AuthCodeExpiresAt: type: string format: date-time description: UTC expiry of the AuthCode. NumbersChange: type: array description: The numbers that will be cancelled when you submit. items: type: object properties: Number: type: string description: Phone number in E.164 format. ConsentStatement: type: string description: The statement you accept by submitting. Instructions: type: string description: Human-readable next-step instructions. examples: example: value: 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' ConsentStatement: >- I confirm that the 1 number(s) listed (+12015550101) 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. '400': description: >- Bad Request — for example: "Invalid request. Please include phone-numbers to 'cancel'.", "Number not found!", "Number does not belong to account ...", or "Number is not active '...'." content: text/plain: schema: $ref: '#/components/schemas/BadRequest_Result' application/json: schema: $ref: '#/components/schemas/BadRequest_Result' examples: example: value: StatusCode: 400 Message: Number is not active '+12015550101'. text/json: schema: $ref: '#/components/schemas/BadRequest_Result' '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/Unauthorized_Result' application/json: schema: $ref: '#/components/schemas/Unauthorized_Result' examples: example: value: StatusCode: 401 Message: >- Unauthorized: Bearer token is missing, expired, or invalid. Re-authenticate via POST /v1.0/oauth2/tokens. text/json: schema: $ref: '#/components/schemas/Unauthorized_Result' '403': description: Forbidden content: text/plain: schema: $ref: '#/components/schemas/Forbidden_Result' application/json: schema: $ref: '#/components/schemas/Forbidden_Result' examples: example: value: StatusCode: 403 Message: >- Forbidden: your token does not have permission to access this resource. Check the ApiEndpoint scope. text/json: schema: $ref: '#/components/schemas/Forbidden_Result' '404': description: Not Found content: text/plain: schema: $ref: '#/components/schemas/NotFound_Result' application/json: schema: $ref: '#/components/schemas/NotFound_Result' examples: example: value: StatusCode: 404 Message: >- Not found: the requested resource does not exist or belongs to a different account. text/json: schema: $ref: '#/components/schemas/NotFound_Result' '405': description: Method Not Allowed content: text/plain: schema: $ref: '#/components/schemas/MethodNotAllowed_Result' application/json: schema: $ref: '#/components/schemas/MethodNotAllowed_Result' examples: example: value: StatusCode: 405 Message: >- Method not allowed: verify the HTTP method required for this endpoint. text/json: schema: $ref: '#/components/schemas/MethodNotAllowed_Result' '408': description: Request Timeout content: text/plain: schema: $ref: '#/components/schemas/RequestTimeout_Result' application/json: schema: $ref: '#/components/schemas/RequestTimeout_Result' examples: example: value: StatusCode: 408 Message: >- Request timeout: the server did not receive a complete request within the allowed time. Retry with exponential backoff. text/json: schema: $ref: '#/components/schemas/RequestTimeout_Result' '429': description: Too Many Requests content: text/plain: schema: $ref: '#/components/schemas/TooManyRequests_Result' application/json: schema: $ref: '#/components/schemas/TooManyRequests_Result' examples: example: value: StatusCode: 429 Message: >- Too many requests: rate limit exceeded. Slow your request cadence and retry after a short delay. text/json: schema: $ref: '#/components/schemas/TooManyRequests_Result' '500': description: Server Error content: text/plain: schema: $ref: '#/components/schemas/InternalServerError_Result' application/json: schema: $ref: '#/components/schemas/InternalServerError_Result' examples: example: value: StatusCode: 500 Message: >- Internal server error: an unexpected error occurred. If the problem persists contact support@telegent.com. text/json: schema: $ref: '#/components/schemas/InternalServerError_Result' '503': description: Service Unavailable content: text/plain: schema: $ref: '#/components/schemas/ServiceUnavailable_Result' application/json: schema: $ref: '#/components/schemas/ServiceUnavailable_Result' examples: example: value: StatusCode: 503 Message: >- Service unavailable: the API is temporarily unavailable. Retry after a short delay. text/json: schema: $ref: '#/components/schemas/ServiceUnavailable_Result' '504': description: Gateway Timeout content: text/plain: schema: $ref: '#/components/schemas/GatewayTimeout_Result' application/json: schema: $ref: '#/components/schemas/GatewayTimeout_Result' examples: example: value: StatusCode: 504 Message: >- Gateway timeout: an upstream service did not respond in time. Retry with exponential backoff. text/json: schema: $ref: '#/components/schemas/GatewayTimeout_Result' x-codeSamples: - lang: JSON source: |- { "PhoneNumbers": [ { "Number": "+12015550101" } ] } - lang: cURL source: >- curl -X POST https://api.telegent.com/v1.0/numbers/cancel-order-request \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "PhoneNumbers": [ { "Number": "+12015550101" } ] }' components: schemas: BadRequest_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false Unauthorized_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false Forbidden_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false NotFound_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false MethodNotAllowed_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false RequestTimeout_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false TooManyRequests_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false InternalServerError_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false ServiceUnavailable_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false GatewayTimeout_Result: required: - StatusCode type: object properties: StatusCode: type: integer format: int32 Message: type: string nullable: true additionalProperties: false ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.