HR & Recruiting Fraud Prevention

class ReferenceVerifier {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://scamverify.ai/api/v1';
  }

  async callApi(endpoint, body) {
    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    });
    if (!response.ok) throw new Error(`API error: ${response.status}`);
    return response.json();
  }

  async verifyReference(reference) {
    const { name, title, company, phone, email } = reference;
    const findings = { phone: null, companyUrl: null, flags: [] };

    // Step 1: Verify the reference phone number
    const phoneCheck = await this.callApi('/phone/lookup', {
      phone_number: phone,
    });

    findings.phone = {
      riskScore: phoneCheck.risk_score,
      lineType: phoneCheck.signals.line_type,
      carrier: phoneCheck.signals.carrier,
      verdict: phoneCheck.verdict,
    };

    // Disposable VoIP for a "corporate reference" is a red flag
    if (phoneCheck.signals.line_type === 'voip') {
      findings.flags.push({
        severity: 'medium',
        signal: 'voip_reference_number',
        detail: `Reference phone is VoIP (${phoneCheck.signals.carrier}). Corporate references typically use landline or mobile numbers.`,
      });
    }

    if (phoneCheck.risk_score >= 40) {
      findings.flags.push({
        severity: 'high',
        signal: 'high_risk_reference_phone',
        detail: `Risk score ${phoneCheck.risk_score}/100. ${phoneCheck.explanation}`,
      });
    }

    if (phoneCheck.signals.ftc_complaints > 0) {
      findings.flags.push({
        severity: 'critical',
        signal: 'ftc_complaints_on_reference',
        detail: `${phoneCheck.signals.ftc_complaints} FTC complaint(s) filed against this number.`,
      });
    }

    // Step 2: If a company URL was provided, verify it
    if (company) {
      try {
        const companyUrl = `https://${company.toLowerCase().replace(/\s+/g, '')}.com`;
        const urlCheck = await this.callApi('/url/lookup', { url: companyUrl });

        findings.companyUrl = {
          url: companyUrl,
          riskScore: urlCheck.risk_score,
          verdict: urlCheck.verdict,
        };

        if (urlCheck.risk_score >= 30) {
          findings.flags.push({
            severity: 'medium',
            signal: 'suspicious_company_domain',
            detail: `Company domain flagged: ${urlCheck.explanation}`,
          });
        }
      } catch (e) {
        // Domain lookup failed, not necessarily suspicious
      }
    }

    // Determine overall assessment
    const hasCritical = findings.flags.some(f => f.severity === 'critical');
    const hasHigh = findings.flags.some(f => f.severity === 'high');

    findings.assessment = hasCritical
      ? 'REJECT'
      : hasHigh
        ? 'REQUIRES_MANUAL_VERIFICATION'
        : findings.flags.length > 0
          ? 'PROCEED_WITH_CAUTION'
          : 'VERIFIED';

    return findings;
  }

  async verifyAllReferences(references) {
    const results = [];

    for (const ref of references) {
      const result = await this.verifyReference(ref);
      results.push({ reference: ref, ...result });
    }

    const anyRejected = results.some(r => r.assessment === 'REJECT');
    const anyManualReview = results.some(
      r => r.assessment === 'REQUIRES_MANUAL_VERIFICATION'
    );

    return {
      overallAssessment: anyRejected
        ? 'REFERENCES_FAILED'
        : anyManualReview
          ? 'MANUAL_REVIEW_REQUIRED'
          : 'ALL_VERIFIED',
      references: results,
    };
  }
}

// Usage in your ATS integration
const verifier = new ReferenceVerifier(process.env.SCAMVERIFY_API_KEY);

app.post('/api/candidates/:id/verify-references', async (req, res) => {
  const { references } = req.body;

  const verification = await verifier.verifyAllReferences(references);

  // Store results in the ATS
  await updateCandidateRecord(req.params.id, {
    referenceVerification: verification,
    verifiedAt: new Date().toISOString(),
  });

  return res.json(verification);
});

import requests
import os

class ReferenceVerifier:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://scamverify.ai/api/v1"

    def _call_api(self, endpoint: str, body: dict) -> dict:
        response = requests.post(
            f"{self.base_url}{endpoint}",
            headers={
                "Authorization": f"Bearer {self.api_key}",
                "Content-Type": "application/json",
            },
            json=body,
        )
        response.raise_for_status()
        return response.json()

    def verify_reference(self, phone: str, company: str = None) -> dict:
        flags = []

        phone_check = self._call_api("/phone/lookup", {"phone_number": phone})

        if phone_check["signals"]["line_type"] == "voip":
            flags.append({
                "severity": "medium",
                "signal": "voip_reference_number",
                "detail": f"VoIP carrier: {phone_check['signals']['carrier']}",
            })

        if phone_check["risk_score"] >= 40:
            flags.append({
                "severity": "high",
                "signal": "high_risk_reference_phone",
                "detail": phone_check["explanation"],
            })

        if phone_check["signals"]["ftc_complaints"] > 0:
            flags.append({
                "severity": "critical",
                "signal": "ftc_complaints_on_reference",
                "detail": f"{phone_check['signals']['ftc_complaints']} FTC complaints",
            })

        has_critical = any(f["severity"] == "critical" for f in flags)
        has_high = any(f["severity"] == "high" for f in flags)

        assessment = (
            "REJECT" if has_critical
            else "REQUIRES_MANUAL_VERIFICATION" if has_high
            else "PROCEED_WITH_CAUTION" if flags
            else "VERIFIED"
        )

        return {
            "phone_risk_score": phone_check["risk_score"],
            "line_type": phone_check["signals"]["line_type"],
            "flags": flags,
            "assessment": assessment,
        }