📚 API Reference

Developer API Reference

Complete endpoint documentation with real-world examples in multiple languages. All examples include live responses and parameter documentation.

Generate an API Key View Endpoints ↓

Authentication

Every request requires your API key in the X-API-Key header.

Required Header

X-API-Key: sgk_your_key_here

⚠️ Security Note

Never commit your API key to version control. Keep it secret like a password.

Rate Limits

Developer APINo enforced per-minute cap (current policy)

Auth requirementValid X-API-Key is required on all developer endpoints

Safety controlsAbuse monitoring and key revocation are still active

Future policyRate limits may be introduced later with advance notice

429 response = rate limited. Wait before retrying.

Endpoints

All SMS, SMM, wallet, and communication endpoints available via API.

WhatsApp Notifications

POST/api/developer/v1/notifications/send

WhatsApp Notifications API

Send approved production WhatsApp templates with fixed NGN billing per one message. Provider details are never exposed to the user.

💡 Use Case

Use this to send OTPs, alerts, order updates, and system notifications from approved templates only. Wallet balance is required before each send.

Parameters

template_idrequiredinteger

Approved WhatsApp template ID

torequiredstring

Recipient phone number in E.164 format

variablesoptionalobject

Template variables keyed by placeholder index

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/notifications/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.SMSGANG_API_KEY
  },
  body: JSON.stringify({
    template_id: 1,
    to: '+2348012345678',
    variables: { '1': '123456' }
  })
});

console.log(await response.json());

Response (201)

Successful response

{
  "message": "WhatsApp notification queued successfully.",
  "data": {
    "id": 1,
    "template_id": 1,
    "message_sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "queued",
    "to": "+2348012345678",
    "unit_price_ngn": 20,
    "quantity": 1,
    "charged_amount_ngn": 20,
    "billing_status": "charged"
  }
}

Possible Errors

422Insufficient balance

422Template not ready for dispatch

429Send in progress

GET/api/developer/v1/notifications/messages

List WhatsApp Notification History

List your WhatsApp notification history with status and wallet billing data only. Provider name, provider cost, and internal profit data are hidden from the user.

💡 Use Case

Use this to build a user history page that shows charges and delivery state.

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/notifications/messages', {
  headers: { 'X-API-Key': process.env.SMSGANG_API_KEY }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": [
    {
      "id": 1,
      "template_id": 1,
      "message_sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "status": "delivered",
      "to": "+2348012345678",
      "unit_price_ngn": 20,
      "quantity": 1,
      "charged_amount_ngn": 20,
      "billing_status": "charged"
    }
  ]
}

POST/api/webhooks/whatsapp/status

WhatsApp Webhook Status

Twilio status callback for production WhatsApp messages.

💡 Use Case

Use this to keep delivery status updated in real time.

Parameters

MessageSidrequiredstring

Twilio message SID

MessageStatusrequiredstring

queued, sent, delivered, read, failed, or undelivered

Example

JAVASCRIPT

// Twilio posts this automatically; no manual client call is needed.
    console.log('Status callback endpoint is consumed by SMSGang backend.');

Response (200)

Successful response

{ "message": "ok" }

SMS Catalog

GET/api/developer/v1/services

List SMS Services

Retrieve all available SMS services your account has access to. This includes services like WhatsApp, Telegram, Gmail, etc.

💡 Use Case

Use this endpoint to populate a dropdown or list of available services before purchasing an activation.

Example

JAVASCRIPT

const services = await fetch('https://api.smsgang.org/api/developer/v1/services', {
  headers: { 'X-API-Key': process.env.SMSGANG_API_KEY }
}).then(r => r.json());

services.forEach(s => console.log(s.name + ' (ID: ' + s.id + ')'));

Response (200)

Successful response

{
  "data": [
    {
      "id": 1,
      "name": "Telegram",
      "slug": "telegram",
      "price": 0.15,
      "min_quantity": 1,
      "max_quantity": 2500
    },
    {
      "id": 2,
      "name": "WhatsApp",
      "slug": "whatsapp",
      "price": 0.35,
      "min_quantity": 1,
      "max_quantity": 5000
    }
  ]
}

GET/api/developer/v1/countries

List Countries

Get a complete list of countries where SMS activations are available. Each country includes its name, code, and current availability status.

💡 Use Case

Build a country selector in your application or filter services by specific regions.

Example

JAVASCRIPT

const countries = await fetch('https://api.smsgang.org/api/developer/v1/countries', {
  headers: { 'X-API-Key': process.env.SMSGANG_API_KEY }
}).then(r => r.json());

