Skip to main content
ScrapingBuddy
Skip to content
ScrapingBuddyDevelopers
Dashboard
On this page Create and store your key

SMS API/Guides

Authentication

Create a customer key and connect your backend securely.

Create and store your key

Open API access from your signed-in dashboard, name the integration and create a key. The full secret is shown once. Store it in a secret manager or server environment variable.

Keys created through the dashboard remain valid until revoked. You can create separate keys for separate integrations; there is no limit on the number of keys. Rate limits are shared by the customer, not multiplied by key count.

Authorize every request

All SMS endpoints require Authorization: Bearer YOUR_API_KEY. Use only your ScrapingBuddy customer key, not credentials from another service.

Use HTTPS and the base URL below. For JSON request bodies, also send Content-Type: application/json.

Request headers
GET /api/v1/balance HTTP/1.1
Host: www.scrapingbuddy.com
Authorization: Bearer YOUR_API_KEY

Keep credentials private

Never place a key in browser JavaScript, mobile app bundles, URL query strings, screenshots or source control. Make API calls from your backend.

If a key is exposed, revoke it in API access and update your integration with a newly created key. Do not include keys in support tickets or application logs.

Understand account access

Your API keys can read SMS catalogue data, manage your own SMS orders and read the shared wallet balance. You cannot access another customer's orders.

Wallet top-ups and API-key management take place in the signed-in dashboard. A 401 response means the key is missing, invalid, revoked or expired. Check the header and the key status before retrying.

Manage API keysOrder API referenceContact support
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