Skip to main content
ScrapingBuddy
Skip to content
ScrapingBuddyDevelopers
Dashboard
On this page Introduction

Developers/SMS API

Build your SMS integration

Find a number. Receive a verification message. Manage the entire order from your application.

Start with a live quote, approve its price and purchase once. Every request uses your ScrapingBuddy customer key and the same wallet as your dashboard.

Get your first number
  1. 01
    Quote

    Choose a service and check its live price.

  2. 02
    Purchase

    Use one saved key for each purchase.

  3. 03
    Receive

    Read your SMS, then finish the order.

Start building

New to the API? Follow the first-number guide, then explore the reference for each request in your integration.

Your first numberFrom your API key to an allocated number and message.AuthenticationConnect your backend and keep credentials private.Order lifecycle & messagesUnderstand statuses, messages and refunds.Safe purchases & retriesRecover uncertain requests without buying twice.

Understand the workflow

  1. Find your country and serviceUse IDs from the catalogue, not display names. Choose an operator only when you need a specific one.
  2. Approve a two-minute quoteCheck amountCents against your budget. Stock is not reserved by a quote.
  3. Keep one identity per purchasePersist the UUID v4 Idempotency-Key and quoteId before sending POST /orders. Reuse them on an uncertain retry.
  4. Wait for a messagePoll your saved order every 10 seconds. Inspect sms, then finish or cancel when the action is allowed.
Order lifecycleErrors & limits

API endpoints

Base URL: https://www.scrapingbuddy.com/api/v1. Every request needs Bearer authentication. All prices are integer USD cents.

SMS API endpoints
MethodEndpointPurpose
GET/balanceRead the wallet balance shared by your dashboard and API purchases.
GET/countriesFind the country identifiers used by catalogue and purchase requests.
GET/servicesFind service IDs, stock and indicative prices for a country.
GET/operatorsFind available operators for a country and service.
POST/quotesGet a live price before committing to a number purchase.
POST/ordersPurchase a number using an approved quote and a persisted idempotency key.
GET/ordersRead your order history, newest first, in pages of up to 20 orders.
GET/orders/{id}Retrieve an allocated number, its current status and all received messages.
POST/orders/{id}/refreshRequest a status check for an existing order.
POST/orders/{id}/cancelCancel an active order before an SMS has arrived.
POST/orders/{id}/finishComplete an active order after receiving and using your SMS.
Explore API referenceDownload OpenAPI
SMS API v1
Getting startedIntroductionYour first numberAuthentication
Integration guidesOrder lifecycle & messagesSafe purchases & retriesErrors & limits
API keys Download OpenAPI Contact support

Explore the documentation

SMS APIIntroduction

Virtual numbers, quotes, verification messages and order management.

GuidesYour first number

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

GuidesAuthentication

Create a customer key and connect your backend securely.

GuidesOrder lifecycle & messages

Know when a number is ready, when a message has arrived and when to stop polling.

GuidesSafe purchases & retries

Recover uncertain requests without accidentally buying another number.

GuidesErrors & limits

Understand response errors and the limits shared by your account.

GET /balanceGet balance

Read the wallet balance shared by your dashboard and API purchases. balanceUsd is the exact available USD balance as a decimal string, including fractional cents from CAPTCHA charg

GET /countriesList countries

Find the country identifiers used by catalogue and purchase requests. Use the id from this response in subsequent requests. Country names and dialling prefixes are display informat

GET /servicesList services

Find service IDs, stock and indicative prices for a country. Catalogue prices are indicative, not a purchase commitment. Always create a fresh quote before purchasing. Stock can ch

GET /operatorsList operators

Find available operators for a country and service. Pass an operator id to Create a quote when you need a specific operator. Omit operator or use any for automatic selection. Chang

POST /quotesCreate a quote

Get a live price before committing to a number purchase. A quote expires after two minutes. Check amountCents against your budget and expiresAt before purchasing. A quote does not

POST /ordersCreate an order

Purchase a number using an approved quote and a persisted idempotency key. This request spends wallet funds. Persist a UUID v4 Idempotency-Key and quoteId before sending it. Reuse

GET /ordersList orders

Read your order history, newest first, in pages of up to 20 orders. Start with offset=0 and increase by 20 while hasMore is true. Stop when hasMore is false. This is offset paginat

GET /orders/{id}Get an order

Retrieve an allocated number, its current status and all received messages. Poll every 10 seconds while the order is active. Background checks continue even if your application dis

POST /orders/{id}/refreshRefresh an order

Request a status check for an existing order. Checks are throttled and also run automatically in the background. Repeated refresh requests do not guarantee a fresh provider request

POST /orders/{id}/cancelCancel an order

Cancel an active order before an SMS has arrived. Only cancel when the order is active and sms is empty. The server checks whether the action is still allowed. Check refunded_at to

POST /orders/{id}/finishFinish an order

Complete an active order after receiving and using your SMS. Finish only after the sms array contains a message. This action ends the order; keep the message you need before finish