Phisherman Getting Started: API Key & First Lookup (2026)

Getting started overview

Getting started with Phisherman involves a sequence of steps designed to quickly enable real-time phishing URL detection within your applications. The process begins with account creation, followed by obtaining the necessary API credentials. Once authenticated, you can proceed to make your initial API request to check a URL's status. Phisherman is frequently used by Discord bot developers for automated moderation and security tasks.

This guide provides a structured approach to integrate Phisherman, focusing on the essential steps from signup to a successful API call. The Phisherman API is designed for straightforward integration, offering a free tier that supports up to 100 API lookups per minute and 100,000 lookups per month, suitable for initial development and smaller projects.

Here's a quick reference table outlining the getting started process:

Create an account and get keys

To access the Phisherman API, you must first create an account and obtain an API key. This key is essential for authenticating your requests and associating them with your usage limits and plan.

Account Creation:

1. Navigate to the Phisherman registration page.
2. Provide the required information, typically an email address and a password.
3. Complete any verification steps, such as email confirmation, as prompted.

Upon successful registration, you will gain access to your Phisherman dashboard.

Obtaining Your API Key:

1. Log in to your newly created Phisherman account.
2. Locate the section dedicated to API keys or developer settings within your dashboard. The exact navigation may vary but is generally clearly labeled, often under a "Settings" or "API" tab. Refer to the Phisherman authentication documentation for specific instructions.
3. Generate a new API key if one is not automatically provided.
4. Copy your API key. It is crucial to treat this key as sensitive information, similar to a password, to prevent unauthorized access to your API usage.

The API key is a unique string that identifies your application when making requests to the Phisherman API. It will be included in the Authorization header of your HTTP requests.

Your first request

With your API key in hand, you are ready to make your first request to the Phisherman API. The primary endpoint for checking a URL is a GET request to /v2/domains/check/{domain}. This endpoint allows you to query the status of a specific domain.

The API expects your API key in the Authorization header, prefixed with Bearer.

Example using cURL:

cURL is a command-line tool and library for transferring data with URLs, commonly used for testing API endpoints. This example demonstrates how to check the domain example.com.

curl -X GET \
  'https://api.phisherman.gg/v2/domains/check/example.com' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Replace YOUR_API_KEY with the actual API key you obtained from your Phisherman dashboard.

Example using Node.js (with node-fetch):

For Node.js developers, using a library like node-fetch (or the built-in fetch API in newer versions) is a common approach.

const fetch = require('node-fetch'); // If using Node.js < 18

const apiKey = 'YOUR_API_KEY';
const domainToCheck = 'example.com';

async function checkDomain() {
  try {
    const response = await fetch(`https://api.phisherman.gg/v2/domains/check/${domainToCheck}`,
      {
        method: 'GET',
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json'
        }
      }
    );

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Phisherman API Response:', data);
  } catch (error) {
    console.error('Error checking domain:', error);
  }
}

checkDomain();

Remember to install node-fetch if you are running an older Node.js version: npm install node-fetch@2 (for Node.js < 18). New Node.js versions have fetch built-in, so the require line would not be needed.

Example using Python (with requests):

Python developers can use the popular requests library for making HTTP requests.

import requests

api_key = 'YOUR_API_KEY'
domain_to_check = 'example.com'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

try:
    response = requests.get(f'https://api.phisherman.gg/v2/domains/check/{domain_to_check}', headers=headers)
    response.raise_for_status()  # Raise an exception for HTTP errors (4xx or 5xx)
    data = response.json()
    print('Phisherman API Response:', data)
except requests.exceptions.HTTPError as http_err:
    print(f'HTTP error occurred: {http_err}')
except Exception as err:
    print(f'Other error occurred: {err}')

Ensure you have the requests library installed: pip install requests.

Expected Response Structure:

A successful response from the /v2/domains/check/{domain} endpoint will typically return a JSON object indicating the domain's status. For example:

{
  "message": "Domain is not tracked by Phisherman or is not phishing.",
  "status": 200,
  "classification": "safe",
  "verified": false,
  "info": {
    "domain": "example.com",
    "scheme": "https",
    "full_url": "https://example.com/"
  }
}

A phishing domain would return a classification of phishing and verified: true, along with additional details if available.

Common next steps

After successfully making your first API call, consider these common next steps to further integrate Phisherman into your application:

• Implement Error Handling: Robust applications should handle various API responses, including rate limits (HTTP 429), authentication errors (HTTP 401), and server errors (HTTP 5xx). The Phisherman API documentation on response codes provides detailed information.
• Explore Other Endpoints: Phisherman offers additional endpoints for reporting phishing links, fetching statistics, or managing whitelisted domains. Review the full API reference to discover more functionality.
• Utilize Official SDKs: For a more streamlined development experience, consider using one of the official Phisherman SDKs for Node.js, Python, or Go. These SDKs often abstract away HTTP request details and provide language-specific interfaces.
• Monitor Usage: Keep an eye on your API usage through your Phisherman dashboard to ensure you stay within your plan's limits, especially if you are on the free tier.
• Integrate with a Webhook: For real-time updates and proactive detection, Phisherman can integrate with webhooks to push notifications about new phishing detections directly to your application or moderation system.
• Secure Your API Key: Ensure your API key is stored securely and not exposed in client-side code or public repositories. Environment variables or secure configuration management are recommended practices. For more general secure API key practices, consult resources like Google Cloud's API key security guidelines.

Troubleshooting the first call

If your first API call to Phisherman doesn't return the expected result, consider these common troubleshooting steps:

• Check API Key: Double-check that your API key is correct and has not expired. Ensure there are no leading or trailing spaces.
• Authorization Header Format: Verify that the Authorization header is correctly formatted as Bearer YOUR_API_KEY. A common mistake is omitting "Bearer " or using an incorrect case.
• Network Connectivity: Confirm that your development environment has internet access and can reach api.phisherman.gg.
• URL Encoding: If the domain or URL you are checking contains special characters, ensure it is properly URL-encoded.
• Rate Limiting (HTTP 429): If you receive an HTTP 429 status code, you have exceeded your plan's rate limit. Wait a few moments before retrying or consider upgrading your plan if sustained higher usage is necessary.
• Invalid Domain (HTTP 400): A 400 Bad Request error typically indicates an issue with the domain provided in the URL path. Ensure it is a valid domain format.
• Server Errors (HTTP 5xx): If you encounter an HTTP 5xx error, it indicates an issue on the Phisherman server side. These are usually temporary; try again after a short period. Check the Phisherman Discord server or their official channels for status updates.
• Consult Documentation: The Phisherman API reference and response codes guide are comprehensive resources for understanding expected behavior and error messages.