// Filter available countries
const available = countries.data.filter(c => c.is_available);

Response (200)

Successful response

{
  "data": [
    {
      "id": 1,
      "name": "United States",
      "code": "US",
      "is_available": true
    },
    {
      "id": 2,
      "name": "United Kingdom", 
      "code": "GB",
      "is_available": true
    }
  ]
}

GET/api/developer/v1/services/{service}/countries

Get Service Countries & Pricing

Retrieve available countries for a specific service with live pricing for each country. Prices update in real-time based on demand.

💡 Use Case

Show users the exact price they'll pay before they select a country for their activation.

Parameters

servicerequiredstring

Service slug (e.g., "telegram", "whatsapp", "gmail")

Example

JAVASCRIPT

const prices = await fetch('https://api.smsgang.org/api/developer/v1/services/telegram/countries', {
  headers: { 'X-API-Key': process.env.SMSGANG_API_KEY }
}).then(r => r.json());

prices.data.forEach(country => {
  console.log(country.name + ': $' + country.price + '/code');
});

Response (200)

Successful response

{
  "data": [
    {
      "id": 1,
      "name": "United States",
      "price": 0.15,
      "operators_count": 3
    },
    {
      "id": 2,
      "name": "United Kingdom",
      "price": 0.18,
      "operators_count": 2
    }
  ]
}

SMS Activations

POST/api/developer/v1/activations/buy

Purchase SMS Activation

Purchase a new SMS activation for receiving verification codes. The SMS is deducted from your account balance and you have a limited time to receive the code.

💡 Use Case

Example: Your user selects Telegram in US → call this endpoint → receive a phone number → user signs up on Telegram with that number.

Parameters

servicerequiredstring

Service slug (e.g., "telegram", "whatsapp")

countryrequiredstring

Country code (e.g., "US", "GB")

Example

JAVASCRIPT

const activation = await fetch('https://api.smsgang.org/api/developer/v1/activations/buy', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.SMSGANG_API_KEY
  },
  body: JSON.stringify({
    service: 'telegram',
    country: 'US'
  })
}).then(r => r.json());

console.log('Phone: ' + activation.data.phone);
console.log('Code expires in: ' + activation.data.timeout + 's');

Response (201)

Successful response

{
  "data": {
    "id": 12345,
    "phone": "+1234567890",
    "service": "telegram",
    "country": "US",
    "timeout": 900,
    "created_at": "2024-04-17T10:30:00Z"
  }
}

Possible Errors

400Invalid service or country

401Unauthorized - Invalid API key

422Insufficient balance

GET/api/developer/v1/activations/{activation}/check-sms

Check SMS Code

Poll for the incoming SMS code for a pending activation. If no code has arrived yet, returns empty. Must be called while the activation is in pending state.

💡 Use Case

Call this endpoint every 3-5 seconds to check if the SMS code has arrived. Stop polling once you have the code or the timeout expires.

Parameters

activationrequiredinteger

Activation ID returned from the buy endpoint

Example

JAVASCRIPT

async function waitForCode(activationId) {
  const maxAttempts = 300; // 15 minutes
  let attempts = 0;
  
  while (attempts < maxAttempts) {
    const res = await fetch(
      'https://api.smsgang.org/api/developer/v1/activations/' + activationId + '/check-sms',
      { headers: { 'X-API-Key': process.env.SMSGANG_API_KEY } }
    ).then(r => r.json());
    
    if (res.data.code) {
      return res.data.code;
    }
    
    await new Promise(r => setTimeout(r, 5000)); // Wait 5 seconds
    attempts++;
  }
}

Response (200)

Successful response

{
  "data": {
    "code": "123456",
    "status": "completed"
  }
}

Possible Errors

404Activation not found

410Activation expired

Wallet Management

GET/api/developer/v1/wallet/balance

Get Wallet Balance

Check your current account balance. This balance is used to purchase activations, SMM services, and other features.

💡 Use Case

Display the current balance to users or check if there's sufficient balance before making a purchase.

Example

JAVASCRIPT

const balance = await fetch('https://api.smsgang.org/api/developer/v1/wallet/balance', {
  headers: { 'X-API-Key': process.env.SMSGANG_API_KEY }
}).then(r => r.json());

console.log('Available: $' + balance.data.balance);
console.log('Hold: $' + balance.data.hold);

Response (200)

Successful response

{
  "data": {
    "balance": 150.50,
    "hold": 10.00,
    "available": 140.50,
    "currency": "USD"
  }
}

Developer Account

GET/api/developer/api-keys

List API Keys

