SMSGig
REST API

API Reference

The SMSGig API is organized around REST. Predictable resource-oriented URLs, JSON request bodies, JSON-encoded responses, and standard HTTP response codes.

API Info
Base URL https://smsgig.com/api/v1
Version v1
Format JSON
Auth Bearer Token

Interactive Tester

Every endpoint includes a built-in API tester. Enter your API key and parameters to send live requests directly from this page.

Secure by Default

All requests use Bearer token authentication. Your API key is stored locally in your browser session only.

Code Examples

cURL, PHP, Python, and Node.js snippets provided for every endpoint. One-click copy to clipboard.

Server Routing (S1)

Endpoints containing /s1/ indicate Server 1, which is primarily routed for USA numbers. Future endpoints may introduce new server prefixes for different regions.

Global API Key:

Authentication

All API requests require a valid API key. Include your key in the Authorization header using the Bearer scheme.

Never expose your API key in client-side code or public repositories. Treat it like a password.

Header format
Authorization: Bearer YOUR_API_KEY

Error Codes

SMSGig uses conventional HTTP response codes. Codes in the 2xx range indicate success. 4xx indicate client errors. 5xx indicate server errors.

200
Success — Request completed
400
Bad Request — Invalid parameters
401
Unauthorized — Invalid or missing API key
404
Not Found — Resource doesn't exist
422
Unprocessable — Validation failed
429
Rate Limited — Too many requests
500
Server Error — Something went wrong
GET

Get Balance

/balance

Retrieve your current wallet balance in USD.

curl -X GET "https://smsgig.com/api/v1/balance" \ -H "Authorization: Bearer YOUR_API_KEY"
// Response { "status": "success", "balance": 10.00, "currency": "USD" }
GET

Get Transactions

/transactions

Get paginated transaction history for your account.

Parameters
Name Type Description
limit integer Max 100, default 20
type string purchase, refund, deposit
curl -X GET "https://smsgig.com/api/v1/transactions?limit=20&type=purchase" \ -H "Authorization: Bearer YOUR_API_KEY"
// Response { "status": "success", "data": [{ "id": 1021, "type": "refund", "amount": 0.75, "description": "Refund for eBay rental #503", "created_at": "2026-05-15T09:21:41.000000Z" }], "meta": { "current_page": 1, "last_page": 2, "total": 37 } }
GET

List Services

/s1/services

Get all available services with pricing, TTL, and stock information.

curl -X GET "https://smsgig.com/api/v1/s1/services" \ -H "Authorization: Bearer YOUR_API_KEY"
{ "status": "success", "data": [{ "service_code": "whatsapp", "name": "WhatsApp", "price": 0.58, "ttl": 600, "count": 6989, "multiple_sms": true }], "meta": { "total": 360, "per_page": 100 } }
POST

Rent Number

/s1/rent

Rent a virtual number for SMS verification. Balance is deducted immediately.

Parameters
Name Type Description
service_code REQ string e.g. "whatsapp", "gmail"
area_code string Preferred area code e.g. "212"
carrier string Preferred carrier
curl -X POST "https://smsgig.com/api/v1/s1/rent" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"service_code": "whatsapp", "area_code": "212"}'
{ "status": "success", "rental": { "activation_id": 10561661, "phone_number": "14052003055", "status": "waiting", "service_code": "whatsapp", "price": 0.58, "ttl": 600, "created_at": "2026-05-18T13:57:56.000000Z" } }
GET

Check Status

/s1/status

Poll every 5-10 seconds to check for incoming SMS codes (webhook alternative).

Recommended polling interval: 2–3 seconds. Stop polling once a code is received or the rental expires.
Parameters
activation_id REQ From the rent response
curl -X GET "https://smsgig.com/api/v1/s1/status?activation_id=10561661" \ -H "Authorization: Bearer YOUR_API_KEY"
// SMS received { "status": "received", "code": "123456", "text": "Your WhatsApp code is 123456" } // No SMS yet { "status": "waiting", "message": "No SMS received yet" }
POST

Get/Update Rental Status

/s1/rentals/status

Get current rental status or mark a received rental as finished.

Parameters
Name Type Description
activation_id REQ integer Activation ID
action string "finished" to complete
# Get status curl -X POST "https://smsgig.com/api/v1/s1/rentals/status" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"activation_id": 10561661}' # Mark finished curl -X POST "https://smsgig.com/api/v1/s1/rentals/status" \ -d '{"activation_id": 10561661, "action": "finished"}'
{ "status": "success", "rental": { "activation_id": 10561661, "phone_number": 15181234567, "service_code": whatsapp, "status": "received", "code": "123456", "text": Your WhatsApp code is 123456, "price": 0.50, "created_at": 2026-02-18T21:07:34.000000Z, "ttl": 600 } }
POST

Cancel Rental

/s1/rentals/cancel

Cancel an active rental. Refund is issued if no SMS was received.

curl -X POST "https://smsgig.com/api/v1/s1/rentals/cancel" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"activation_id": 10561661}'
{ "status": "success", "message": "Rental canceled and refund processed" }
POST

Webhooks (Receive SMS)

Instead of continuously polling the /status endpoint, you can configure a Webhook URL in your dashboard. We will send an HTTP POST request to your URL immediately when an SMS is received.

Webhook Payload
Property Type Description
activation_id integer The rental ID the code belongs to
message_id string Unique identifier for this message
service string Service code (e.g., "whatsapp")
code string The extracted verification code
text string The full, raw SMS message content
received_at string Timestamp of receipt (ISO 8601)

Expected Response

Your server must return a 200 OK HTTP status code within 5 seconds to acknowledge receipt. If your server times out or returns a non-200 status, the webhook payload may be lost.

Verifying Signatures

To ensure the webhook was sent by SMSGig, we include an X-SMSGig-Signature header. This is an HMAC SHA256 hash of the raw request body signed with your API Key.

$payload = file_get_contents('php://input'); $signature = hash_hmac('sha256', $payload, 'YOUR_API_KEY'); if (hash_equals($signature, $_SERVER['HTTP_X_SMSGIG_SIGNATURE'])) { // Valid request }
Example Payload
{ "activation_id": 10561661, "message_id": "msg_10561661_a1b2c3d4", "service": "whatsapp", "code": "123456", "text": "Your WhatsApp code is 123456", "received_at": "2026-05-18T14:02:11.000000Z" }