Finish an order

Complete an active order after receiving and using your SMS.

01 / Request

Make a request

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

Finish only after the sms array contains a message. This action ends the order; keep the message you need before finishing.

An updating or terminal order may return 409. Retrieve the order and inspect its status before deciding what to do next.

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}/finish

# 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/finish" \
  -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}/finish`, {
  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}/finish",
    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": "FINISHED",
    "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