API v2

Overview

Two products, one API. One-time numbers receive a single verification code and last 10 minutes; you are charged only if a message arrives. Rentals hold a real mobile number for a month or longer and are charged when you buy them.

Every response is JSON. Successes are an object carrying an object field naming its type; failures are application/problem+json with a stable code to branch on. Amounts are always EUR, timestamps always UTC.

There is an older plain-text API — ?key= in the query string, magic strings in the body, HTTP 200 on failure. It is still live and still supported, and nothing about it is changing; it is just not where a new integration should start. If you are already on it, its reference is at the legacy API page. Your existing key works here unchanged, as a bearer token.

Authentication

Every authenticated request carries your key in the Authorization header. Keys are never accepted in the query string: a URL ends up in web server logs, proxy logs, Referer headers and the shell history of whoever you paste an example to.

curl https://juicysms.com/api/v2/account \
  -H "Authorization: Bearer $JUICYSMS_KEY"

Two kinds of key work

The cheapest way to check a key is GET /api/v2/account: it is the only endpoint that reports back which scopes the key you presented actually holds, so you can verify permissions without provoking a 403 from the endpoint you really wanted.

Errors

Every failure is a application/problem+json document (RFC 9457) with the right HTTP status. There are no 200-with-a-string errors anywhere in v2, so your HTTP client, your retry middleware and your monitoring all see a failure as a failure.

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

{
  "type": "https://juicysms.com/api/errors#insufficient_balance",
  "title": "Insufficient balance",
  "status": 402,
  "code": "insufficient_balance",
  "detail": "Your balance does not cover this order.",
  "retryable": false,
  "price":   { "amount": "0.50", "amount_minor": 50, "currency": "EUR" },
  "balance": { "amount": "0.12", "amount_minor": 12, "currency": "EUR" }
}

• code is the field to branch on. These strings are part of the contract: we add to them, we never rename or repurpose one.
• retryable tells you whether repeating the identical request could ever succeed, so you do not have to keep your own table of which of our failures are transient.
• Anything after retryable is extra context for that specific failure — price and balance here, order_id on a concurrency conflict, errors on a validation failure.
• The HTTP status for a given code is fixed. One condition cannot be a 409 on one endpoint and a 422 on another.
• status always means the HTTP status and nothing else. Where an order's own state is relevant — refusing to cancel an order that already finished, for instance — it is reported separately as order_status, so the two can never be confused.

The codes

This is the complete list. Nothing else can come back.

Quickstart: order a number, read the code

1. Look up the service id and what it costs you: GET /services?country=UK.
2. Buy a number: POST /orders.
3. Poll GET /orders/{id}/messages until data is non-empty, or register a webhook and skip the polling.

export JUICYSMS_KEY="your_api_key"

# 1. What can I buy, and what does it cost me?
curl -s "https://juicysms.com/api/v2/services?country=UK&search=whatsapp" \
  -H "Authorization: Bearer $JUICYSMS_KEY"

# 2. Buy a number.
curl -s -X POST https://juicysms.com/api/v2/orders \
  -H "Authorization: Bearer $JUICYSMS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_id": 1, "country": "UK", "max_price": "0.60"}'

# 3. Poll until data is non-empty. Empty + "pending" means keep waiting.
curl -s https://juicysms.com/api/v2/orders/8123456/messages \
  -H "Authorization: Bearer $JUICYSMS_KEY"

# Nothing arriving? Release the number and get a different one.
curl -s -X POST https://juicysms.com/api/v2/orders/8123456/skip \
  -H "Authorization: Bearer $JUICYSMS_KEY"

What comes back

POST /orders answers 201 with a Location header and the order itself:

{
  "object": "order",
  "id": 8123456,
  "status": "pending",
  "service": { "id": 1, "name": "WhatsApp" },
  "country": "UK",
  "country_iso": "GB",
  "phone_number": "+447407792510",
  "phone_number_local": "7407792510",
  "price": { "amount": "0.50", "amount_minor": 50, "currency": "EUR" },
  "charged": false,
  "reused_from_order_id": null,
  "created_at": "2026-08-09T12:00:00Z",
  "expires_at": "2026-08-09T12:10:00Z",
  "code": null,
  "messages": []
}

