How long does an activation last?

About 20 minutes from purchase. That window is for receiving the code, not for keeping the number — once it expires the number is gone and cannot be renewed.

What if the code never arrives?

You are refunded automatically at expiry. There is no support ticket and no claim to file: prepaid balance is credited back, and an x402 authorization that never settled is simply released.

Can one activation receive two codes?

No. An activation is scoped to a single verification. If you need to verify again, buy another one — that is also why it is the cheapest option per code.

How fast do codes usually land?

Usually within seconds of the service sending it, but that depends entirely on the service, not on us. Poll every few seconds rather than waiting on a single long request.

Should I hardcode a country because it was cheapest last week?

No. Call the countries endpoint right before you buy — it returns current stock and the exact price, and both move with real supply.

Can I buy without an account?

Yes. Send the purchase with no credentials, sign the x402 challenge that comes back, and repeat the request. Discovery never needed credentials in the first place.

One-time activation · REST + MCP

One number, one code

Buy a private number, catch the verification code, move on. The activation lives about 20 minutes — and if no SMS ever lands, you keep your money: prepaid balance is credited back and an unsettled x402 hold is released.

Connect your AI client Jump to REST quickstart

Lifetime: About 20 minutes
What you get: One verification code
Best for: Account verification and OTP flows

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, then countries. Availability and exact USD prices are returned live.

GET /v1/sms/activation/servicesGET /v1/sms/activation/countries sms_activation_list_servicessms_activation_list_countries
2

Buy one number

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

POST /v1/sms/activation/numbers sms_activation_buy_number
3

Poll for the code

Read status every few seconds until a code arrives or the activation is done.

GET /v1/sms/activation/numbers/{id} sms_activation_get_code
4

Complete or refund

Use the code immediately. If no SMS arrives before expiry, the activation is refunded automatically.

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.

5 tools for this product

sms_activation_list_services
sms_activation_list_countries
sms_activation_buy_number
sms_activation_get_code
sms_activation_list_numbers

Try asking your agent

Find the cheapest live country for WhatsApp, buy one activation, and wait for the verification code.

Show me the available countries and exact current prices for a Telegram activation before buying anything.

Check my active SMS activations and report any code that has arrived.

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/activation/services'
curl 'https://api.voxisim.com/v1/sms/activation/countries?service_id=SERVICE_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/activation/numbers \
  -H 'authorization: Bearer YOUR_VXS_API_KEY' \
  -H 'content-type: application/json' \
  -d '{"service_id":"SERVICE_ID","country_id":COUNTRY_ID}'

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/activation/numbers \
  -H 'content-type: application/json' \
  -d '{"service_id":"SERVICE_ID","country_id":COUNTRY_ID}'

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

3. Poll for the code

Poll every few seconds until codes is non-empty or done is true.

curl 'https://api.voxisim.com/v1/sms/activation/numbers/YOUR_ACTIVATION_ID' \
  -H 'authorization: Bearer YOUR_VXS_API_KEY'

Method	Route	What it does
GET	`/v1/sms/activation/services`	List services and cheapest live options
GET	`/v1/sms/activation/countries`	List countries, stock, and exact prices
POST	`/v1/sms/activation/numbers`	Purchase a one-time number
GET	`/v1/sms/activation/numbers/{id}`	Read status and received codes
GET	`/v1/sms/activation/numbers`	List active or archived activations

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.

No SMS, no charge

If nothing arrives before the roughly 20-minute expiry, the refund is automatic. Prepaid balance is credited back and an x402 authorization is released without ever settling — you do not have to ask.

One code, then it is spent

Poll until codes is non-empty or done is true, then use the code promptly. An activation does not catch a second message; start a new one if you need another attempt.

Keep secrets out of prompts

vxs_ keys and x402 receipt_token values belong in a secret manager — not in prompts, source control, or logs.

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

You are here

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

About 20 minutes
One verification code
Account verification and OTP flows

SMS Rental

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

Read the SMS Rental guide

Where one-time activation fits

One-time passwordsAccount verificationSignup and QA automationShort agent-run tasks

FAQ

Activation questions

About 20 minutes from purchase. That window is for receiving the code, not for keeping the number — once it expires the number is gone and cannot be renewed.
You are refunded automatically at expiry. There is no support ticket and no claim to file: prepaid balance is credited back, and an x402 authorization that never settled is simply released.
No. An activation is scoped to a single verification. If you need to verify again, buy another one — that is also why it is the cheapest option per code.
Usually within seconds of the service sending it, but that depends entirely on the service, not on us. Poll every few seconds rather than waiting on a single long request.
No. Call the countries endpoint right before you buy — it returns current stock and the exact price, and both move with real supply.
Yes. Send the purchase with no credentials, sign the x402 challenge that comes back, and repeat the request. Discovery never needed credentials in the first place.

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

One number, one code

Get your API key in under a minute

Your account is ready

Four steps, start to finish

Discover live inventory

Buy one number

Poll for the code

Complete or refund

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. Poll for the code

Refunds, expiry, and recovering cleanly

No SMS, no charge

One code, then it is spent

Keep secrets out of prompts

When something goes wrong

Activation and rental solve different problems

SMS Activation

SMS Rental

Where one-time activation fits

Activation questions

How long does an activation last? ▼

What if the code never arrives? ▼

Can one activation receive two codes? ▼

How fast do codes usually land? ▼

Should I hardcode a country because it was cheapest last week? ▼

Can I buy without an account? ▼

The generated contracts

Ready to buy your first number?