List every API key owned by the authenticated user, including name, status, prefix, and usage metadata.

💡 Use Case

Use this to show the key management screen inside your dashboard.

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/api-keys', {
  headers: { Authorization: 'Bearer YOUR_SANCTUM_TOKEN' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": [
    {
      "id": 1,
      "name": "Production key",
      "key_prefix": "sgk_ab12",
      "last_used_at": "2026-04-17T09:10:00Z",
      "revoked_at": null
    }
  ]
}

POST/api/developer/api-keys

Create API Key

Create a new API key for a developer account. The secret is shown once and the stored key is hashed.

💡 Use Case

Use this when a user clicks Create Key in the dashboard. Store the plain secret only once.

Parameters

namerequiredstring

Friendly name for the key, such as Production or Staging

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/api-keys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_SANCTUM_TOKEN'
  },
  body: JSON.stringify({ name: 'Production key' })
});

console.log(await response.json());

Response (201)

Successful response

{
  "data": {
    "id": 2,
    "name": "Production key",
    "plain_key": "sgk_live_XXXXXXXXXXXXXXXX",
    "key_prefix": "sgk_live",
    "revoked_at": null
  }
}

DELETE/api/developer/api-keys/{developerApiKey}

Delete API Key

Revoke an API key permanently. This should be used when a key is compromised or no longer needed.

💡 Use Case

Use this from the dashboard when the user clicks Revoke.

Parameters

developerApiKeyrequiredinteger

The API key record ID to revoke

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/api-keys/2', {
  method: 'DELETE',
  headers: { Authorization: 'Bearer YOUR_SANCTUM_TOKEN' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "message": "API key revoked successfully"
}

SMM / Boosting

GET/api/developer/v1/smm/services

List SMM Services

List all social media marketing services available to the developer account.

💡 Use Case

Use this to show followers, likes, views, and engagement products in your app.

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/smm/services', {
  headers: { 'X-API-Key': 'sgk_your_key_here' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": [
    { "id": 101, "name": "Instagram Followers", "rate": 0.5 },
    { "id": 102, "name": "TikTok Views", "rate": 0.2 }
  ]
}

GET/api/developer/v1/smm/services/{service}

Show SMM Service

Get pricing, limits, and metadata for one SMM service.

💡 Use Case

Use this when the user opens a specific SMM product page.

Parameters

servicerequiredinteger

SMM service ID

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/smm/services/101', {
  headers: { 'X-API-Key': 'sgk_your_key_here' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": {
    "id": 101,
    "name": "Instagram Followers",
    "min": 100,
    "max": 10000,
    "rate": 0.5
  }
}

POST/api/developer/v1/smm/orders

Create SMM Order

Create a new SMM order for a social media service.

💡 Use Case

Use this to place boost orders after the user provides a target link and quantity.

Parameters

smm_service_idrequiredinteger

SMM service ID

linkrequiredstring

Target URL or social profile link

quantityrequiredinteger

Requested quantity

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/smm/orders', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sgk_your_key_here'
  },
  body: JSON.stringify({
    smm_service_id: 101,
    link: 'https://instagram.com/example',
    quantity: 1000
  })
});

console.log(await response.json());

Response (201)

Successful response

{
  "data": {
    "id": 9001,
    "status": "pending",
    "quantity": 1000
  }
}

GET/api/developer/v1/smm/orders

List SMM Orders

List all SMM orders for the authenticated developer account.

💡 Use Case

Use this to build an orders page for boost deliveries and status tracking.

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/smm/orders', {
  headers: { 'X-API-Key': 'sgk_your_key_here' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": [
    { "id": 9001, "status": "pending" },
    { "id": 9002, "status": "completed" }
  ]
}

GET/api/developer/v1/smm/orders/{order}

Show SMM Order

Get the current state and progress for one SMM order.

💡 Use Case

Use this to show delivery progress after an order is placed.

Parameters

orderrequiredinteger

SMM order ID

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/smm/orders/9001', {
  headers: { 'X-API-Key': 'sgk_your_key_here' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": { "id": 9001, "status": "pending", "progress": 42 }
}

Monthly Numbers

GET/api/developer/v1/monthly-numbers/inventory

Monthly Number Inventory

Show the monthly communication number inventory and prices before purchase.

💡 Use Case

Use this to let developers choose a subscription country or package.

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/monthly-numbers/inventory', {
  headers: { 'X-API-Key': 'sgk_your_key_here' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": [
    { "country": "US", "price": 6.0 },
    { "country": "GB", "price": 5.0 }
  ]
}

POST/api/developer/v1/monthly-numbers/purchase

