> ## 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. # Purchase a number > Buys a number returned by `GET /numbers/available` and routes it to your account for messaging. ## OpenAPI ````yaml openapi-sms.yaml POST /numbers/purchase 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/purchase: post: tags: - Numbers summary: Purchase a number description: >- Buys a number returned by `GET /numbers/available` and routes it to your account for messaging. This call spends money: it debits the setup fee and the first month's rental from your wallet before the number is bought, and the rental renews monthly until you release the number. If the purchase cannot complete after the debit, your wallet is refunded and the error message says so. Run it only with your own credentials once you have confirmed the number and price. A `numbers.updated` WebSocket event is published when the number goes live; a US number then needs a 10DLC campaign or toll-free verification before it can send to US recipients. operationId: purchase-number requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PurchaseNumberRequest' examples: us: summary: US number value: e164: '+14155550100' country: US keyed: summary: Number with an inventory key value: e164: '+442079460100' country: GB numberKey: YOUR_NUMBER_KEY responses: '201': description: The number is bought, charged and routed to your account. content: application/json: schema: $ref: '#/components/schemas/PurchaseNumberResponse' 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: purchased purchasedAt: '2026-10-12T09:06:44Z' nextBillingAt: '2026-11-12T09:06:44Z' releasedAt: null createdAt: '2026-10-12T09:06:42Z' updatedAt: '2026-10-12T09:06:44Z' 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' number: id: 1042 e164: '+14155550100' provider: internal channelCapabilities: - sms - mms accountId: MA_XXXXXXXX countryCode: US createdAt: '2026-10-12T09:06:44Z' '400': description: The body is invalid or the number does not match the country. content: application/json: schema: $ref: '#/components/schemas/Error' examples: e164: value: error: e164 must be a number in E.164 format country-missing: value: error: country is required country-format: value: error: country must be an ISO 3166-1 alpha-2 code mismatch: value: error: number does not belong to the given country body: value: error: invalid request body '401': $ref: '#/components/responses/Unauthorized' '402': description: >- Your wallet balance does not cover the setup fee plus the first month. Top up and retry. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: insufficient balance '409': description: >- The number is already yours, is taken, or a purchase of it is already running. content: application/json: schema: $ref: '#/components/schemas/Error' examples: own: value: error: you already have this number taken: value: error: number is not available gone: value: error: number is no longer available in-progress: value: error: a purchase of this number is already in progress '422': description: The number cannot be sold to your account as requested. content: application/json: schema: $ref: '#/components/schemas/Error' examples: india: value: error: India uses DLT sender IDs, not long codes country: value: error: SMS numbers are not sold for country FR documents: value: error: this country needs regulatory documents; contact support capability: value: error: number is not SMS-capable '500': description: >- Unexpected error. The message says whether a refund was issued or support needs to finish activation. content: application/json: schema: $ref: '#/components/schemas/Error' examples: refunded: value: error: >- the purchase could not be completed; your wallet has been refunded activation: value: error: >- number purchased but could not be activated; contact support '502': description: >- The upstream inventory could not complete the purchase. The error says whether your wallet was refunded automatically. content: application/json: schema: $ref: '#/components/schemas/Error' examples: refunded: value: error: >- number provider could not complete the purchase; your wallet has been refunded refund-pending: value: error: >- number provider: number already assigned; your refund is being processed by support unavailable: value: error: number provider unavailable; try again later '503': description: Purchasing or billing is paused. Retry later. content: application/json: schema: $ref: '#/components/schemas/Error' examples: purchasing: value: error: number purchasing is not available billing: value: error: billing is unavailable; try again later 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.purchaseNumber({ e164: "+14155550100", country: "US" }) - lang: python label: Python SDK source: | from vobiz import Vobiz client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN") client.sms.numbers.purchase_number( e164="+14155550100", country="US", ) - 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.PurchaseNumberRequest{ E164: "+14155550100", Country: "US", } c.Sms.Numbers.PurchaseNumber( 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().purchaseNumber( PurchaseNumberRequest .builder() .e164("+14155550100") .country("US") .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.purchase_number( e164: "+14155550100", country: "US" ) - lang: csharp label: C# SDK source: | using Vobiz; using Vobiz.Sms; var client = new VobizApiClient("YOUR_AUTH_TOKEN", "MA_XXXXXXXX"); await client.Sms.Numbers.PurchaseNumberAsync( new PurchaseNumberRequest { E164 = "+14155550100", Country = "US" } ); - lang: php label: PHP SDK source: > sms->numbers->purchaseNumber( new PurchaseNumberRequest([ 'e164' => '+14155550100', 'country' => 'US', ]), ); components: schemas: PurchaseNumberRequest: type: object required: - e164 - country properties: e164: type: string description: >- The number to buy, in E.164 format, exactly as returned in `e164` by `GET /numbers/available`. Required. example: '+14155550100' country: type: string description: >- ISO 3166-1 alpha-2 code of the number's country, for example `US`. Required, and must match the number; a mismatch returns `400`. example: US numberKey: type: string description: >- The `numberKey` from `GET /numbers/available`. Required when the search result has a non-empty `numberKey`, as for `CA` and `GB` numbers; omit it for US numbers, which are bought by `e164` alone. description: The number to buy, taken from a `GET /numbers/available` result. PurchaseNumberResponse: type: object properties: purchase: allOf: - $ref: '#/components/schemas/NumberPurchase' description: >- The purchase record, with `status: purchased`, the amounts charged and `nextBillingAt`. number: allOf: - $ref: '#/components/schemas/NumberRouting' description: >- The routing record that connects the number to your account. The number appears in `GET /numbers` from this point. description: >- The result of a successful purchase: the billing record and the routing record. 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' NumberRouting: type: object description: >- The routing record that connects a purchased number to your account for messaging. properties: id: type: integer example: 1042 description: Numeric identifier of the routing record. e164: type: string example: '+14155550100' description: The routed number in E.164 format. provider: type: string description: Internal routing identifier; do not rely on its value. channelCapabilities: type: array description: >- Lower-case messaging channels routed on the number, for example `sms` and `mms`. items: type: string example: - sms - mms accountId: type: string example: MA_XXXXXXXX description: >- Auth ID of the account the number is routed to, for example `MA_XXXXXXXX`. countryCode: type: string example: US description: ISO 3166-1 alpha-2 code of the number's country. createdAt: type: string format: date-time example: '2026-10-12T09:06:44Z' description: When the number was routed to your account (ISO 8601). 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 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.