API Documentation

RESTful API for IMEI database access with authentication and rate limiting.

Authentication

All API requests require authentication using an API key. To get an API key:

  1. Register for an account
  2. Verify your email address
  3. Generate your API key from your dashboard

Include your API key in the request header:

X-API-Key: your-api-key-here

Rate Limiting

API requests are limited to 100 requests per hour for all users by default. The limit can be configured per user in the database.

Each response includes the remaining calls in the response body.

Need more quota? Contact us at [email protected] to discuss increasing your rate limits.

Endpoints

1. IMEI Lookup

GET /api/v1/imei/{imei}

Look up device information by IMEI number.

Parameters:
  • imei (string, required): 15-digit IMEI number
Example Request:
curl -H "X-API-Key: your-api-key" \
  https://yoursite.com/api/v1/imei/123456789012345
Example Response:
{
  "imei": "123456789012345",
  "tac": "12345678",
  "manufacturer": "Apple",
  "model_name": "iPhone 12",
  "marketing_name": "iPhone 12",
  "brand_name": "Apple",
  "allocation_date": "2020-10-23",
  "device_type": "Smartphone",
  "operating_system": "iOS",
  "bluetooth": "Yes",
  "nfc": "Yes",
  "wlan": "Yes",
  "calls_remaining": 99
}
2. Generate IMEI

POST /api/v1/generate

Generate a random valid IMEI based on brand and model.

Request Body:
{
  "brand": "Apple",
  "model": "iPhone 12"
}
Example Request:
curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"brand":"Apple","model":"iPhone 12"}' \
  https://yoursite.com/api/v1/generate
Example Response:
{
  "imei": "123456789012345",
  "brand": "Apple",
  "model": "iPhone 12",
  "calls_remaining": 98
}
3. Get Brands

GET /api/v1/brands

Get list of available brands in the database.

Example Request:
curl -H "X-API-Key: your-api-key" \
  https://yoursite.com/api/v1/brands
Example Response:
{
  "brands": ["Apple", "Samsung", "Google", "OnePlus"],
  "calls_remaining": 97
}
4. Get Models by Brand

GET /api/v1/models/{brand}

Get list of available models for a specific brand.

Parameters:
  • brand (string, required): Brand name
Example Request:
curl -H "X-API-Key: your-api-key" \
  https://yoursite.com/api/v1/models/Apple
Example Response:
{
  "brand": "Apple",
  "models": ["iPhone 12", "iPhone 12 Pro", "iPhone 13", "iPhone 13 Pro"],
  "calls_remaining": 96
}

Error Responses

401 Unauthorized
{"error": "API key required"}
{"error": "Invalid API key"}
400 Bad Request
{"error": "Invalid IMEI format"}
{"error": "Brand and model are required"}
404 Not Found
{"error": "IMEI not found"}
429 Too Many Requests
{"error": "Rate limit exceeded"}

Code Examples

PHP Example
$api_key = 'your-api-key';
$imei = '123456789012345';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://yoursite.com/api/v1/imei/$imei");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: $api_key"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

print_r($data);
Python Example
import requests

api_key = 'your-api-key'
imei = '123456789012345'

headers = {'X-API-Key': api_key}
response = requests.get(f'https://yoursite.com/api/v1/imei/{imei}', headers=headers)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f'Error: {response.status_code}')
JavaScript Example
const apiKey = 'your-api-key';
const imei = '123456789012345';

fetch(`https://yoursite.com/api/v1/imei/${imei}`, {
    headers: {
        'X-API-Key': apiKey
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));