And once the message lands:

{
  "data": [
    {
      "object": "message",
      "id": 44120931,
      "sender": "WhatsApp",
      "text": "Your WhatsApp code is 417-097. Don't share it.",
      "code": "417097",
      "received_at": "2026-08-09T12:01:44Z",
      "source": "sms"
    }
  ],
  "order_id": 8123456,
  "order_status": "completed"
}

• code is the extracted verification code, so you do not have to write a regex against the message body. It is deliberately conservative — one unambiguous run of 4–8 digits, a hyphen in the middle tolerated. When a message has no clear single candidate it is null and text is always there to fall back on.
• An empty data array with order_status: "pending" means keep waiting. Any other status means the order is over and no message is coming.
• phone_number is E.164 and phone_number_local is the national form, because some signup forms reject one or the other.
• Orders stay open for 10 minutes. After that the order expires on its own, and you are not charged.

One order at a time, unless you ask

By default an account may hold one open order at a time. Ordering again while one is still running returns 409 concurrent_order_limit, with the id of the order already open in the problem document — so you can pick that one back up rather than starting over.

That limit can be lifted. Parallel ordering is a per-account setting: contact support and we can enable it, after which you can hold as many open orders at once as you need. It suits anyone verifying in bulk rather than one signup at a time. Read parallel_orders_allowed from GET /account to see which mode your account is in, rather than discovering it from a 409 in production.

Rate limits

Limits are per key, per minute, in separate buckets. Reads are generous because polling for a code is cheap; ordering is tighter because every call can allocate a real number.

Every response tells you where you stand, in both the widely-used X-RateLimit-* form and the IETF RateLimit-* form. Note the difference in the reset field: X-RateLimit-Reset is an absolute Unix timestamp, RateLimit-Reset is seconds from now.

X-RateLimit-Limit: 240
X-RateLimit-Remaining: 237
X-RateLimit-Reset: 1786636800
RateLimit-Limit: 240
RateLimit-Remaining: 237
RateLimit-Reset: 41
RateLimit-Policy: 240;w=60

Going over is rate_limited (429) with a Retry-After header. Wait that long; do not retry immediately.

Other headers on every response

Cursor pagination

GET /orders and GET /rentals are cursor-paginated: pass limit (default 25, maximum 100) and cursor. There is no page number and no total count, on purpose — a cursor stays correct while new rows arrive underneath you, and costs the same on page 400 as on page 1.

GET /api/v2/orders?limit=25&status=completed

{
  "data": [ "...25 orders, newest first..." ],
  "pagination": {
    "limit": 25,
    "has_more": true,
    "next_cursor": "eyJpZCI6ODEyMzQ1NiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ",
    "previous_cursor": null
  }
}

Keep passing next_cursor back as cursor until has_more is false. Treat the cursor as opaque — do not parse it or build one yourself.

Small, bounded lists — services, rental packages, webhook endpoints and the messages on one order — come back without a pagination block. They are still JSON objects with a data array rather than bare arrays, so we can add fields to them later without breaking your client.

Webhooks

Register an HTTPS URL and we push events to it, so you can stop polling. Create one with POST /webhook-endpoints, naming the events you want. You can have up to 5 endpoints.

curl -s -X POST https://juicysms.com/api/v2/webhook-endpoints \
  -H "Authorization: Bearer $JUICYSMS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://example.com/hooks/juicysms",
        "events": ["sms.received", "rental.sms.received"],
        "description": "production worker"
      }'

URLs must be https, on port 80 or 443, with no credentials in the URL, and must not resolve to a private, loopback, link-local or otherwise reserved address. We do not follow redirects.

Events

POST /webhook-endpoints/{id}/test queues a ping delivery and answers 202 with its delivery id, so you can prove your receiver works before any real traffic depends on it. ping is not subscribable — it is only ever produced by that call. Testing a disabled endpoint is a 422, because nothing would go out.

What we send

POST /hooks/juicysms
JuicySMS-Signature: t=1786636800,v1=6f3a...c19b
JuicySMS-Event: sms.received
JuicySMS-Delivery-Id: 90210
User-Agent: JuicySMS-Webhook/2.0
Content-Type: application/json

