Making Your First Request

This guide will walk you through making your first API request to the LightSMS API, including obtaining a timestamp and checking your account balance.

Prerequisites

Before making API requests, ensure you have:

• ✅ Login - Your LightSMS account login
• ✅ API Key - Your unique API key for authentication
• ✅ Timestamp - Current UTC timestamp (valid for 10 seconds)

Getting Your Credentials

You can retrieve your API credentials from the LightSMS admin panel under MISC → API. Your login and API key will be displayed there.

---

Step 1: Get Current Timestamp

All API requests require a timestamp parameter that is valid for 10 seconds.

Endpoint:

GET https://www.lightsms.com/external/get/timestamp.php

Example Request:

curl https://www.lightsms.com/external/get/timestamp.php

Response:

1732809600

Timestamp Validity

Timestamps expire after 10 seconds. If your request takes longer, you'll need to get a new timestamp.

---

Step 2: Create Request Signature

Every request must include a signature parameter to ensure security.

How Signature Works

1. Collect all parameters (except signature)
2. Sort alphabetically by parameter name
3. Concatenate values into a single string
4. Append API key at the end
5. Generate MD5 hash of the string

Example in PHP

function createSignature($params, $apiKey) {
    ksort($params);
    reset($params);
    return md5(implode($params) . $apiKey);
}

// Example usage
$params = [
    'login' => 'YourLogin',
    'timestamp' => '1732809600'
];

$apiKey = 'your_api_key_here';
$signature = createSignature($params, $apiKey);

echo $signature; // Output: generated_signature_hash

Example in Python

import hashlib

def create_signature(params, api_key):
    # Sort parameters alphabetically
    sorted_params = sorted(params.items())

    # Concatenate values
    param_string = ''.join([str(value) for key, value in sorted_params])

    # Append API key and generate MD5
    signature_string = param_string + api_key
    return hashlib.md5(signature_string.encode()).hexdigest()

# Example usage
params = {
    'login': 'YourLogin',
    'timestamp': '1732809600'
}

api_key = 'your_api_key_here'
signature = create_signature(params, api_key)
print(signature)

Example in JavaScript

const crypto = require('crypto');

function createSignature(params, apiKey) {
    // Sort parameters alphabetically
    const sortedKeys = Object.keys(params).sort();

    // Concatenate values
    const paramString = sortedKeys.map(key => params[key]).join('');

    // Append API key and generate MD5
    const signatureString = paramString + apiKey;
    return crypto.createHash('md5').update(signatureString).digest('hex');
}

// Example usage
const params = {
    login: 'YourLogin',
    timestamp: '1732809600'
};

const apiKey = 'your_api_key_here';
const signature = createSignature(params, apiKey);
console.log(signature);

---

Step 3: Check Your Balance

Now let's make your first API request to check your account balance.

Endpoint:

GET https://www.lightsms.com/external/get/balance.php

Required Parameters:

Parameter	Type	Description
login	string	Your LightSMS login
timestamp	integer	Current UTC timestamp
signature	string	MD5 hash signature

Optional Parameters:

Parameter	Type	Description
return	string	Response format: json or xml (default: plain text)

Example Request (JSON Response)

curl "https://www.lightsms.com/external/get/balance.php?login=YourLogin&timestamp=1732809600&signature=generated_signature&return=json"

Response:

{
    "money": "150.50",
    "currency": "EUR"
}

Example Request (XML Response)

curl "https://www.lightsms.com/external/get/balance.php?login=YourLogin&timestamp=1732809600&signature=generated_signature&return=xml"

Response:

<?xml version="1.0" encoding="utf-8"?>
<response>
   <money>150.50</money>
   <currency>EUR</currency>
</response>

---

Complete Example: PHP

Here's a complete working example in PHP:

<?php
// Configuration
$login = 'YourLogin';
$apiKey = 'your_api_key_here';

// Step 1: Get timestamp
$timestamp = file_get_contents('https://www.lightsms.com/external/get/timestamp.php');

// Step 2: Prepare parameters
$params = [
    'login' => $login,
    'timestamp' => trim($timestamp),
    'return' => 'json'
];

// Step 3: Create signature
function createSignature($params, $apiKey) {
    ksort($params);
    reset($params);
    return md5(implode($params) . $apiKey);
}

$signature = createSignature($params, $apiKey);
$params['signature'] = $signature;

// Step 4: Make request
$url = 'https://www.lightsms.com/external/get/balance.php?' . http_build_query($params);
$response = file_get_contents($url);

// Step 5: Parse response
$data = json_decode($response, true);
echo "Balance: {$data['money']} {$data['currency']}\n";
?>

---

Complete Example: Python

import requests
import hashlib
from urllib.parse import urlencode

# Configuration
LOGIN = 'YourLogin'
API_KEY = 'your_api_key_here'

# Step 1: Get timestamp
timestamp_response = requests.get('https://www.lightsms.com/external/get/timestamp.php')
timestamp = timestamp_response.text.strip()

# Step 2: Prepare parameters
params = {
    'login': LOGIN,
    'timestamp': timestamp,
    'return': 'json'
}

# Step 3: Create signature
def create_signature(params, api_key):
    sorted_params = sorted(params.items())
    param_string = ''.join([str(value) for key, value in sorted_params])
    signature_string = param_string + api_key
    return hashlib.md5(signature_string.encode()).hexdigest()

signature = create_signature(params, API_KEY)
params['signature'] = signature

# Step 4: Make request
url = f'https://www.lightsms.com/external/get/balance.php?{urlencode(params)}'
response = requests.get(url)

# Step 5: Parse response
data = response.json()
print(f"Balance: {data['money']} {data['currency']}")

---

Common Issues

"Invalid signature" Error

Problem: You're getting error code 6 (Invalid signature)

Solutions:

• ✅ Ensure parameters are sorted alphabetically
• ✅ Concatenate only parameter values, not keys
• ✅ Append API key at the end (not at the beginning)
• ✅ Use lowercase for MD5 hash
• ✅ Don't include signature parameter when generating signature

"Timestamp not specified" Error

Problem: You're getting error code 24

Solutions:

• ✅ Include timestamp parameter in every request
• ✅ Get a fresh timestamp (less than 10 seconds old)
• ✅ Use UTC timestamp, not local time

"Invalid login" Error

Problem: You're getting error code 7

Solutions:

• ✅ Double-check your login spelling
• ✅ Ensure your account is active
• ✅ Contact support if login is correct

---

Next Steps

Now that you've made your first request, you can:

• Send your first SMS
• Manage recipient lists
• Create SMS templates
• Check delivery status

---

Need Help?

If you encounter any issues:

• Email: [email protected]
• Phone: Contact Information
• Business hours: Monday-Friday, 8:00-20:00 (EET)

For more information about authentication, see Authentication.