On this page

Quick start

Beta

Buy a number, read the code it receives, and let it go — three calls.

2 min read

You need a key with activations:write and activations:read. Everything below runs against https://api.ghostsms.io/v1.

1. Find out what a number costs

Prices move with supply, so ask before you buy. The answer includes a quote_token that holds the price for a few minutes.

curl "https://api.ghostsms.io/v1/prices/US/telegram" \
  -H "Authorization: Bearer $GHOSTSMS_KEY"

You can skip this — buying without a quote charges whatever the price is at that moment — but passing the token means the price you showed someone is the price they pay.

2. Buy the number

curl https://api.ghostsms.io/v1/activations \
  -X POST \
  -H "Authorization: Bearer $GHOSTSMS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "telegram",
    "country": "US",
    "client_reference": "order-8842"
  }'

{
  "object": "activation",
  "id": "8c1e4f2a-3b6d-4e9f-a0c7-2d5b9e1f7a34",
  "status": "waiting_for_code",
  "service": { "id": "telegram", "name": "Telegram" },
  "country": "US",
  "phone_number": "+13155550142",
  "price": { "amount": 62, "currency": "USD" },
  "client_reference": "order-8842",
  "created_at": "2026-09-18T10:20:00Z",
  "expires_at": "2026-09-18T10:35:00Z",
  "no_code_available_at": "2026-09-18T10:22:00Z",
  "messages_count": 0,
  "messages": []
}

The Idempotency-Key is required, and it is what makes a retry safe: the same key returns this same activation instead of buying a second number.

client_reference is yours — it comes back on every read, and it is what lets two of your jobs buy the same service and country at the same time without blocking each other.

3. Read the code

Give the number to the service you are verifying, then fetch the activation until a message appears.

curl https://api.ghostsms.io/v1/activations/8c1e4f2a-3b6d-4e9f-a0c7-2d5b9e1f7a34 \
  -H "Authorization: Bearer $GHOSTSMS_KEY"

  "status": "code_received",
  "messages": [
    {
      "object": "message",
      "id": "b7d2c9e0-4f1a-4a6b-8e3d-1c5f9a2e7b60",
      "received_at": "2026-09-18T10:21:04Z",
      "from": "Telegram",
      "text": "Telegram code: 482913",
      "code": "482913"
    }
  ]

Polling once every few seconds is fine — reads have their own budget, separate from purchases — but you do not have to: register an endpoint and we post the message to you the moment it lands, signed.

When nothing arrives

After no_code_available_at you can report it, and either get a replacement number for free or your money back:

curl https://api.ghostsms.io/v1/activations/8c1e4f2a-3b6d-4e9f-a0c7-2d5b9e1f7a34/no-code \
  -X POST \
  -H "Authorization: Bearer $GHOSTSMS_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Two replacements per activation, then the next report refunds it automatically. You are never charged for a number that never worked.

Next