How long can I keep a rental?

One day is the minimum, and longer intervals go up from there. Ask the intervals endpoint what is actually on offer for your service and country rather than assuming a fixed set — the options vary.

How many messages does a rental receive?

As many as arrive during the rental. That is the whole difference from an activation, which stops after one code.

How do I avoid re-reading the same message?

Pass last_id when you poll. Each call then returns only messages newer than the one you already have, so you can poll aggressively without deduplicating on your side.

Can I extend a rental that is about to expire?

Yes, while it is still active, using any interval currently available for it. Extending is cheaper and less disruptive than renting a fresh number, since the number itself does not change.

What happens if I cancel?

Cancelling inside the eligible window refunds the rental. Outside that window the rental simply runs to the end of its term — so cancel as soon as you know you are finished.

Can I buy a rental without an account?

Yes. The x402 path works exactly as it does for activations: send the purchase, sign the challenge that comes back, and repeat the identical request.

Reusable rental · REST + MCP

A number that stays yours

Rent a private number for a day or more and keep receiving messages the whole time. Check which intervals are available and what they cost, buy one, then extend it if a job runs long or cancel it when you are done.

Connect your AI client Jump to REST quickstart

Lifetime: A day or more
What you get: Multiple SMS messages
Best for: Sessions, testing, and ongoing access

800+ services covered

200+ countries in stock

No signup to browse prices

Per number never a subscription

Start building

Get your API key in under a minute

Sign up with an email address — no card, no sales call. The sign-in link brings you straight back to this page and hands you a key that works with both the REST API and the MCP server.

Free to create. You pay per number, never a subscription.

How it works

Four steps, start to finish

Every step below maps to real endpoints and real tools. Hold on to the id a purchase gives you — everything after the buy hangs off it.

1

Discover live inventory

List services, countries, and rentable intervals with their exact current USD prices.

GET /v1/sms/rental/servicesGET /v1/sms/rental/countriesGET /v1/sms/rental/intervals sms_rental_list_servicessms_rental_list_countriessms_rental_list_intervals
2

Rent for an interval

Choose prepaid balance or accountless x402, then keep the returned rental id.

POST /v1/sms/rental/numbers sms_rental_buy_number
3

Collect messages

Poll throughout the rental and use cursors to retrieve multiple messages without duplicates.

GET /v1/sms/rental/numbers/{id}/codes sms_rental_get_codes
4

Cancel or extend

Cancel when eligible for a refund, or list the available extension durations and prices and extend an active rental.

POST /v1/sms/rental/numbers/{id}/cancelGET /v1/sms/rental/numbers/{id}/extend-optionsPOST /v1/sms/rental/numbers/{id}/extend sms_rental_cancelsms_rental_list_extend_optionssms_rental_extend

Set up once

Put Voxisim inside your AI client

Connect the hosted endpoint and your agent can price options, buy a number, and hand you the code without you writing a request. Nothing to install: there is no package, no local server, and no container — just one URL and a browser sign-in.

Hosted endpoint https://api.voxisim.com/mcp

Streamable HTTP · OAuth or bearer key

01
Add the endpoint

Choose your client below and copy the block it needs.
02
Sign in once

Approve the browser OAuth prompt, or pass a vxs_ key from your secret manager if you would rather not use OAuth.
03
Just ask

Your agent picks the right tools and carries ids between them, so a single sentence covers the whole lifecycle.

Claude

Web + Desktop

OAuth

Open Settings → Connectors, add a custom connector named Voxisim, then paste the hosted endpoint.

No config file

https://api.voxisim.com/mcp

Select Connect and finish the browser sign-in. Enable Voxisim from Search and tools in your chat.

Codex

App + CLI + IDE

OAuth

Add one server table. Codex shares this configuration across its local app, CLI, and IDE extension.

~/.codex/config.toml

[mcp_servers.voxisim]
url = "https://api.voxisim.com/mcp"

# Authenticate once from a terminal:
# codex mcp login voxisim

Restart the client, then use /mcp to confirm that Voxisim is connected.

Claude Code

Terminal

OAuth

CLI command

