StalkPhish API

Full Documentation - v1.5

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 50/day 4 hours 30 URL, IP
Starter 150/day 3 days 35 + Title
Researcher 300/day 14 days 50 + Email extraction
Standard 1000/day 30 days 100 Full metadata
Professional 5000/day 180 days 200 + Brand, Favicon, Zip hash, Telegram

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": "Professional", "subscription_status": "active", "daily_api_limit": 5000, "api_requests_today": 342, "api_requests_remaining": 4658, "features": { "url_search": true, "title_search": true, "telegram_search": true } }

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": "2025-12-03T10:30:00Z", "firstseencode": "200", "ipaddress": "192.168.1.100", "asn": "AS12345", "asndesc": "Example ISP", "asnreg": "ARIN" }]

API Responses

Response data varies by subscription level:

Free Tier Response

{ "siteurl": "https://fake-site.com", "sitedomain": "fake-site.com", "pagetitle": "Login Page", "firstseentime": "2025-12-03T10:30:00Z", "firstseencode": "200", "ipaddress": "192.168.1.1", "asn": "AS12345", "asndesc": "Example ISP", "asnreg": "ARIN" }

Standard Tier Response

{ // Free fields + "lastseentime": "2025-12-03T15:30:00Z", "lastseencode": "200", "extracted_emails": "admin@fake-site.com", "GoogleSafebrowsing": "malware", "phishing_score": 85, "page_hash": "sha256hashvalue", "zipfilename": "phishing_kit.zip", "zipfilehash": "abc123def456" }

Professional Tier Response

{ // Standard fields + "extracted_telegram": "@scam_support_bot", "phishingkit_family": "Generic", "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 or invalid token

403 - Forbidden

Access denied - insufficient subscription level

429 - Too Many Requests

Rate limit exceeded - wait before retry

500 - Internal Server Error

Server error occurred

Error Response Format

{ "error": "You don't have access to this search option with the plan you subscribed to.", "required_plan": "Professional or higher" }

Security

Best Practices

Token Protection: Never expose your token in client-side code, version control, or logs. Always use HTTPS for API requests.
Rate Limiting: Implement exponential backoff when encountering 429 errors. Monitor your daily usage through the /me endpoint.

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 ) # Telegram search with filters params = { 'last_days': 30 } response = requests.get( f'{base_url}/search/telegram/support_bot', headers=headers, params=params ) data = response.json() for entry in data: print(f"URL: {entry['siteurl']}") print(f"Telegram: {entry.get('extracted_telegram', 'N/A')}")

JavaScript/Node.js

const axios = require('axios'); const api = axios.create({ baseURL: 'https://api.stalkphish.io/api/v1', headers: {'Authorization': 'Token YOUR_TOKEN'} }); // Telegram search async function searchTelegram() { try { const response = await api.get('/search/telegram/scam_bot', { 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/telegram?last_days=30" search_api "/search/telegram/support_bot"

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 in the /me endpoint.

Q: The API returns 403 errors

Verify your token is valid and you have the required subscription level for the endpoint used.

Q: What's the difference between /search/telegram and /search/telegram/{term}?

Without parameter, it returns all entries with Telegram data. With parameter, it searches for specific strings.

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
Starter Allowed 3 days
Researcher Allowed 14 days
Standard Allowed 30 days
Professional 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=2025-01-01&to_date=2025-01-31 ?from_date=2025-01-01 10:30:00&to_date=2025-01-31 23:59:59 # Relative periods ?last_days=7 # Last 7 days ?last_hours=48 # Last 48 hours

Rate Limit Management

import time import requests 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")