On this page Prepare your account

Your first number

Go from a server-side API key to an allocated number and your first verification message.

Prepare your account

Sign in, top up your wallet and create an API key in API access. Save the key when it is shown; it cannot be revealed again.

Set SCRAPINGBUDDY_API_KEY in your server environment. First call GET /balance to verify authentication without placing an order. All amounts are integer USD cents; 100 cents is $1.00.

Check your connection

curl "https://www.scrapingbuddy.com/api/v1/balance" \
  -H "Authorization: Bearer $SCRAPINGBUDDY_API_KEY"

Choose a country and service

Call List countries and use a returned country ID with List services. Use the service id as product, not its display name.

For a specific operator, call List operators with the same country and product. Otherwise omit operator when quoting, or pass any. Catalogue prices and stock are indicative.

GET /countries
GET /services?country=england
Optional: GET /operators?country=england&product=google

Check a live quote

POST /quotes with country, product and optional operator. Inspect amountCents and compare it against a budget that you control.

Save the quote id and check expiresAt. Quotes last two minutes and do not reserve stock. If the price is too high, stop; do not purchase.

Request a quote

curl -X POST "https://www.scrapingbuddy.com/api/v1/quotes" \
  -H "Authorization: Bearer $SCRAPINGBUDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"england","product":"google","operator":"any"}'

Purchase exactly once

Generate one UUID v4 for this purchase and persist it with the approved quote ID before making the request. Set them as SCRAPINGBUDDY_PURCHASE_KEY and SCRAPINGBUDDY_QUOTE_ID in the examples below.

This request spends wallet funds. If the connection fails or times out, reuse the same saved key and quote ID. Never generate another key just because you did not receive a response.

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.

Receive the SMS and finish

Retrieve GET /orders/{id} every 10 seconds while the order is active. Use the returned phone number for your intended verification flow. Read order.sms to detect a message.

After receiving and using the message, POST /orders/{id}/finish. To cancel an active order before an SMS arrives, use POST /orders/{id}/cancel. Check refunded_at to confirm a recorded refund.

If status is purchase_unknown, do not create a replacement purchase automatically. Keep the order ID and contact support.

Manage API keys Order API reference Contact support