Get an order

Retrieve an allocated number, its current status and all received messages.

01 / Request

Make a request

GET/api/v1/orders/{id}

Poll every 10 seconds while the order is active. Background checks continue even if your application disconnects.

GET reads the saved order. Use Refresh an order if you need to request a provider check; provider checks are throttled.

Read the sms array to detect delivery. Stop polling terminal states, and send purchase_unknown orders for review rather than creating replacements.

Required headers

AuthorizationstringRequired: Bearer followed by your ScrapingBuddy customer API key. Keep it on your server.

Authentication guide

Path parameters

idUUIDRequired: Your saved order ID. Replace {id} in the URL. You can only access orders belonging to your account.

GET /orders/{id}

# Set SCRAPINGBUDDY_API_KEY in your server environment.
# Set SCRAPINGBUDDY_ORDER_ID to your saved order ID.
curl "https://www.scrapingbuddy.com/api/v1/orders/$SCRAPINGBUDDY_ORDER_ID" \
  -H "Authorization: Bearer $SCRAPINGBUDDY_API_KEY"

Node.js 20+

// Node.js 20+. Keep credentials on your server.
const base = "https://www.scrapingbuddy.com/api/v1";
const orderId = encodeURIComponent(process.env.SCRAPINGBUDDY_ORDER_ID);
const response = await fetch(base + `/orders/${orderId}`, {
  method: "GET",
  headers: {
    Authorization: "Bearer " + process.env.SCRAPINGBUDDY_API_KEY,
  },
  signal: AbortSignal.timeout(30000),
});
const data = await response.json();
if (!response.ok) throw new Error(response.status + ": " + data.error);
console.log(data);
// Inspect data.order.status and data.order.sms before taking the next action.

Python 3 + requests

# Python 3. Install: pip install requests
import os
import requests
from urllib.parse import quote

base = "https://www.scrapingbuddy.com/api/v1"
headers = {"Authorization": "Bearer " + os.environ["SCRAPINGBUDDY_API_KEY"]}
order_id = quote(os.environ["SCRAPINGBUDDY_ORDER_ID"], safe="")
response = requests.get(
    base + f"/orders/{order_id}",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
data = response.json()
print(data)
# Inspect data["order"]["status"] and data["order"]["sms"] next.

Base URL https://www.scrapingbuddy.com/api/v1

Set the environment variables shown in the example. Python requires requests; JavaScript requires Node.js 20+. These examples call the live API, not a sandbox.

02 / Response

Understand the response

Success returns HTTP 200 with JSON. Always inspect order.status before using the number or taking another action.

order.idUUID: Save this identifier to retrieve, refresh, cancel or finish the order.
order.country / productstring: Country and service IDs used for this purchase.
order.operatorstring | null: Assigned operator; may be null while purchasing.
order.amount_centsinteger: Customer price in USD cents. 25 means $0.25. This field uses snake_case.
order.statusstring: Current lifecycle state. Read sms to detect a message; RECEIVED alone is not proof that a code arrived.
order.phonestring | null: Allocated phone number, including its country prefix. May be null while purchasing.
order.smsarray: Received messages. An empty array means no message has been recorded yet.
order.sms[].sender / text / code / datestring: Sender, complete message, extracted verification code and provider message date. A message may also contain an id.
order.expires_atdate-time | null: Order expiry reported by the provider. May be null while purchasing.
order.created_at / updated_atdate-time: When the order was created and last updated.
order.refunded_atdate-time | null: A timestamp confirms a recorded refund. Do not infer a refund from a local timer or status alone.
order.error_codestring | null: Failure or review details, when present. Include this and the order ID in a support ticket, never your API key.

Example response / illustrative values

{
  "order": {
    "id": "22222222-2222-4222-8222-222222222222",
    "country": "england",
    "product": "google",
    "operator": "assigned-operator",
    "amount_cents": 25,
    "status": "RECEIVED",
    "phone": "+440000000000",
    "sms": [
      {
        "sender": "Example",
        "text": "Your verification code is 123456",
        "code": "123456",
        "date": "2026-09-12T12:01:00.000Z"
      }
    ],
    "expires_at": "2026-09-12T12:15:00.000Z",
    "created_at": "2026-09-12T12:00:00.000Z",
    "updated_at": "2026-09-12T12:01:00.000Z",
    "refunded_at": null,
    "error_code": null
  }
}

Prices, stock, phone numbers, messages and timestamps here are illustrative, not live availability or a price guarantee.

Errors & next steps

Failures return an HTTP error status and a JSON error message. Correct validation and authentication errors before retrying. For 429, honor Retry-After; longer account limits may still apply.

All keys share the account limit of 60 API requests per minute. Purchase recovery must keep the original idempotency key and quote ID.

Errors & limits Safe purchases & retries Order lifecycle