OTP Grove REST API v1 — authenticate, list services, buy numbers, poll SMS, and manage orders. Same engine as the dashboard.
Base URL: https://otpgrove.com/api/v1/.
Charges deduct from your OTP Grove wallet. Orders created via API use the same order engine as the dashboard and appear immediately in Order History.
Existing API keys keep working — create or regenerate only from
Dashboard → API Key.
Every request requires your API key:
Authorization: Bearer YOUR_API_KEY?api_key=YOUR_API_KEYcurl -X GET "https://otpgrove.com/api/v1/balance/" \ -H "Authorization: Bearer YOUR_API_KEY"
Invalid / missing key → HTTP 401:
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "OTP Grove API Invalid API Key"
},
"error_message": "OTP Grove API Invalid API Key"
}
Used by /services/ and /buy/ as type. Names match the user dashboard sidebar. Each service row includes server_name (page name) and name with Server 1/2/3 labels — same as the dashboard.
| type | Dashboard name | Notes |
|---|---|---|
usa1 | Short Term USA 1 | USA temp — Server 1/2/3 |
usa2 | USA Short Term 2 | USA temp — Server 1/2 |
usa3 | USA Virtual Number | USA virtual — Server 1/2 |
global | Global Temp Number | country required — Server 1/2/3 |
longterm | Long Term Numbers | USA 1 / 3 / 7 / 14 / 30 Day products |
dedicated | Dedicated Numbers | 30-day by country & carrier |
dataplan | Buy E-Sim | eSIM / data plans |
All errors use OTP Grove branding. Shape:
{
"success": false,
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "OTP Grove API Balance Low"
},
"error_message": "OTP Grove API Balance Low"
}
| HTTP | code | Typical message |
|---|---|---|
| 401 | UNAUTHORIZED | OTP Grove API Invalid API Key |
| 400 | INSUFFICIENT_BALANCE | OTP Grove API Balance Low |
| 400 | NUMBER_UNAVAILABLE | OTP Grove API Service Unavailable |
| 400/404 | OTP_GROVE_ERROR | OTP Grove API Error: … |
| HTTP | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad request — see error.code / error.message (OTP Grove branded) |
| 401 | OTP Grove API Invalid API Key |
| 404 | Service or order not found |
| 429 | Rate limit exceeded — retry after 60s |
| 500 | OTP Grove API Error — contact support |
Wallet balance (server-authoritative).
curl -X GET "https://otpgrove.com/api/v1/balance/" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"balance": "8.56",
"currency": "USD"
}
List purchasable services (price > 0). Header X-Powered-By: OTPGrove API.
| Param | Required | Description |
|---|---|---|
type | Yes | One of the service types above |
country | Varies | Required for global. Optional filter for longterm, dedicated, dataplan |
curl -X GET "https://otpgrove.com/api/v1/services/?type=usa1" \ -H "Authorization: Bearer YOUR_API_KEY"
Temp / global item shape (same labels as the dashboard):
[
{
"id": 1358186,
"service_code": "wp",
"name": "WhatsApp (Server 1)",
"server_name": "Short Term USA 1",
"price": "0.0260",
"currency": "USD",
"provider": "OTP Grove",
"providerName": "OTP Grove"
}
]
Use id as service_id in POST /buy/. Sync tip: store server_name + name so your app matches the dashboard.
| Param | Required | Description |
|---|---|---|
type | No | global (default), longterm, or dedicated |
curl -X GET "https://otpgrove.com/api/v1/countries/?type=dedicated" \ -H "Authorization: Bearer YOUR_API_KEY"
GET /api/v1/services/?type=longterm returns these stable product IDs (same pricing as dashboard Long Term Numbers):
| service_id | Product |
|---|---|
900001 | Long Term Number USA — 1 Day |
900003 | Long Term Number USA — 3 Days |
900007 | Long Term Number USA — 7 Days |
900030 | Long Term Number USA — 30 Days |
curl -X POST "https://otpgrove.com/api/v1/buy/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"longterm","service_id":900001}'
If inventory is empty → OTP Grove API Service Unavailable.
GET /api/v1/services/?type=dedicated lists in-stock dedicated offers with country, carrier, and duration. Optional country filter. Buy with the returned id.
curl -X GET "https://otpgrove.com/api/v1/services/?type=dedicated&country=United%20States" \ -H "Authorization: Bearer YOUR_API_KEY"
JSON body. Debits wallet atomically on success.
| Field | Required | Description |
|---|---|---|
type | Yes | Service type |
service_id | Yes | Integer id from /services/ |
country | Varies | Required for global |
area_code | No | usa1/usa2/usa3 only — default Random Location |
quantity | No | Legacy longterm rental / dataplan (default 1) |
curl -X POST "https://otpgrove.com/api/v1/buy/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"usa1","service_id":1358186}'
{
"order_id": "42",
"number": "+1234567890",
"status": "pending",
"name": "WhatsApp (Server 1)",
"server_name": "Short Term USA 1",
"provider": "OTP Grove",
"providerName": "OTP Grove"
}
High-volume API bulk purchase for temporary SMS types (usa1, usa2, usa3, global).
Accepts 300+ numbers in one request (max 500).
Funds are reserved up front; you are charged only for successful purchases. Processing is asynchronous.
Required header: Idempotency-Key: UNIQUE_CLIENT_GENERATED_VALUE — repeating the same key returns the original batch; a different body with the same key returns 409.
| Field | Required | Description |
|---|---|---|
type | Yes | usa1, usa2, usa3, or global |
service_id | Yes | Integer id from /services/ (same catalog as single buy) |
quantity | Yes | 1 … 500 (supports 300+) |
country | Varies | Required when type=global — same country names/codes as catalog |
area_code | No | usa1/usa2/usa3 only — default Random Location |
curl -X POST "https://otpgrove.com/api/v1/orders/bulk/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: bulk-wa-2026-001" \
-H "Content-Type: application/json" \
-d '{"type":"usa1","service_id":1358186,"quantity":300}'
{
"success": true,
"batch_id": "BATCH-A1B2C3D4E5F60718",
"status": "queued",
"type": "usa1",
"service_id": 1358186,
"requested": 300,
"queued": 300,
"processing": 0,
"completed": 0,
"failed": 0,
"cancelled": 0,
"unit_price": "0.4500",
"reserved": "135.00",
"charged": "0.00",
"refunded": "0.00",
"message": "Your bulk order has been accepted for processing."
}
{
"success": false,
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "OTP Grove API Balance Low"
},
"error_message": "OTP Grove API Balance Low"
}
order_id — use /sms/, /status/, and /cancel/ per order.Track batch progress. Individual orders are paginated (page, page_size ≤ 100).
curl -X GET "https://otpgrove.com/api/v1/orders/bulk/BATCH-A1B2C3D4E5F60718/?page=1&page_size=50" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"batch_id": "BATCH-A1B2C3D4E5F60718",
"status": "partial",
"requested": 300,
"queued": 0,
"processing": 0,
"completed": 280,
"failed": 20,
"charged": "126.00",
"refunded": "9.00",
"orders": [
{"index": 0, "status": "success", "order_id": "42", "number": "+12025550100", "sell_price": "0.4500", "error": null}
],
"orders_page": 1,
"orders_page_size": 50,
"orders_total": 300
}
Poll SMS / OTP for an order you own. Poll every 3–5 seconds while pending.
| Param | Required | Description |
|---|---|---|
order_id | Yes | From buy response |
curl -X GET "https://otpgrove.com/api/v1/sms/?order_id=42" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"order_id": "42",
"sms": "Your code is 123456",
"status": "received"
}
Status: pending, received, cancelled, timeout.
Status only (no full SMS body).
curl -X GET "https://otpgrove.com/api/v1/status/?order_id=42" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"order_id": "42",
"status": "pending"
}
Cancel a pending SMS order when the dashboard cancel rules allow it (no OTP yet; within cancel window; not after renew). Refunds sell price to wallet when eligible.
Not supported for eSIM/dataplan orders and legacy SMSPool rental-request IDs — those return cancel-not-supported.
curl -X POST "https://otpgrove.com/api/v1/cancel/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"order_id":"42"}'
{
"status": "cancelled",
"refund": "0.50"
}
server_name matches sidebar names (Short Term USA 1, Global Temp Number, …)/sms/ or open the dashboardYes. OTPGrove REST API starts from about $0.10 per real non-VoIP OTP with no $30 minimum. SMS-Activate shut down — migrate getNumber/getSMS scripts to /api/v1/ endpoints.
Yes. Every usa1/usa2/global temp number via API is a real non-VoIP carrier number — not VoIP. Ideal for WhatsApp, Google, Telegram OTP automation.
Register free at /register/, fund your wallet, then copy your API key from the dashboard API Key page. Start integrating in minutes.
Yes. High-volume developers and resellers get bulk non-VoIP API access with volume discounts. Contact support for wholesale rates above 10,000 OTP/month.
Use POST /api/v1/orders/bulk/ with type, service_id, quantity, and a unique Idempotency-Key header. The API returns a batch_id immediately; poll GET /api/v1/orders/bulk/{batch_id}/ for progress. Each successful number is a normal order for /sms/ and /cancel/.
Standard accounts: 60 requests/minute per API key. Bulk/reseller tiers: 300+ requests/minute. Bulk create itself is limited separately (default 10 bulk requests/minute). Contact support to raise limits.
Webhook delivery for incoming SMS is on the roadmap for reseller tiers. Currently poll GET /api/v1/sms/ every 3–5 seconds for OTP.