Create an order

Purchase a number using an approved quote and a persisted idempotency key.

01 / Request

Make a request

POST/api/v1/orders

This request spends wallet funds. Persist a UUID v4 Idempotency-Key and quoteId before sending it. Reuse the same pair if the outcome is uncertain.

201 means a new order record was created; 200 can recover an existing request. Neither status alone proves that a number was allocated. Inspect order.status and order.phone.

Do not automatically place a replacement purchase when status is purchase_unknown. Retrieve the saved order and contact support if it remains unresolved.

Required headers

AuthorizationstringRequired: Bearer followed by your ScrapingBuddy customer API key. Keep it on your server.
Content-TypestringRequired: application/json.
Idempotency-KeyUUID v4Required: Generate once per purchase and persist with quoteId before sending. Reuse the same pair on an uncertain retry.

Authentication guide

JSON body

quoteIdUUIDRequired: Your saved, unexpired quote ID. Check its price against your budget before purchasing.

POST /orders

# Set SCRAPINGBUDDY_API_KEY in your server environment.
# Persist these values before purchase; reuse them on an uncertain retry.
# SCRAPINGBUDDY_QUOTE_ID: your approved quote ID.
# SCRAPINGBUDDY_PURCHASE_KEY: one saved UUID v4 for this purchase.

curl -X POST "https://www.scrapingbuddy.com/api/v1/orders" \
  -H "Authorization: Bearer $SCRAPINGBUDDY_API_KEY" \
  -H "Idempotency-Key: $SCRAPINGBUDDY_PURCHASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quoteId":"'"$SCRAPINGBUDDY_QUOTE_ID"'"}'

Node.js 20+

// Node.js 20+. Keep credentials on your server.
const base = "https://www.scrapingbuddy.com/api/v1";
// Persist both values before sending. Reuse them for an uncertain retry.
const quoteId = process.env.SCRAPINGBUDDY_QUOTE_ID;
const purchaseKey = process.env.SCRAPINGBUDDY_PURCHASE_KEY;
if (!quoteId || !purchaseKey) throw new Error("Set your saved quote and purchase key");
const response = await fetch(base + "/orders", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.SCRAPINGBUDDY_API_KEY,
    "Idempotency-Key": purchaseKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ quoteId }),
  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

base = "https://www.scrapingbuddy.com/api/v1"
headers = {"Authorization": "Bearer " + os.environ["SCRAPINGBUDDY_API_KEY"]}
# Persist these values before purchase; reuse them on an uncertain retry.
headers["Idempotency-Key"] = os.environ["SCRAPINGBUDDY_PURCHASE_KEY"]
response = requests.post(
    base + "/orders",
    headers=headers,
    json={"quoteId": os.environ["SCRAPINGBUDDY_QUOTE_ID"]},
    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 201 / 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": "PENDING",
    "phone": "+440000000000",
    "sms": [],
    "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