Stop Fake Accounts with Real-Time Detection APIs

// Store the key outside your code (e.g. an environment variable or a .env file)
$apiKey = getenv('APIVOID_API_KEY');

if ($apiKey === false || $apiKey === '') {
    throw new RuntimeException('APIVOID_API_KEY is not set.');
}

define('APIVOID_API_KEY', $apiKey);

// Behind a proxy or CDN, REMOTE_ADDR is the proxy's IP, not the user's.
// Use your proxy's forwarded-IP header instead, and only trust it if your
// proxy overwrites it, since clients can spoof X-Forwarded-For.
$ip = $_SERVER['REMOTE_ADDR'];
$email = $_POST['email'] ?? '';

// Validate the email syntax before checking it with the API.
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
    // Block the action with a message like "Email syntax is not valid".
    // Must stop here: the domain extraction below assumes a valid address
}

// NOTE: These checks are independent and run sequentially here to keep the
// example readable. In production you can run them in parallel with
// curl_multi_* to reduce the total signup latency.

// Check the user IP address reputation
$ipReputation = makeAPIVoidRequestV2('/v2/ip-reputation', ['ip' => $ip]);

if (is_array($ipReputation)) {
    // What to do if the IP is detected only by 1 or 2 blacklists?
    // These may not be definitive indicators of malicious activity but can still suggest potential risk.
    // For example, you might choose to apply additional verification steps,
    // such as prompting the user for SMS-based phone number verification,
    // or requesting business details like company name and intended use case.
    if (in_array($ipReputation['blacklists']['detections'] ?? 0, [1, 2], true)) {
        // Apply your verification logic here (e.g., SMS, email challenge, or business form)
    }
    
    // Block the IP address if it is detected by 3 or more blacklists.
    // A higher number of detections reduces the likelihood of a false positive.
    if (($ipReputation['blacklists']['detections'] ?? 0) >= 3) {
        // Block the action with a message like "Your IP is detected by 3 or more blacklists".
    }
    
    // How to properly handle IPs detected as VPN?
    // Depending on your SaaS type (e.g., financial services), you may choose to block VPN users entirely.
    // Alternatively, you can allow them but flag their session as VPN-based,
    // and optionally restrict certain features, such as limiting access to a free trial plan.
    if (($ipReputation['anonymity']['is_vpn'] ?? false) === true) {
        // Apply your custom logic here (e.g., block, flag, or restrict features)
    }
    
    // How should hosting or data center IPs be handled?
    // These IPs may indicate automated signups, bots, or anonymous activity,
    // but they are not always inherently malicious and can belong to legitimate users.
    // A common approach is to allow these users conditionally by enforcing additional verification,
    // such as requiring SMS-based phone verification or collecting company and use case details.
    if (($ipReputation['anonymity']['is_hosting'] ?? false) === true) {
        // Apply your verification logic here (e.g., SMS challenge or business info form)
    }
    
    // Block IP addresses identified as public proxies or Tor traffic.
    // These sources are commonly used to mask identity and bypass access controls.
    if (($ipReputation['anonymity']['is_proxy'] ?? false) === true || 
        ($ipReputation['anonymity']['is_tor'] ?? false) === true) {
        // Block the action with a message like "Your IP is detected as proxy or Tor".
    }
    
    // Block IP addresses identified as residential proxies.
    // These sources are commonly used to mask identity and bypass access controls.
    // However, since residential IPs can be reassigned, a legitimate user may later
    // inherit an IP previously flagged as a proxy. In such cases, consider applying
    // additional verification rather than outright blocking.
    if (($ipReputation['anonymity']['is_residential_proxy'] ?? false) === true) {
        // Apply your verification logic here (e.g., SMS challenge or business info form)
    }
    
    // Do you need to restrict access from specific countries?
    // For example, you may choose to block IP addresses originating from certain locations.
    if (in_array($ipReputation['information']['country_code'] ?? '', ['IT', 'NL'], true)) {
        // Block the action with a message like "Your IP is located in a blocked country".
    }
}

// Check the user email address reputation
$emailReputation = makeAPIVoidRequestV2('/v2/email-verify', ['email' => $email]);

