> ## 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. # List number purchases > Returns the numbers you have bought through Vobiz, newest first, each with its full list of wallet charges. Released numbers stay in the list with `status: released`, so this is the billing history of every number you have owned. ## OpenAPI ````yaml openapi-sms.yaml GET /numbers/purchases 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/purchases: get: tags: - Numbers summary: List number purchases description: >- Returns the numbers you have bought through Vobiz, newest first, each with its full list of wallet charges. Released numbers stay in the list with `status: released`, so this is the billing history of every number you have owned. Use `nextBillingAt` to see when each active number renews and `charges` to reconcile setup and rental debits. operationId: list-purchases responses: '200': description: Your purchases. content: application/json: schema: $ref: '#/components/schemas/NumberPurchaseList' example: purchases: - 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' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/ServerError' '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.listPurchases() - lang: python label: Python SDK source: | from vobiz import Vobiz client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN") client.sms.numbers.list_purchases() - 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"), ) c.Sms.Numbers.ListPurchases( context.TODO(), ) - 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().listPurchases(); - lang: ruby label: Ruby SDK source: > require 'vobiz' client = Vobiz::Client.new(api_key: 'MA_XXXXXXXX', auth_token: 'YOUR_AUTH_TOKEN') client.sms.numbers.list_purchases - lang: csharp label: C# SDK source: | using Vobiz; using Vobiz.Sms; var client = new VobizApiClient("YOUR_AUTH_TOKEN", "MA_XXXXXXXX"); await client.Sms.Numbers.ListPurchasesAsync(); - lang: php label: PHP SDK source: > sms->numbers->listPurchases(); components: schemas: NumberPurchaseList: type: object properties: purchases: type: array description: >- Your purchases, newest first, including released numbers. Empty array when you have never bought a number. items: $ref: '#/components/schemas/NumberPurchase' description: The numbers you have bought, with their billing history. 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.