Refresh an order

Request a status check for an existing order.

01 / Request

Make a request

POST/api/v1/orders/{id}/refresh

Checks are throttled and also run automatically in the background. Repeated refresh requests do not guarantee a fresh provider request.

Read the returned order. This action does not purchase a new number or extend the order expiry.

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.

No request body is required.

POST /orders/{id}/refresh

# Set SCRAPINGBUDDY_API_KEY in your server environment.
# Set SCRAPINGBUDDY_ORDER_ID to your saved order ID.
curl -X POST "https://www.scrapingbuddy.com/api/v1/orders/$SCRAPINGBUDDY_ORDER_ID/refresh" \
  -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}/refresh`, {
  method: "POST",
  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.post(
    base + f"/orders/{order_id}/refresh",
    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