Overview

Base URLhttps://www.codeysms.com/api/v1

Every path below is relative to the base URL. Every response is JSON. Amounts are always in EUR, timestamps always in UTC (ISO 8601).

The API offers the same two products as the website. A one-time number receives one SMS for one website and stays open for 20 minutes; if no SMS arrives, or you cancel, the price goes back to your balance. A rental number is yours for 1, 3, 6 or 12 months and receives every SMS sent to it.

Your API keys

Authentication

Send your key in the Authorization header of every request. Keys are never accepted in the URL, because URLs end up in logs and browser history.

curl https://www.codeysms.com/api/v1/account \
  -H "Authorization: Bearer $CODEYSMS_KEY"

GET /account is the cheapest way to check that a key works. A missing key answers 401 unauthenticated, a wrong or revoked key 401 invalid_token.

Quickstart: order a number and read the code

1. Order a number: POST /orders.
2. Enter the number on the website and let it send the SMS.
3. Poll GET /orders/{id}/messages every few seconds until data is not empty.

export CODEYSMS_KEY="csk_your_key"

# 1. Order a number for a website
curl -s -X POST https://www.codeysms.com/api/v1/orders \
  -H "Authorization: Bearer $CODEYSMS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"website": "myshop.com", "country": "NL", "max_price": "0.50"}'

# 2. Poll every few seconds until data is not empty
curl -s https://www.codeysms.com/api/v1/orders/123/messages \
  -H "Authorization: Bearer $CODEYSMS_KEY"

# No SMS after all? Cancel and get your money back
curl -s -X POST https://www.codeysms.com/api/v1/orders/123/cancel \
  -H "Authorization: Bearer $CODEYSMS_KEY"

const KEY = process.env.CODEYSMS_KEY;
const api = (path, body) =>
  fetch("https://www.codeysms.com/api/v1" + path, {
    method: body ? "POST" : "GET",
    headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  }).then(async (r) => {
    const json = await r.json();
    if (!r.ok) throw new Error(json.code + ": " + json.detail);
    return json;
  });

const order = await api("/orders", { website: "myshop.com", country: "NL" });
console.log("Use this number:", order.phone_number);

let code = null;
while (!code) {
  await new Promise((r) => setTimeout(r, 3000));
  const { data, order_status } = await api(`/orders/${order.id}/messages`);
  if (data.length) code = data[0].code;
  else if (order_status !== "pending") throw new Error("Order " + order_status);
}
console.log("Code:", code);

import os, time, requests

KEY = os.environ["CODEYSMS_KEY"]
H = {"Authorization": f"Bearer {KEY}"}
BASE = "https://www.codeysms.com/api/v1"

order = requests.post(f"{BASE}/orders", headers=H,
                      json={"website": "myshop.com", "country": "NL"}).json()
print("Use this number:", order["phone_number"])

while True:
    time.sleep(3)
    r = requests.get(f"{BASE}/orders/{order['id']}/messages", headers=H).json()
    if r["data"]:
        print("Code:", r["data"][0]["code"])
        break
    if r["order_status"] != "pending":
        raise SystemExit("Order " + r["order_status"])

What comes back

POST /orders answers 201 Created with the order:

HTTP/1.1 201 Created
Location: /api/v1/orders/123

{
  "object": "order",
  "id": 123,
  "status": "pending",
  "website": "myshop.com",
  "country": "NL",
  "phone_number": "+31612345678",
  "phone_number_local": "0612345678",
  "price": { "amount": "0.50", "amount_minor": 50, "currency": "EUR" },
  "reusable": false,
  "created_at": "2026-11-01T12:00:00Z",
  "expires_at": "2026-11-01T12:20:00Z",
  "closed_at": null,
  "code": null,
  "messages": []
}

Once the SMS arrives, GET /orders/{id}/messages returns it:

{
  "data": [
    {
      "object": "message",
      "sender": "MyShop",
      "text": "Your verification code is 591204.",
      "code": "591204",
      "received_at": "2026-11-01T12:01:12Z"
    }
  ],
  "order_id": 123,
  "order_status": "completed"
}

• code is the verification code we found in the message, so you don't need your own regex. If there is no clear code, it is null and text has the full message.
• An empty data with order_status: "pending" means: keep waiting. Any other status means the order is over.
• phone_number is in international format (E.164); phone_number_local is the national format, for forms that want that.
• An account can have one open order at a time. A second order while one is open answers 409 concurrent_order_limit.

Errors

Every error is an application/problem+json document (RFC 9457) with the matching HTTP status. Branch on code: these values never change meaning. retryable tells you whether the same request can succeed later.

HTTP/1.1 402 Payment Required
Content-Type: application/problem+json

{
  "type": "https://www.codeysms.com/api#error-insufficient_balance",
  "title": "Insufficient balance",
  "status": 402,
  "code": "insufficient_balance",
  "detail": "Your balance is too low. Please top up first.",
  "retryable": false
}

Rate limits

Limits count per account, per minute. Reading is generous, because polling for a code is cheap; ordering is stricter.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time). Over the limit you get 429 rate_limited with a Retry-After header in seconds.

Pagination

GET /orders uses a cursor: pass limit (default 25, maximum 100) and keep sending pagination.next_cursor back as cursor until has_more is false. Treat the cursor as an opaque string.

Endpoints

Objects

Order statuses

pending waiting for the SMS · completed SMS received · cancelled cancelled, money back · expired time ran out without an SMS, money back.

Money

Amounts are objects: {"amount": "0.50", "amount_minor": 50, "currency": "EUR"}. Use amount_minor (cents) for calculations.

Rental

id, status (active or ended), country, phone_number, phone_number_local, plan, months, price, auto_renew, started_at, ends_at, ended_at.