Purchase Monthly Number

Purchase a monthly communication number subscription.

💡 Use Case

Use this after a user selects a country and you want to start the subscription.

Parameters

countryrequiredstring

Country code to purchase

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/monthly-numbers/purchase', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sgk_your_key_here'
  },
  body: JSON.stringify({ country: 'US' })
});

console.log(await response.json());

Response (201)

Successful response

{
  "data": { "id": 7001, "country": "US", "status": "active" }
}

GET/api/developer/v1/monthly-numbers/subscriptions

List Monthly Subscriptions

List active and past monthly communication number subscriptions.

💡 Use Case

Use this in a subscriptions dashboard.

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/monthly-numbers/subscriptions', {
  headers: { 'X-API-Key': 'sgk_your_key_here' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": [
    { "id": 7001, "country": "US", "status": "active" }
  ]
}

GET/api/developer/v1/monthly-numbers/subscriptions/{subscription}

Show Monthly Subscription

Get details for one monthly number subscription.

💡 Use Case

Use this to show the current subscription state and renewal settings.

Parameters

subscriptionrequiredinteger

Subscription ID

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/monthly-numbers/subscriptions/7001', {
  headers: { 'X-API-Key': 'sgk_your_key_here' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": { "id": 7001, "country": "US", "status": "active" }
}

PATCH/api/developer/v1/monthly-numbers/subscriptions/{subscription}/auto-renew

Update Auto Renew

Enable or disable auto-renew for a monthly number subscription.

💡 Use Case

Use this in a billing settings page.

Parameters

subscriptionrequiredinteger

Subscription ID

auto_renewrequiredboolean

True to enable auto-renew

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/monthly-numbers/subscriptions/7001/auto-renew', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sgk_your_key_here'
  },
  body: JSON.stringify({ auto_renew: true })
});

console.log(await response.json());

Response (200)

Successful response

{
  "message": "Auto renew updated successfully"
}

GET/api/developer/v1/monthly-numbers/subscriptions/{subscription}/messages

List Subscription Messages

List incoming messages received on a monthly communication number.

💡 Use Case

Use this when you need to display SMS history for a purchased number.

Parameters

subscriptionrequiredinteger

Subscription ID

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/monthly-numbers/subscriptions/7001/messages', {
  headers: { 'X-API-Key': 'sgk_your_key_here' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": [
    { "from": "+1234567890", "message": "Your code is 123456" }
  ]
}

POST/api/developer/v1/monthly-numbers/subscriptions/{subscription}/messages

Send Number Message

Send an SMS message using a purchased monthly communication number.

💡 Use Case

Use this to build user-initiated outbound SMS flows.

Parameters

subscriptionrequiredinteger

Subscription ID

torequiredstring

Destination phone number

messagerequiredstring

Message body

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/monthly-numbers/subscriptions/7001/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sgk_your_key_here'
  },
  body: JSON.stringify({ to: '+1234567890', message: 'Hello from SMSGang' })
});

console.log(await response.json());

Response (201)

Successful response

{
  "message": "Message sent successfully"
}

Wallet

GET/api/developer/v1/wallet/transactions

Wallet Transactions

List wallet debit and credit history for the developer account.

💡 Use Case

Use this to build statement or ledger views.

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/wallet/transactions', {
  headers: { 'X-API-Key': 'sgk_your_key_here' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": [
    { "id": 1, "type": "credit", "amount": 100 },
    { "id": 2, "type": "debit", "amount": 15 }
  ]
}

GET/api/developer/v1/wallet/history

Wallet History Alias

Alias for wallet transactions, kept for backward compatibility.

💡 Use Case

Use this only if a legacy client already calls /history.

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/wallet/history', {
  headers: { 'X-API-Key': 'sgk_your_key_here' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": [
    { "id": 1, "type": "credit", "amount": 100 },
    { "id": 2, "type": "debit", "amount": 15 }
  ]
}

GET/api/developer/v1/transactions

Platform Transactions

List all transactions related to the developer account across SMS, SMM, and numbers.

💡 Use Case

Use this for an all-in-one finance and activity page.

Example

JAVASCRIPT

const response = await fetch('https://api.smsgang.org/api/developer/v1/transactions', {
  headers: { 'X-API-Key': 'sgk_your_key_here' }
});

console.log(await response.json());

Response (200)

Successful response

{
  "data": [
    { "id": 11, "type": "sms_purchase", "amount": 5 },
    { "id": 12, "type": "smm_order", "amount": 20 }
  ]
}

Ready to integrate?

Get your API key and start building within minutes.

Create API Key Back to Docs