API Documentation

Running a website or service and want to offer SMS verification numbers to your own users? Copy this prompt into Claude Code, Codex, or any AI coding agent, add your API key, and it will wire up number rental + SMS code retrieval into your existing project — without touching your design or any unrelated code.

I want you to integrate the SMSKody SMS-verification-number API into this project so my users can rent a temporary phone number and receive an SMS verification code.

Context:
- SMSKody rents temporary phone numbers and delivers SMS verification codes via a REST API compatible with the SMS-Activate protocol.
- Base URL: https://smskody.com/api/ext
- Auth: send header "Authorization: Bearer <API_KEY>" on every request. Store the key as an environment variable (e.g. SMSKODY_API_KEY) — never hardcode it.
- Full reference docs: https://smskody.com/api-docs

Endpoints you'll need:
- GET ?action=getBalance -> "ACCESS_BALANCE:10.50"
- GET ?action=getServicesList -> JSON array of {code, name}
- GET ?action=getPrices -> JSON {country: {service: {cost, count}}}
- GET ?action=getNumber&service=<code> -> "ACCESS_NUMBER:<activationId>:<phoneNumber>" (errors: NO_BALANCE, NO_NUMBERS, BAD_SERVICE)
- GET ?action=getStatus&id=<activationId> -> "STATUS_WAIT_CODE" (keep polling every 3-5s) | "STATUS_OK:<code>" (SMS received) | "STATUS_CANCEL" | "NO_ACTIVATION"
- GET ?action=setStatus&id=<activationId>&status=8 -> cancel & refund | status=6 -> mark complete
- Add &format=json to any request to get JSON instead of the text protocol above, e.g. getNumber -> {"status":"ACCESS_NUMBER","id":"8041315","phone":"12145550198"}
- Rate limit: max 60 requests/minute per key (response "RATE_LIMIT" if exceeded)

What I need you to do:
1. Add a small, self-contained integration (a service/module/client that fits this codebase's existing conventions and language) wrapping these calls: rent a number, poll for the SMS code, and cancel/complete an activation.
2. Wire it into [DESCRIBE WHERE IN YOUR APP THIS SHOULD LIVE, e.g. "the signup flow", "a new /verify-number page", "the existing phone-verification step"] so it's actually usable.
3. Handle the documented response codes and edge cases (insufficient balance, no numbers available, expired/cancelled activation, rate limiting).
4. Do NOT touch any unrelated code, existing UI/design, styling, layout, or refactor anything outside what's needed for this integration. Keep the change minimal and additive — new files/functions only wherever possible.
5. Do NOT invent any payment/billing logic for the numbers themselves — assume the SMSKody balance is already funded; just call the API.
6. Briefly explain your integration approach before writing code, and ask me before doing anything outside the scope of this feature (like a DB migration) if one seems necessary.

My SMSKody API key: <PASTE YOUR API KEY HERE>

Two methods are supported. Header-based auth is recommended as it keeps your key out of server logs and browser history.

Polling getStatus every 3 seconds uses ~20 req/min — well within the limit. If you get RATE_LIMIT, wait and retry.

# 1. Check balance
GET /api/ext?action=getBalance
→ ACCESS_BALANCE:10.50

# 2. Get available services and prices
GET /api/ext?action=getPrices
→ {"0": {"wa": {"cost": 0.05, "count": 219475}, ...}}

# 3. Rent a number for WhatsApp
GET /api/ext?action=getNumber&service=wa
→ ACCESS_NUMBER:8041315:12145550198

# 4. Use +12145550198 on WhatsApp to request SMS code

# 5. Poll for the SMS (every 3-5 seconds)
GET /api/ext?action=getStatus&id=8041315
→ STATUS_WAIT_CODE          (keep polling)
→ STATUS_OK:482731          (SMS received!)

# 6. Done! Optionally mark as complete
GET /api/ext?action=setStatus&id=8041315&status=6
→ ACCESS_ACTIVATION

# If SMS never arrives, cancel for refund:
GET /api/ext?action=setStatus&id=8041315&status=8
→ ACCESS_CANCEL

Returns the current account balance in USD.

Returns a JSON array of all available services with code and name.

Returns prices and available number counts for all services, grouped by country.

Returns available countries. Currently only USA.

Rent a phone number for a specific service. Balance is deducted at the service price (check getPrices). Number is typically active for around 5 minutes.

Check the status of an activation. Poll this every 3-5 seconds to wait for the SMS code.

Change the status of an activation. Use status=8 to cancel (get refund), or status=6 to mark complete.

Instead of polling, you can set a webhook URL in Settings. When an SMS arrives, we'll POST a JSON payload to your URL:

POST https://your-server.com/webhook
Content-Type: application/json

{
  "activationId": 8041315,
  "phone": "12145550198",
  "service": "wa",
  "smsCode": "482731",
  "smsText": "Your WhatsApp code is 482731",
  "status": "completed"
}

import requests, time

API_KEY = "sk_your_key_here"
BASE = "https://smskody.com/api/ext"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

r = requests.get(BASE, params={"action": "getNumber", "service": "wa"}, headers=HEADERS)
parts = r.text.split(":")
activation_id, phone = parts[1], parts[2]
print(f"Use this number: +{phone}")

while True:
    r = requests.get(BASE, params={"action": "getStatus", "id": activation_id}, headers=HEADERS)
    if r.text.startswith("STATUS_OK:"):
        print(f"SMS code: {r.text.split(':')[1]}")
        break
    time.sleep(3)

const API_KEY = "sk_your_key_here";
const BASE = "https://smskody.com/api/ext";

async function api(params) {
  const url = BASE + "?" + new URLSearchParams(params);
  const res = await fetch(url, { headers: { Authorization: "Bearer " + API_KEY } });
  return res.text();
}

const result = await api({ action: "getNumber", service: "wa" });
const [, activationId, phone] = result.split(":");
console.log("Use number: +" + phone);

while (true) {
  const status = await api({ action: "getStatus", id: activationId });
  if (status.startsWith("STATUS_OK:")) {
    console.log("Code:", status.split(":")[1]);
    break;
  }
  await new Promise(r => setTimeout(r, 3000));
}

curl -H "Authorization: Bearer sk_your_key" \
  "https://smskody.com/api/ext?action=getBalance"

curl -H "Authorization: Bearer sk_your_key" \
  "https://smskody.com/api/ext?action=getNumber&service=wa"

curl -H "Authorization: Bearer sk_your_key" \
  "https://smskody.com/api/ext?action=getStatus&id=8041315"

curl -H "Authorization: Bearer sk_your_key" \
  "https://smskody.com/api/ext?action=setStatus&id=8041315&status=8"

Test all endpoints in your browser with our interactive tool.