API Documentation

Welcome to the Workplace by Webpal SMS Gateway API documentation. Our RESTful API allows you to send SMS messages, check delivery status, and manage your account programmatically.

KYC Verification Required

Until your KYC is verified, you can only send test SMS to your registered phone number. Complete KYC verification to unlock full messaging capabilities.

Quick Start

  1. Register for an account at workplace.webpal.it
  2. Complete KYC verification for full access
  3. Generate an API key from your dashboard
  4. Start sending SMS using the API

Authentication

All API requests require authentication using an API key. You can generate API keys from your client dashboard.

API Key Format

API keys are prefixed with sk_ followed by a 60-character random string.

Example API Key 
sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Passing API Key

Include your API key in the request header:

HTTP Header (Recommended) 
X-API-Key: sk_your_api_key_here

Note: You can also pass the API key as a query parameter api_key, but using headers is recommended for security.

Base URL

All API endpoints are relative to the following base URL:

Production 
https://workplace.webpal.it/api/v1

Rate Limits

API requests are rate-limited to ensure fair usage and system stability.

Endpoint Rate Limit
Send SMS 100 requests/minute
Send Bulk SMS 10 requests/minute
Status/History/Balance 300 requests/minute
POST

Send SMS

Send a single SMS message to a recipient.

Endpoint 
POST /api/v1/sms/send

Request Parameters

Parameter Type Required Description
to string Required Recipient phone number (10-15 digits)
message string Required Message content (max 1600 characters)
sender_id string Optional Sender ID (max 11 characters, defaults to account setting)

Example Request

cURL 
curl -X POST "https://workplace.webpal.it/api/v1/sms/send" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "9841234567",
    "message": "Hello! This is a test message.",
    "sender_id": "WEBPAL"
  }'

Success Response

200 OK 
{
  "status": "success",
  "message": "SMS sent successfully",
  "data": {
    "message_id": "msg_abc123def456",
    "to": "9841234567",
    "credits_used": 1,
    "status": "sent"
  }
}

Error Response

400 Bad Request 
{
  "status": "error",
  "message": "Insufficient credits",
  "data": null
}
POST

Send Bulk SMS

Send the same message to multiple recipients in a single request.

Endpoint 
POST /api/v1/sms/send-bulk

Request Parameters

Parameter Type Required Description
recipients array Required Array of phone numbers (max 1000)
message string Required Message content (max 1600 characters)
sender_id string Optional Sender ID (max 11 characters)

Example Request

cURL 
curl -X POST "https://workplace.webpal.it/api/v1/sms/send-bulk" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["9841234567", "9851234567", "9861234567"],
    "message": "Special offer! Get 20% off today.",
    "sender_id": "WEBPAL"
  }'

Success Response

200 OK 
{
  "status": "success",
  "message": "Bulk SMS processed: 3 sent, 0 failed",
  "data": {
    "total": 3,
    "success": 3,
    "failed": 0,
    "credits_used": 3,
    "results": [
      {"success": true, "message_id": "msg_abc123", "recipient": "9841234567"},
      {"success": true, "message_id": "msg_def456", "recipient": "9851234567"},
      {"success": true, "message_id": "msg_ghi789", "recipient": "9861234567"}
    ]
  }
}
GET

Message Status

Check the delivery status of a sent message.

Endpoint 
GET /api/v1/sms/status/{message_id}

Example Request

cURL 
curl -X GET "https://workplace.webpal.it/api/v1/sms/status/msg_abc123def456" \
  -H "X-API-Key: sk_your_api_key_here"

Success Response

200 OK 
{
  "status": "success",
  "data": {
    "message_id": "msg_abc123def456",
    "recipient": "9841234567",
    "sender_id": "WEBPAL",
    "status": "delivered",
    "credits_used": 1,
    "sent_at": "2026-01-15T10:30:00+05:45",
    "delivered_at": "2026-01-15T10:30:05+05:45",
    "created_at": "2026-01-15T10:29:58+05:45"
  }
}
GET

Message History

Retrieve your message history with pagination and filtering options.

Endpoint 
GET /api/v1/sms/history

Query Parameters

page (default: 1), per_page (default: 50, max: 100), status, from_date, to_date

Example Request

cURL 
curl -X GET "https://workplace.webpal.it/api/v1/sms/history?page=1&per_page=20&status=sent" \
  -H "X-API-Key: sk_your_api_key_here"
GET

Check Balance

Check your current SMS credit balance and KYC status.

Endpoint 
GET /api/v1/account/balance

Example Request

cURL 
curl -X GET "https://workplace.webpal.it/api/v1/account/balance" \
  -H "X-API-Key: sk_your_api_key_here"

Success Response

200 OK 
{
  "status": "success",
  "data": {
    "credits": 5000,
    "kyc_status": "approved",
    "kyc_verified": true
  }
}

Code Examples

cURL

Send SMS with cURL 
curl -X POST "https://workplace.webpal.it/api/v1/sms/send" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "to": "9841234567",
    "message": "Your OTP is 123456. Valid for 5 minutes.",
    "sender_id": "WEBPAL"
  }'

PHP

Send SMS with PHP 
<?php

$apiKey = 'sk_your_api_key_here';
$baseUrl = 'https://workplace.webpal.it/api/v1';

function sendSms($to, $message, $senderId = null) {
    global $apiKey, $baseUrl;
    
    $data = ['to' => $to, 'message' => $message];
    if ($senderId) $data['sender_id'] = $senderId;
    
    $ch = curl_init($baseUrl . '/sms/send');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $apiKey,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode($data),
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Usage
$result = sendSms('9841234567', 'Hello from Workplace!', 'WEBPAL');
print_r($result);

JavaScript

Send SMS with JavaScript 
const API_KEY = 'sk_your_api_key_here';
const BASE_URL = 'https://workplace.webpal.it/api/v1';

async function sendSms(to, message, senderId = null) {
    const data = { to, message };
    if (senderId) data.sender_id = senderId;
    
    const response = await fetch(`${BASE_URL}/sms/send`, {
        method: 'POST',
        headers: {
            'X-API-Key': API_KEY,
            'Content-Type': 'application/json',
        },
        body: JSON.stringify(data),
    });
    
    return await response.json();
}

// Usage
const result = await sendSms('9841234567', 'Hello from Workplace!', 'WEBPAL');
console.log(result);

Python

Send SMS with Python 
import requests

API_KEY = 'sk_your_api_key_here'
BASE_URL = 'https://workplace.webpal.it/api/v1'

headers = {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json',
}

def send_sms(to: str, message: str, sender_id: str = None) -> dict:
    data = {'to': to, 'message': message}
    if sender_id:
        data['sender_id'] = sender_id
    
    response = requests.post(f'{BASE_URL}/sms/send', headers=headers, json=data)
    return response.json()

# Usage
result = send_sms('9841234567', 'Hello from Workplace!', 'WEBPAL')
print(result)

Error Codes

Code Meaning Description
200 OK Request successful
400 Bad Request Invalid request (e.g., insufficient credits)
401 Unauthorized Missing or invalid API key
403 Forbidden Account inactive or IP not whitelisted
404 Not Found Resource not found
422 Validation Error Request data failed validation
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error

Message Status Codes

pending

Message queued and waiting to be sent

sent

Message sent to the gateway

delivered

Message delivered to recipient

failed

Message delivery failed

rejected

Message rejected by gateway

Need Help?

If you have any questions or need assistance with the API integration, our support team is here to help.

Email Support Client Portal