Public API Documentation

Access public SIM cards and messages programmatically. No authentication required. Perfect for developers building integrations and automation tools.

No Authentication
RESTful API
JSON Responses

Quick Start

Base URL for all API requests

https://www.otpocket.app/api/public

All endpoints are prefixed with this base URL. No API key or authentication is required.

List Public SIMs

Get a list of all available public SIM cards with their status and carrier information.

GET

Endpoint

https://www.otpocket.app/api/public/sims

Query Parameters

status

Filter by status: active, idle, or offline

carrier

Filter by carrier name (partial match)

limit

Number of results (default: 100, max: 500)

offset

Pagination offset (default: 0)

Example Request

curl "https://www.otpocket.app/api/public/sims?status=active&limit=50"

Example Response

{
  "success": true,
  "data": [
    {
      "number": "+639123456789",
      "carrier": "Smart",
      "status": "active",
      "device_id": "device-123",
      "device_name": "Device 1"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 150,
    "has_more": true
  }
}

Code Examples

Ready-to-use code snippets in different programming languages

// List all active public SIMs
const response = await fetch('https://www.otpocket.app/api/public/sims?status=active');
const data = await response.json();
console.log(data.data);

// Get messages for a specific SIM
const messages = await fetch('https://www.otpocket.app/api/public/sims/09123456789/messages');
const messagesData = await messages.json();
console.log(messagesData.data);

Error Handling

All endpoints return errors in a consistent format

Error Response Format

{
  "success": false,
  "error": "Error type",
  "message": "Detailed error message"
}

HTTP Status Codes

200
Success
400
Bad Request (invalid parameters)
404
Not Found (SIM not found)
500
Internal Server Error
429
Too Many Requests (rate limit exceeded)
503
Service Unavailable (health check only)

Rate Limiting

All endpoints are rate limited to ensure fair usage

Rate Limit Policy

  • Dynamic rate limits - Configurable per endpoint via database
  • Default: 10 requests per minute per IP address
  • Rate limits are enforced per IP address
  • When exceeded, you'll receive a 429 Too Many Requests response
  • Rate limits can be adjusted dynamically without code changes

Note: Rate limits are stored in the database and can be adjusted by administrators. Different endpoints may have different limits. Check the response headers for current limits.

Rate Limit Headers

Every response includes rate limit information in headers:

X-RateLimit-Limit
Maximum number of requests allowed (varies by endpoint, check headers for current limit)
X-RateLimit-Remaining
Number of requests remaining in current window
X-RateLimit-Reset
ISO timestamp when the rate limit resets
Retry-After
Seconds to wait before retrying (only in 429 responses)

Example: Rate Limit Exceeded Response

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Rate limit exceeded. Maximum 10 requests per minute. Please try again later.",
  "retry_after": 45
}

HTTP Status: 429 Too Many Requests

Handling Rate Limits

When you receive a 429 response, implement exponential backoff retry logic:

// Example: Fetch with exponential backoff
async function fetchWithRetry(url, maxRetries = 3) {
  let delay = 1000; // Start with 1 second
  
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url);
    
    if (response.status !== 429) {
      return response; // Success or other error
    }
    
    if (attempt === maxRetries) {
      return response; // Return 429 on last attempt
    }
    
    // Get Retry-After header or use exponential backoff
    const retryAfter = response.headers.get('Retry-After');
    const waitTime = retryAfter 
      ? parseInt(retryAfter) * 1000 
      : Math.min(delay * 2, 30000); // Max 30 seconds
    
    console.log(`Rate limited. Retrying after ${waitTime}ms...`);
    await new Promise(resolve => setTimeout(resolve, waitTime));
    delay = waitTime;
  }
}

// Usage
const response = await fetchWithRetry('https://www.otpocket.app/api/public/sims');
const data = await response.json();

Important Notes

  • All timestamps are in ISO 8601 format (UTC)
  • Phone numbers can be provided in any format; the API will extract the last 10 digits
  • Only public SIMs are accessible through this API
  • Messages are returned in reverse chronological order (newest first)
  • This API is read-only; no operations can modify data
  • Rate limits are dynamically configurable via database (default: 10 requests/minute)

Need Help?

Have questions or need assistance with the API?

Contact SupportHelp CenterView Public SIMs