if (is_array($emailReputation)) {
    // Use the should_block flag to block the email.
    // APIVoid provides this field so you can quickly decide without
    // evaluating the other JSON fields yourself. It is computed by a
    // weighted algorithm that analyzes them. If you use this flag, then
    // you don't need the other email checks below.
    if (($emailReputation['should_block'] ?? false) === true) {
        // Block the action with a message like "Email is blocked by APIVoid security check".
    }
    
    // Block suspicious and disposable email addresses.
    // These are often used for temporary access or to avoid verification,
    // and may indicate fraudulent intent or attempts to abuse trial-based features.
    if (($emailReputation['suspicious_email'] ?? false) === true || 
        ($emailReputation['suspicious_domain'] ?? false) === true || 
        ($emailReputation['disposable'] ?? false) === true) {
        // Block the action with a message like "Email is classified as suspicious".
    }
    
    // Do you allow signups with free email addresses on your SaaS?
    // If your service targets only businesses, you may choose to block common free email providers.
    // This helps maintain a cleaner, business-focused user base as intended.
    if (($emailReputation['free_email'] ?? false) === true) {
        // Block the action with a message like "Free email addresses are not allowed".
    }
    
    // Should you block email domains with risky TLD like .top?
    // This approach can reduce signups from suspicious or less common domain sources,
    // but it may also result in false positives, affecting legitimate users.
    if (($emailReputation['risky_tld'] ?? false) === true) {
        // Block the action with a message like "Domain TLD is classified as risky".
        // Alternatively, prompt the user for SMS verification or business info form
    }
    
    // Block emails with no MX records configured.
    // A missing MX record indicates the domain cannot receive emails, 
    // which is often a sign of a fake or misconfigured address.
    // Default to true so a missing field doesn't block a legitimate user.
    if (($emailReputation['has_mx_records'] ?? true) === false) {
        // Block the action with a message like "Email domain cannot receive emails".
    }
}

$emailDomain = substr(strrchr($email, '@'), 1);

// Check domain age of email domain
$domainAge = makeAPIVoidRequestV2('/v2/domain-age', ['host' => $emailDomain]);

if (is_array($domainAge)) {
    // Block email addresses from domains registered less than 30 days ago.
    // Recently created domains are often linked to suspicious or disposable email activity.
    // A value of 0 means the domain age is unknown. Allow it rather than risk a false positive.
    if (($domainAge['domain_age_in_days'] ?? 0) > 0 && ($domainAge['domain_age_in_days'] ?? 0) <= 30) {
        // Block the action with a message like "Email domain is too new".
    }
}

// Check if email domain is parked
$parkedDomain = makeAPIVoidRequestV2('/v2/parked-domain', ['host' => $emailDomain]);

if (is_array($parkedDomain)) {
    // Block email addresses if domain is a parked or inactive domain
    if (($parkedDomain['parked_domain'] ?? false) === true) {
        // Block the action with a message like "Email domain is parked".
    }
}

// Simple function to query APIVoid v2 endpoints
// To add a retry for 429 and 5xx errors, see: https://docs.apivoid.com/errors/
// Returns null in case of errors. The checks will then be skipped.
function makeAPIVoidRequestV2(string $endpoint, array $payload, int $timeout = 30): ?array
{
    $curl = curl_init('https://api.apivoid.com' . $endpoint);

    curl_setopt_array($curl, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($payload),
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'X-API-Key: ' . APIVOID_API_KEY,
        ],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT        => $timeout,
    ]);

    $body     = curl_exec($curl);
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    $curlErr  = curl_error($curl);
    curl_close($curl);

    // Connection failed, DNS error or timeout: nothing was returned
    if ($body === false) {
        error_log("APIVoid {$endpoint} connection error: {$curlErr}");
        return null;
    }

    $data = json_decode($body, true);

    // Anything other than 200 is an error; the body carries an "error" field
    if ($httpCode !== 200 || !is_array($data)) {
        error_log("APIVoid {$endpoint} returned {$httpCode}: " . ($data['error'] ?? $body));
        return null;
    }

    return $data;
}