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.

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"

// Guzzle HTTP client
$client = new GuzzleHttp\Client();
$res = $client->get('https://smsgig.com/api/v1/balance', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);

import requests
res = requests.get(
    'https://smsgig.com/api/v1/balance',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

// Node.js (fetch)
const res = await fetch('https://smsgig.com/api/v1/balance', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await res.json();

// 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"

$client = new GuzzleHttp\Client();
$res = $client->get('https://smsgig.com/api/v1/transactions?limit=20&type=purchase', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);

import requests
res = requests.get(
    'https://smsgig.com/api/v1/transactions?limit=20&type=purchase',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

const res = await fetch('https://smsgig.com/api/v1/transactions?limit=20&type=purchase', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await res.json();

// 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"

$client = new GuzzleHttp\Client();
$res = $client->get('https://smsgig.com/api/v1/s1/services', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);

import requests
res = requests.get(
    'https://smsgig.com/api/v1/s1/services',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

const res = await fetch('https://smsgig.com/api/v1/s1/services', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await res.json();

{
  "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"}'

$client = new GuzzleHttp\Client();
$res = $client->post('https://smsgig.com/api/v1/s1/rent', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'json' => ['service_code' => 'whatsapp', 'area_code' => '212']
]);

import requests
res = requests.post(
    'https://smsgig.com/api/v1/s1/rent',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={"service_code": "whatsapp", "area_code": "212"}
)

const res = await fetch('https://smsgig.com/api/v1/s1/rent', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ service_code: 'whatsapp', area_code: '212' })
});
const data = await res.json();

{
  "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"

$client = new GuzzleHttp\Client();
$res = $client->get('https://smsgig.com/api/v1/s1/status?activation_id=10561661', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);

import requests
res = requests.get(
    'https://smsgig.com/api/v1/s1/status?activation_id=10561661',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

const res = await fetch('https://smsgig.com/api/v1/s1/status?activation_id=10561661', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await res.json();

// 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"}'

// Get status
$client = new GuzzleHttp\Client();
$res = $client->post('https://smsgig.com/api/v1/s1/rentals/status', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'json' => ['activation_id' => 10561661]
]);

// Mark finished
$resFinished = $client->post('https://smsgig.com/api/v1/s1/rentals/status', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'json' => ['activation_id' => 10561661, 'action' => 'finished']
]);

import requests

# Get status
res = requests.post(
    'https://smsgig.com/api/v1/s1/rentals/status',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={"activation_id": 10561661}
)

# Mark finished
res_finished = requests.post(
    'https://smsgig.com/api/v1/s1/rentals/status',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={"activation_id": 10561661, "action": "finished"}
)

// Get status
const res = await fetch('https://smsgig.com/api/v1/s1/rentals/status', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ activation_id: 10561661 })
});

// Mark finished
const resFinished = await fetch('https://smsgig.com/api/v1/s1/rentals/status', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ 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}'

$client = new GuzzleHttp\Client();
$res = $client->post('https://smsgig.com/api/v1/s1/rentals/cancel', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'json' => ['activation_id' => 10561661]
]);

import requests
res = requests.post(
    'https://smsgig.com/api/v1/s1/rentals/cancel',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={"activation_id": 10561661}
)

const res = await fetch('https://smsgig.com/api/v1/s1/rentals/cancel', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ activation_id: 10561661 })
});
const data = await res.json();

{ "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
}

import hmac, hashlib

# Flask / FastAPI Example
payload = request.get_data() # Raw bytes
signature = request.headers.get('X-SMSGig-Signature')

expected_sig = hmac.new(
    b'YOUR_API_KEY',
    msg=payload,
    digestmod=hashlib.sha256
).hexdigest()

if hmac.compare_digest(expected_sig, signature):
    # Valid request
    pass

const crypto = require('crypto');

// Express: Ensure you use the raw buffer body
const payload = req.rawBody; 
const signature = req.headers['x-smsgig-signature'];

const expectedSig = crypto
  .createHmac('sha256', 'YOUR_API_KEY')
  .update(payload)
  .digest('hex');

if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSig))) {
  // 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"
}