claude mcp add --transport http --scope user \
  voxisim https://api.voxisim.com/mcp

Run /mcp inside Claude Code and follow the browser authentication prompt.

Cursor

Editor + Agent CLI

OAuth

Add the remote server globally, or place the same object in .cursor/mcp.json for one project.

~/.cursor/mcp.json

{
  "mcpServers": {
    "voxisim": {
      "url": "https://api.voxisim.com/mcp"
    }
  }
}

Open Settings → Tools & MCP and authenticate Voxisim, then verify its tools are enabled.

Alternative

Prefer a plain API key?

Register a vxs_ key once and send it as a bearer token. It is shown exactly once, so put it in your secret manager — never in a config file you commit.

Terminal

curl -X POST https://api.voxisim.com/mcp/register \
  -H 'content-type: application/json' \
  -d '{"label":"my-mcp-client"}'

Agent workflow

What your agent actually does

The tools are typed and named for the job, so results come back as structured fields rather than prose an agent has to re-read. Purchases can draw on your balance or answer with a payment challenge your agent settles from a wallet.

9 tools for this product

sms_rental_list_services
sms_rental_list_countries
sms_rental_list_intervals
sms_rental_buy_number
sms_rental_get_codes
sms_rental_list_numbers
sms_rental_cancel
sms_rental_list_extend_options
sms_rental_extend

Try asking your agent

Compare the live rental intervals for WhatsApp in the United States and show me the exact prices.

Rent a number for the shortest available interval, then watch it for new messages.

List my active rentals and extend the one expiring soonest by an available interval.

REST

REST quickstart

Discovery is public — run the first block right now with no account. Buying takes either a prepaid key or a signed x402 payment, and the request body is identical either way.

Two ways to pay, one purchase call

A prepaid balance is simpler when you buy often. Accountless x402 is better for a one-off autonomous purchase — save the receipt_token from the first paid response so you can read back what you bought.

1. Discover for free

No account is required. Fetch live availability and exact prices before purchase.

curl 'https://api.voxisim.com/v1/sms/rental/services'
curl 'https://api.voxisim.com/v1/sms/rental/countries?service_id=SERVICE_ID'
curl 'https://api.voxisim.com/v1/sms/rental/intervals?service_id=SERVICE_ID&country_id=COUNTRY_ID'

2A. Use prepaid balance

Create an account once, top it up over x402, then use the returned vxs_ key for purchases.

curl -X POST https://api.voxisim.com/v1/signup \
  -H 'content-type: application/json' \
  -d '{"label":"docs-quickstart"}'

curl -X POST https://api.voxisim.com/v1/sms/rental/numbers \
  -H 'authorization: Bearer YOUR_VXS_API_KEY' \
  -H 'content-type: application/json' \
  -d '{"service_id":"SERVICE_ID","country_id":COUNTRY_ID,"hours":HOURS}'

2B. Or pay accountlessly with x402

Send the purchase without credentials, sign one requirement from the 402 response, then retry the same request.

curl -i -X POST https://api.voxisim.com/v1/sms/rental/numbers \
  -H 'content-type: application/json' \
  -d '{"service_id":"SERVICE_ID","country_id":COUNTRY_ID,"hours":HOURS}'

curl -X POST https://api.voxisim.com/v1/sms/rental/numbers \
  -H 'content-type: application/json' \
  -H 'X-PAYMENT: BASE64_SIGNED_AUTHORIZATION' \
  -d '{"service_id":"SERVICE_ID","country_id":COUNTRY_ID,"hours":HOURS}'

3. Retrieve messages

Poll throughout the rental; use last_id to retrieve only newer messages.

curl 'https://api.voxisim.com/v1/sms/rental/numbers/YOUR_RENTAL_ID/codes' \
  -H 'authorization: Bearer YOUR_VXS_API_KEY'

