Overview
The StalkPhish API provides secure access to phishing data with advanced search capabilities, temporal filters, and multi-layered protection against attacks. Our comprehensive database helps organizations detect and respond to phishing threats, brand impersonation, and fraud campaigns.
Base URL
https://api.stalkphish.io/api/v1/
Authentication
All API requests must include your API token in the Authorization header:
Authorization: Token YOUR_API_TOKEN
Important: Your API token must be included in the Authorization header of every request. Keep your token secure and never expose it in client-side code.
Subscription Levels and Limits
| Level | Rate Limit | Time Range | Max Results | Features |
|---|---|---|---|---|
| Free | 10/day | 4 hours | 30 | URL, IP |
| Standard | 200/day | 30 days | 100 | + Title, Email extraction |
| Pro | 1000/day | 180 days | 200 | + Brand, Favicon, Zip hash |
Endpoints
1. User Information
GET /me
Returns information about the authenticated user account.
curl -H "Authorization: Token YOUR_TOKEN" \
https://api.stalkphish.io/api/v1/me
[{
"username": "john_doe",
"email": "john@example.com",
"api_key": "67ac1298...8ae5",
"subscribed_plan": "Pro"
}]
2. Latest Phishing URLs
GET /last
Returns the latest phishing URLs according to your subscription level.
curl -H "Authorization: Token YOUR_TOKEN" \
https://api.stalkphish.io/api/v1/last
[{
"siteurl": "https://fake-paypal.com",
"sitedomain": "fake-paypal.com",
"pagetitle": "PayPal Login",
"firstseentime": "2024-07-31T10:30:00Z",
"firstseencode": "200",
"ipaddress": "192.168.1.100",
"asn": "AS12345",
"asndesc": "Example ISP",
"asnreg": "ARIN"
}]
Advanced Search
3. URL Search
GET /search/url/{search_term}
Search within phishing site URLs with support for boolean operators.
Search Parameters:
- Simple search: paypal
- Boolean operators: paypal AND login, microsoft OR apple, paypal NOT legitimate
Temporal Parameters:
- from_date - YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format
- to_date - YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format
- last_days - Integer (last X days)
- last_hours - Integer (last X hours)
# Simple search
curl -H "Authorization: Token YOUR_TOKEN" \
"https://api.stalkphish.io/api/v1/search/url/paypal"
# Boolean search with dates
curl -H "Authorization: Token YOUR_TOKEN" \
"https://api.stalkphish.io/api/v1/search/url/paypal%20AND%20login?from_date=2024-07-01&to_date=2024-07-31"
# Search last 7 days
curl -H "Authorization: Token YOUR_TOKEN" \
"https://api.stalkphish.io/api/v1/search/url/microsoft?last_days=7"
4. IP Address Search
GET /search/ipv4/{ip_address}
Search by exact IPv4 address (format: 192.168.1.1).
curl -H "Authorization: Token YOUR_TOKEN" \
"https://api.stalkphish.io/api/v1/search/ipv4/192.168.1.1?last_days=30"
5. Page Title Search Standard+
GET /search/title/{search_term}
Search within phishing page titles. Available for Standard and Pro subscriptions.
# Simple search
curl -H "Authorization: Token YOUR_TOKEN" \
"https://api.stalkphish.io/api/v1/search/title/Login"
# Boolean search
curl -H "Authorization: Token YOUR_TOKEN" \
"https://api.stalkphish.io/api/v1/search/title/PayPal%20AND%20Secure"
6. Email Search Pro+
GET /search/email/{search_term}
Search within emails extracted from phishing pages. Available for Pro subscriptions.
7. Brand Search Pro+
GET /search/brand/{brand_name}
Search by targeted brand or company. Available for Pro subscriptions.
8. Favicon Hash Search Pro+
GET /search/favicon/{hash}
Search by MMH3 favicon hash (integer format, positive or negative).
9. ZIP File Hash Search Pro+
GET /search/zipfilehash/{hash}
Search by phishing kit hashes (MD5, SHA1, or SHA256 format).
API Responses
Response data varies by subscription level:
Free Tier Response
{
"siteurl": "https://fake-site.com",
"sitedomain": "fake-site.com",
"pagetitle": "Login Page",
"firstseentime": "2024-07-31T10:30:00Z",
"firstseencode": "200",
"ipaddress": "192.168.1.1",
"asn": "AS12345",
"asndesc": "Example ISP",
"asnreg": "ARIN"
}
Standard Tier Response
{
// Free fields +
"extracted_emails": "admin@fake-site.com",
"GoogleSafebrowsing": "malware",
"phishing_score": 85,
"certificate": [{
"issuer": "Let's Encrypt",
"commonName": "fake-site.com"
}]
}
Pro Tier Response
{
// Standard fields +
"extracted_telegram": [{
"botID": "123456789",
"channelID": "987654321"
}],
"zipfilename": "phishing_kit.zip",
"zipfilehash": "abc123def456",
"phishingkit_family": "Generic",
"page_hash": "sha256hash",
"favicon_mmh3": -1601194732,
"targeted_brand": "PayPal"
}
Error Handling
HTTP Status Codes
200 - Success
Request completed successfully
400 - Bad Request
Invalid parameters provided
401 - Unauthorized
Authentication required
403 - Forbidden
Access denied for this resource
429 - Too Many Requests
Rate limit exceeded
500 - Internal Server Error
Server error occurred
Error Response Format
{
"error": "Invalid request parameters",
"error_code": "validation"
}
Security
Best Practices
Token Protection: Never expose your token in client-side code and always use HTTPS.
Code Examples
Python with requests
import requests
headers = {'Authorization': 'Token YOUR_TOKEN'}
base_url = 'https://api.stalkphish.io/api/v1'
# Simple search
response = requests.get(
f'{base_url}/search/url/paypal',
headers=headers
)
# Search with filters
params = {
'from_date': '2024-07-01',
'to_date': '2024-07-31'
}
response = requests.get(
f'{base_url}/search/brand/paypal AND login',
headers=headers,
params=params
)
data = response.json()
JavaScript/Node.js
const axios = require('axios');
const api = axios.create({
baseURL: 'https://api.stalkphish.io/api/v1',
headers: {'Authorization': 'Token YOUR_TOKEN'}
});
// Boolean search
async function searchPhishing() {
try {
const response = await api.get('/search/url/paypal OR microsoft', {
params: {
last_days: 7
}
});
console.log(response.data);
} catch (error) {
console.error('Error:', error.response.data);
}
}
cURL
#!/bin/bash
TOKEN="YOUR_TOKEN"
BASE_URL="https://api.stalkphish.io/api/v1"
# Search function
search_api() {
curl -H "Authorization: Token $TOKEN" \
-H "Accept: application/json" \
"$BASE_URL$1"
}
# Usage examples
search_api "/last"
search_api "/search/url/paypal?last_days=7"
search_api "/search/brand/microsoft%20OR%20apple?from_date=2024-07-01"
FAQ and Troubleshooting
Frequently Asked Questions
Q: Why aren't my boolean searches working?
Check the operator syntax (AND, OR, NOT in uppercase) and URL encoding of spaces (%20).
Q: How do I handle rate limits?
Implement a retry system with exponential backoff and monitor response headers.
Q: My custom dates are ignored
Free users cannot use custom dates. Check your subscription level.
Q: The API returns 403 errors
Verify your token is valid and you have permissions for the endpoint used.
Boolean Operators
Supported Syntax:
- AND: Both terms must be present
- OR: Either term can be present
- NOT: Exclude the following term
Combination Rules:
- Maximum 5 operators per query
- Maximum 10 search terms
- Maximum length: 200 characters
- Maximum term length: 50 characters
Usage Examples:
# AND search
"paypal AND login"
# OR search
"microsoft OR apple OR google"
# Exclusion
"banking NOT legitimate"
# Complex combinations
"(paypal OR visa) AND login NOT secure"
Temporal Filters
| Level | Custom Range | Maximum Range |
|---|---|---|
| Free | Not allowed | 4 hours fixed |
| Standard | Allowed | 30 days |
| Pro | Allowed | 180 days |
Date Validation:
- Accepted format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
- Allowed range: 2 years in the past to 1 day in the future
- Maximum range: according to subscription level
Available Parameters:
# Absolute dates
?from_date=2024-07-01&to_date=2024-07-31
?from_date=2024-07-01 10:30:00&to_date=2024-07-31 23:59:59
# Relative periods
?last_days=7 # Last 7 days
?last_hours=48 # Last 48 hours
Debugging Tips
- Enable detailed logging in your application
- Check response headers for rate limit information
- Test with simple requests first before complex queries
- Verify URL parameter encoding (spaces should be %20)
- Use tools like Postman or curl for testing
Rate Limit Management
import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
def create_session_with_retries():
session = requests.Session()
retry_strategy = Retry(
total=3,
status_forcelist=[429, 500, 502, 503, 504],
backoff_factor=1
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("http://", adapter)
session.mount("https://", adapter)
return session
# Usage
session = create_session_with_retries()
headers = {'Authorization': 'Token YOUR_TOKEN'}
response = session.get(
'https://api.stalkphish.io/api/v1/search/url/paypal',
headers=headers
)
Handling Rate Limits
def make_api_request(url, headers, params=None, max_retries=3):
"""Make API request with automatic rate limit handling"""
for attempt in range(max_retries):
response = requests.get(url, headers=headers, params=params)
if response.status_code == 429:
# Rate limited, wait before retry
retry_after = int(response.headers.get('Retry-After', 60))
print(f"Rate limited. Waiting {retry_after} seconds...")
time.sleep(retry_after)
continue
return response
raise Exception("Max retries exceeded")