Reseller REST API

API Authentication

All API requests require an API Key token in the request header. Pass your key using the `Auth` header.

Private Key Authentication Required

To acquire your unique secure 60-character cryptographic token, please create a free user account or log into your client matrix dashboard.

Login to get API Key

1. Check Wallet Balance

Get your reseller profile and balance information.

GET https://codysms.com/api/v1/profile
cURL Example:
curl -X GET "https://codysms.com/api/v1/profile" -H "Auth: your_api_key_here"
JavaScript Example:
fetch('https://codysms.com/api/v1/profile', {
    headers: { 'Auth': 'your_api_key_here' }
})
.then(r => r.json())
.then(d => console.log(d))
Response (200 OK):
{
    "success": true,
    "user": {
        "name": "Merchant Name",
        "email": "developer@example.com",
        "balance": "$340.50"
    }
}

2. Rent Short-Term Number

Rent real mobile numbers instantly. Maximum 5 active rentals at a time.

POST https://codysms.com/api/v1/number/rent
Required Parameters:
ParameterTypeRequirementDescription
serviceStringRequiredService slug: whatsapp, telegram, google, facebook, etc.
cURL Example:
curl -X POST "https://codysms.com/api/v1/number/rent" \
  -H "Auth: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"service": "whatsapp"}'
JavaScript Example:
fetch('https://codysms.com/api/v1/number/rent', {
    method: 'POST',
    headers: {'Auth': 'your_api_key_here'},
    body: JSON.stringify({service: 'whatsapp'})
})
.then(r => r.json())
.then(d => console.log(d))
Response (200 OK):
{
    "success": true,
    "message": "Number rented successfully via API.",
    "rental": {
        "id": 13322954,
        "phone": "15012774216",
        "service": "Whatsapp",
        "cost": "$1.44",
        "end_time": "2026-07-10T10:20:00+00:00"
    }
}

3. Check Live Inbound OTP Code

Check if SMS has been received. Call regularly in a polling loop.

GET https://codysms.com/api/v1/number/check-otp/{rental_id}
JavaScript Polling Loop:
const pollOTP = (rentalId) => {
    const interval = setInterval(async () => {
        const res = await fetch(
            `https://codysms.com/api/v1/number/check-otp/${rentalId}`,
            {headers: {'Auth': 'your_api_key_here'}}
        );
        const data = await res.json();
        if (data.sms_received) {
            console.log('OTP:', data.sms_code);
            clearInterval(interval);
        }
    }, 2000);
};
Response - OTP Received:
{
    "success": true,
    "sms_received": true,
    "sms_code": "489201",
    "full_message": "Your WhatsApp verification code is: 489-201"
}
Response - Waiting for SMS:
{
    "success": true,
    "sms_received": false,
    "message": "Waiting for SMS."
}

4. Query Rental History Log

View all your rental history with pagination support.

GET https://codysms.com/api/v1/rentals/history 
{
    "success": true,
    "current_page": 1,
    "total_records": 450,
    "data": [
        {
            "id": 13322954,
            "phone_number": "15012774216",
            "service_name": "WhatsApp",
            "cost": 1.44,
            "sms_code": "489201",
            "status": "completed"
        }
    ]
}

5. Cancel Active Rental

Cancel active rental and get refund. Cannot cancel after OTP is received.

DELETE https://codysms.com/api/v1/rentals/{rental_id} 
{
    "success": true,
    "message": "Rental cancelled successfully."
}

6. Active Long-Term Rentals Tracker

View your active long-term rental numbers.

GET https://codysms.com/api/v1/rentals/long-term/active 
{
    "success": true,
    "active_long_rentals_count": 1,
    "rentals": []
}

7. Live Inbound SMS HTTP Webhooks

When SMS arrives on a rented number, we send it to your webhook endpoint automatically.

WEBHOOK POST ↳ https://yourdomain.com/api/sms-listener
📨 Webhook Payload Structure:

When SMS arrives, we send POST with this JSON:

{
    "event": "sms.received",
    "timestamp": 1781151781,
    "rental_id": 13322954,
    "phone": "15012774216",
    "service_slug": "whatsapp",
    "sms_code": "489201",
    "raw_text": "Your WhatsApp verification code is: 489-201"
}
✅ Your Server Response Format:
{
    "success": true,
    "message": "SMS received successfully"
}
👨‍💻 Node.js/Express Example:
app.post('/api/sms-listener', (req, res) => {
    console.log('SMS received:', req.body);
    console.log('Code:', req.body.sms_code);
    
    // Your logic here...
    
    res.json({
        success: true,
        message: 'SMS received successfully'
    });
});
🐍 Python/Flask Example:
from flask import Flask, request, jsonify

@app.route('/api/sms-listener', methods=['POST'])
def sms_webhook():
    data = request.json
    print('SMS received:', data)
    print('Code:', data.get('sms_code'))
    
    # Your logic here...
    
    return jsonify({
        'success': True,
        'message': 'SMS received successfully'
    })
🔒 Security Tips:
  • Always use HTTPS for webhook endpoints
  • Respond within 30 seconds to avoid timeout
  • Verify the source of incoming webhooks
  • Store SMS codes securely in your database

API Error Code Reference

✅ Success Codes:
CodeMeaning
200OK - Request successful
201Created - Resource created successfully
⚠️ Client Errors (4xx):
CodeMeaningSolution
400Bad RequestCheck request data
401UnauthorizedVerify API key is correct
404Not FoundCheck resource ID or endpoint URL
422Unprocessable EntityValidation failed - check parameters
429Too Many RequestsRate limit exceeded (60 requests/minute)
🔥 Server Errors (5xx):
CodeMeaning
500Internal Server Error - Server side issue
503Service Unavailable - Please try again later