Method	Route	What it does
GET	`/v1/sms/rental/services`	List rentable services
GET	`/v1/sms/rental/countries`	List countries for a service
GET	`/v1/sms/rental/intervals`	List intervals and exact prices
POST	`/v1/sms/rental/numbers`	Rent a number
GET	`/v1/sms/rental/numbers`	List active or archived rentals
GET	`/v1/sms/rental/numbers/{id}/codes`	Retrieve received SMS messages
POST	`/v1/sms/rental/numbers/{id}/cancel`	Cancel an active rental
GET	`/v1/sms/rental/numbers/{id}/extend-options`	List extension durations and prices
POST	`/v1/sms/rental/numbers/{id}/extend`	Extend an active rental

Operating notes

Refunds, expiry, and recovering cleanly

Expiry and provider hiccups are normal states, not exceptions. Branch on the typed error, re-run discovery before you retry, and never assume last run's price still holds.

Intervals come from discovery

Durations and prices are not a fixed menu — they come from live interval discovery. The hours value you send to purchase has to match one of the options actually on offer at that moment.

Read messages without duplicates

Poll with last_id so each call returns only what is new, and keep the rental id — you need it to cancel or extend later.

Cancel early, extend late

Cancel inside the eligible window if you no longer need the number, or extend an active rental by any interval still available for it.

When something goes wrong

invalid_argument — your service, country, or interval is stale. Re-run discovery and send a currently valid combination.
payment_required — expected on the x402 path. Sign one of the offered requirements and repeat the identical request.
number_unavailable or a conflict — that option just sold out. Discover again and pick another rather than replaying the same buy.
provider_unavailable or rate limiting — back off and honour the retry hint in the error. Retrying immediately makes it worse.

Not sure yet?

Activation and rental solve different problems

Pick the shortest lifetime that still covers your workflow. Stock and prices are live for both.

SMS Activation

Buy a one-time phone number and receive its verification code.

About 20 minutes
One verification code
Account verification and OTP flows

Read the SMS Activation guide

SMS Rental

You are here

Rent a phone number for a chosen duration and receive its SMS messages.

A day or more
Multiple SMS messages
Sessions, testing, and ongoing access

Where a rental fits

Multi-message sessionsLonger integration testsOngoing account accessAgent-monitored inboxes

FAQ

Rental questions

One day is the minimum, and longer intervals go up from there. Ask the intervals endpoint what is actually on offer for your service and country rather than assuming a fixed set — the options vary.
As many as arrive during the rental. That is the whole difference from an activation, which stops after one code.
Pass last_id when you poll. Each call then returns only messages newer than the one you already have, so you can poll aggressively without deduplicating on your side.
Yes, while it is still active, using any interval currently available for it. Extending is cheaper and less disruptive than renting a fresh number, since the number itself does not change.
Cancelling inside the eligible window refunds the rental. Outside that window the rental simply runs to the end of its term — so cancel as soon as you know you are finished.
Yes. The x402 path works exactly as it does for activations: send the purchase, sign the challenge that comes back, and repeat the identical request.

Reference

The generated contracts

This page explains the workflow. For every parameter, response field, and tool input, go to the reference — it is generated from the live contract, so it cannot drift.

Interactive APIExplore operations in Scalar REST MarkdownGenerated from OpenAPI MCP MarkdownGenerated from tool metadata OpenAPI JSONMachine-readable contract

Ready to buy your first number?

Connect an MCP client and ask, or copy the REST quickstart and run it.

Open API reference Compare both products

A number that stays yours

Get your API key in under a minute

Your account is ready

Four steps, start to finish

Discover live inventory

Rent for an interval

Collect messages

Cancel or extend

Put Voxisim inside your AI client

Add the endpoint

Sign in once

Just ask

Claude

Codex

Claude Code

Cursor

What your agent actually does

REST quickstart

1. Discover for free

2A. Use prepaid balance

2B. Or pay accountlessly with x402

3. Retrieve messages

Refunds, expiry, and recovering cleanly

Intervals come from discovery

Read messages without duplicates

Cancel early, extend late

When something goes wrong

Activation and rental solve different problems

SMS Activation

SMS Rental

Where a rental fits

Rental questions

How long can I keep a rental? ▼

How many messages does a rental receive? ▼

How do I avoid re-reading the same message? ▼

Can I extend a rental that is about to expire? ▼

What happens if I cancel? ▼

Can I buy a rental without an account? ▼

The generated contracts

Ready to buy your first number?