{
  "id": "whd_90210",
  "object": "event",
  "type": "sms.received",
  "api_version": "2026-08-09",
  "created_at": "2026-08-09T12:01:44Z",
  "attempt": 1,
  "data": {
    "order": {
      "object": "order",
      "id": 8123456,
      "status": "completed",
      "service": { "id": 1, "name": "WhatsApp" },
      "country": "UK",
      "country_iso": "GB",
      "phone_number": "+447407792510",
      "phone_number_local": "7407792510"
    },
    "message": {
      "object": "message",
      "id": null,
      "sender": "WhatsApp",
      "text": "Your WhatsApp code is 417-097. Don't share it.",
      "code": "417097",
      "received_at": "2026-08-09T12:01:44Z",
      "source": "provider"
    }
  }
}

Answer 2xx quickly. Anything else counts as a failure and is retried up to 6 times with a backoff of 10s, 1m, 5m, 30m, then 2h. Our request times out after 10 seconds, so acknowledge first and do your work afterwards. An endpoint that keeps failing is disabled automatically; re-enable it with a PATCH. Recent attempts, with the status and body we got back, are listed at GET /webhook-endpoints/{id}/deliveries.

JuicySMS-Delivery-Id stays the same across every retry of the same event, so it is the key to de-duplicate on if your handler is not already idempotent. What does change per attempt is the attempt counter in the body — which means each attempt is a distinct message with its own signature, and you cannot cache one signature and compare it to the next.

Verifying the signature

v1 is the hex HMAC-SHA256 of timestamp + "." + raw request body, keyed with your endpoint secret. The timestamp is inside the signed string, which is what stops someone replaying a captured delivery forever: reject anything whose t is more than 300 seconds away from your clock, and compare the digests in constant time.

Sign the raw bytes of the request. If you parse the JSON and re-serialize it, whitespace and key order change and the signature will not match.

import hmac, hashlib, time

def verify(raw_body: bytes, signature_header: str, secret: str, tolerance: int = 300) -> bool:
    """raw_body must be the exact bytes we sent, not a re-serialized dict."""
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    timestamp, received = parts.get("t"), parts.get("v1")

    if not timestamp or not received:
        return False

    # Reject anything too old to be a live delivery: this is what makes
    # replaying a captured request useless.
    if abs(time.time() - int(timestamp)) > tolerance:
        return False

    expected = hmac.new(
        secret.encode(),
        timestamp.encode() + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, received)

Scopes

A v2 key created under Account › API keys holds only the scopes you tick. A key that only reads orders cannot spend your balance, which is what you want for anything that runs on a machine you do not fully control.

Calling an endpoint your key is not scoped for is insufficient_scope (403), and the problem document names both what was required and what your key holds. The account key is unscoped and passes every check.

Endpoint reference

Base URL https://juicysms.com/api/v2. Anything not listed here answers not_found as a problem document, never an HTML page.

Everything below — the endpoints, their scopes and their parameters — is generated from the OpenAPI document, so it cannot drift from the API. Import that URL into Postman, Insomnia or a client generator and you get the same contract, typed.

Countries

The list changes very rarely, so it lives here rather than behind an endpoint.

There is no stock figure anywhere in the API, for one-time numbers or for rentals. Stock moves second to second and any number published here would be wrong by the time you read it. Place the order and handle out_of_stock, which is marked retryable because it usually clears on its own.

Country codes are ours, not ISO — UK rather than GB, USA rather than US — but requests also accept the ISO form and the full English name, in any casing, and every response carries both country and country_iso. A country we do not sell is a 422; we never quietly substitute a different one.

Money

Every amount — prices, balances, rental packages — is the same object, and always in EUR, which is the currency your balance is actually held and charged in. Nothing is converted.

{
  "amount": "0.50",
  "amount_minor": 50,
  "currency": "EUR"
}

Use amount_minor (an integer number of cents) for arithmetic and amount for display. There is no float anywhere in the payload. Timestamps are ISO 8601 in UTC (2026-08-09T12:10:00Z), and booleans are real JSON booleans.