> ## Documentation Index > Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Release a number > Cancels a number you bought through Vobiz and removes it from your account. The number stops sending and receiving messages immediately, and monthly rental stops. ## OpenAPI ````yaml openapi-sms.yaml POST /numbers/{e164}/release openapi: 3.0.3 info: title: Vobiz Messaging API description: > Send and receive SMS, MMS and RCS messages, buy messaging numbers, register for US 10DLC and toll-free, run broadcasts, manage conversations, opt-outs and webhooks. **Base URL:** `https://api.vobiz.ai/api/v1/sms` **Authentication:** every request needs the `X-Auth-ID` and `X-Auth-Token` headers. The account is taken from your credentials; you never put an account ID in a path or body. Field names in this API are camelCase. version: '1.0' contact: email: support@vobiz.ai url: https://vobiz.ai servers: - url: https://api.vobiz.ai/api/v1/sms description: Production security: - AuthID: [] AuthToken: [] tags: - name: Messages description: Send messages and inspect their delivery state. - name: Numbers description: >- Messaging-capable numbers on your account, inventory search, purchase and release. - name: Coverage description: Where you can send, per country. - name: Conversations description: Two-way threads between one of your numbers and a contact. - name: Opt-outs description: Numbers that must not receive messages on a channel. - name: Webhooks description: Subscriptions that deliver message and broadcast events to your server. - name: Broadcasts description: Bulk sends from an uploaded recipient list. - name: RCS Senders description: RCS sender (agent) identities and their message templates. - name: 10DLC Brands description: US 10DLC brand registration. - name: 10DLC Campaigns description: US 10DLC campaigns, toll-free verification and supporting documents. paths: /numbers/{e164}/release: post: tags: - Numbers summary: Release a number description: >- Cancels a number you bought through Vobiz and removes it from your account. The number stops sending and receiving messages immediately, and monthly rental stops. The setup fee and the current month are not refunded, and a released number cannot be restored. The call has no request body and returns the purchase with `status: released`. Run it only with your own credentials once you are sure you no longer need the number. operationId: release-number parameters: - name: e164 in: path required: true description: >- The number to release, in E.164 format, for example `+14155550100`. In raw HTTP requests, URL-encode the `+` as `%2B`; the SDKs encode it for you. A value that is not an E.164 number returns `400`, and a number that is not on your account returns `404`. schema: type: string example: '+14155550100' responses: '200': description: >- The number is released. `status` is `released`, `releasedAt` is set and `nextBillingAt` is `null`. content: application/json: schema: $ref: '#/components/schemas/ReleaseNumberResponse' example: purchase: id: 5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e accountId: MA_XXXXXXXX provider: internal e164: '+14155550100' countryCode: US type: VIRTUAL_LONG_NUMBER capabilities: - VOICE - SMS - MMS setupAmount: 1 monthlyAmount: 1 currency: USD status: released purchasedAt: '2026-10-12T09:06:44Z' nextBillingAt: null releasedAt: '2026-10-20T14:02:10Z' createdAt: '2026-10-12T09:06:42Z' updatedAt: '2026-10-20T14:02:10Z' charges: - purchaseId: 5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e kind: purchase periodStart: '2026-10-12T09:06:42Z' amount: 2 currency: USD status: paid reference: sms_number_purchase:5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e attempts: 1 attemptedAt: '2026-10-12T09:06:42Z' '400': description: The path value is not an E.164 number. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: e164 must be a number in E.164 format '401': $ref: '#/components/responses/Unauthorized' '404': description: The number is not on your account. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: number not found '409': description: The number cannot be released through the API right now. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not-self-serve: value: error: >- this number was not bought through the console; contact support to release it in-progress: value: error: the purchase of this number is still in progress '500': $ref: '#/components/responses/ServerError' '502': description: The upstream inventory could not release the number. Retry later. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: number provider could not release the number; try again later '503': description: Purchasing is paused. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: number purchasing is not available x-codeSamples: - lang: typescript label: Node SDK source: > import { VobizClient } from "@vobiz/sdk"; const client = new VobizClient({ apiKey: "MA_XXXXXXXX", authToken: "YOUR_AUTH_TOKEN" }); await client.sms.numbers.releaseNumber({ e164: "+14155550100" }) - lang: python label: Python SDK source: | from vobiz import Vobiz client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN") client.sms.numbers.release_number( e164="+14155550100", ) - lang: go label: Go SDK source: | import ( "context" vobiz "github.com/vobiz-ai/Vobiz-Go-SDK" "github.com/vobiz-ai/Vobiz-Go-SDK/client" "github.com/vobiz-ai/Vobiz-Go-SDK/option" "github.com/vobiz-ai/Vobiz-Go-SDK/sms" ) c := client.NewClient( option.WithAPIKey("MA_XXXXXXXX"), option.WithAuthToken("YOUR_AUTH_TOKEN"), ) request := &sms.ReleaseNumberRequest{ E164: "+14155550100", } c.Sms.Numbers.ReleaseNumber( context.TODO(), request, ) - lang: java label: Java SDK source: | import com.vobiz.api.VobizApiClient; VobizApiClient client = VobizApiClient .builder() .apiKey("MA_XXXXXXXX") .authToken("YOUR_AUTH_TOKEN") .build(); client.sms().numbers().releaseNumber( "+14155550100", ReleaseNumberRequest .builder() .build() ); - lang: ruby label: Ruby SDK source: > require 'vobiz' client = Vobiz::Client.new(api_key: 'MA_XXXXXXXX', auth_token: 'YOUR_AUTH_TOKEN') client.sms.numbers.release_number(e164: "+14155550100") - lang: csharp label: C# SDK source: > using Vobiz; using Vobiz.Sms; var client = new VobizApiClient("YOUR_AUTH_TOKEN", "MA_XXXXXXXX"); await client.Sms.Numbers.ReleaseNumberAsync(new ReleaseNumberRequest { E164 = "+14155550100" }); - lang: php label: PHP SDK source: > sms->numbers->releaseNumber( '+14155550100', ); components: schemas: ReleaseNumberResponse: type: object properties: purchase: allOf: - $ref: '#/components/schemas/NumberPurchase' description: >- The purchase record after release, with `status: released`, `releasedAt` set and `nextBillingAt` set to `null`. description: The result of releasing a number. Error: type: object description: >- The body of every error response: a flat object with one `error` string that explains what went wrong. Use the HTTP status code to decide how to handle the error, and log `error` for diagnosis. required: - error properties: error: type: string example: 'recipient has opted out: +14155550123' description: >- Human-readable explanation of the error, for example `phoneNumber is required` or `recipient has opted out: +14155550123`. Branch on the HTTP status code rather than on this text. NumberPurchase: type: object description: >- A number you bought through Vobiz, with its price, lifecycle status and billing history. properties: id: type: string format: uuid example: 5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e description: Unique identifier of the purchase (UUID). accountId: type: string example: MA_XXXXXXXX description: >- Auth ID of the account that owns the purchase, for example `MA_XXXXXXXX`. provider: type: string description: Internal routing identifier; do not rely on its value. e164: type: string example: '+14155550100' description: >- The purchased number in E.164 format. Use it as the path value of `POST /numbers/{e164}/release`. countryCode: type: string example: US description: ISO 3166-1 alpha-2 code of the number's country. type: type: string example: VIRTUAL_LONG_NUMBER description: >- Inventory type of the number in upper case, for example `VIRTUAL_LONG_NUMBER`. capabilities: type: array items: type: string example: - VOICE - SMS - MMS description: >- Upper-case capability labels for the number, for example `SMS`, `MMS` and `VOICE`. setupAmount: type: number description: One-time setup fee charged at purchase, in `currency`. example: 1 monthlyAmount: type: number example: 1 description: Monthly rental for the number, in `currency`. currency: type: string example: USD description: ISO 4217 code of the amounts, for example `USD`. status: type: string enum: - pending - debited - purchased - past_due - failed - refunded - released description: >- Lifecycle state: `pending` (created), `debited` (charged, purchase in progress), `purchased` (active and billing monthly), `past_due` (a renewal has been failing for more than 7 days), `failed` (did not complete), `refunded` (charge returned after a failed purchase) or `released` (you released it). purchasedAt: type: string format: date-time nullable: true example: '2026-10-12T09:06:44Z' description: >- When the number went live on your account (ISO 8601). `null` until the purchase completes. nextBillingAt: type: string format: date-time nullable: true description: >- When the next monthly rental is charged (ISO 8601). `null` before the purchase completes and after release. example: '2026-11-12T09:06:44Z' releasedAt: type: string format: date-time nullable: true example: null description: >- When you released the number (ISO 8601). `null` while the number is active. createdAt: type: string format: date-time example: '2026-10-12T09:06:42Z' description: When the purchase was started (ISO 8601). updatedAt: type: string format: date-time example: '2026-10-12T09:06:44Z' description: >- When the purchase last changed, for example on renewal or release (ISO 8601). charges: type: array nullable: true description: >- Wallet charges raised for this number, oldest first: the initial `purchase` charge and each monthly `rental`. `null` when none have been raised. items: $ref: '#/components/schemas/NumberBillingCharge' NumberBillingCharge: type: object description: >- One wallet charge raised for a purchased number: the initial purchase charge or a monthly renewal. properties: purchaseId: type: string format: uuid example: 5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e description: '`id` of the purchase this charge belongs to.' kind: type: string enum: - purchase - rental description: >- `purchase` for the setup fee plus the first month, charged when you buy; `rental` for each later monthly renewal. periodStart: type: string format: date-time example: '2026-10-12T09:06:42Z' description: Start of the billing period this charge covers (ISO 8601). amount: type: number example: 2 description: >- Amount charged, in `currency`. For `kind: purchase` this is the setup fee plus the first month. currency: type: string example: USD description: ISO 4217 code of `amount`, for example `USD`. status: type: string enum: - pending - paid - failed - refunded description: >- `pending` while the charge is waiting to be collected, `paid` once collected, `failed` when collection failed, `refunded` when the amount was returned to your wallet. reference: type: string description: >- Ledger reference for the charge, as it appears in your wallet transactions. Quote it to support when reconciling. example: sms_number_purchase:5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e attempts: type: integer example: 1 description: >- How many times collection of this charge has been attempted. Values above `1` mean earlier attempts failed, typically for lack of balance. attemptedAt: type: string format: date-time example: '2026-10-12T09:06:42Z' description: When collection was last attempted (ISO 8601). responses: Unauthorized: description: Missing or invalid `X-Auth-ID` / `X-Auth-Token`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing or invalid credentials ServerError: description: Unexpected error. Retry with the same idempotency key where one applies. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: internal error securitySchemes: AuthID: type: apiKey in: header name: X-Auth-ID description: Your Vobiz account Auth ID (`MA_XXXXXXXX`). AuthToken: type: apiKey in: header name: X-Auth-Token description: Your Vobiz account Auth Token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.