Screen a lead in one request.

Overview

The LeadFilter API is a screening layer for inbound leads. You send the raw message text (plus any context you have), and LeadFilter responds with a score, a verdict, a short reason, and matched categories.

LeadFilter is conservative by design. It estimates how spam-like a message is — it does not decide whether a lead is valuable, and it never deletes anything. You stay in control of what happens to each result.

• One JSON endpoint, one predictable response shape.
• Every result includes a request_id for auditing, support, and debugging.
• Works with contact forms, CRM webhooks, automations, and internal tools.

Quick start

Create an account, add your business context, generate an API key, then send your first lead. Here's a complete request and response:

# Analyze an inbound lead
curl https://api.leadfilter.zsetup.com/v1/leads/analyze \
  -H "content-type: application/json" \
  -H "x-api-key: $LEADFILTER_API_KEY" \
  -d '{
    "lead": {
      "text": "Boost your DA with 5,000 backlinks...",
      "email": "sales@example.com",
      "company": "Example Growth",
      "source": "website_form",
      "country": "US"
    },
    "external_id": "crm_12345"
  }'

// 200 OK
{
  "request_id": "lfreq_...",
  "score": 94,
  "verdict": "likely_spam",
  "confidence": 0.92,
  "reason": "This message appears to be an SEO outreach pitch.",
  "categories": ["seo_pitch", "link_building"],
  "processed_at": "2026-05-30T20:00:00.000Z"
}

Authentication

Authenticate every request with an API key in the x-api-key header. Create and manage keys from your dashboard — when you generate a key, the full secret is shown once, so copy it then.

x-api-key: lfai_live_••••••••••••••••

Analyze a lead

Submit an inbound message for screening. The only required field is lead.text; everything else is optional context that can sharpen the result. A successful call returns 200 OK with the screening result.

Request fields

Response fields

Understanding verdicts

Every result maps to one of three verdicts. They describe how spam-like a message is — not whether it's a good fit for your business.

Understanding the score

The score is a spam-likelihood estimate from 0 to 100. A 100 means very likely spam, fake, irrelevant, or non-actionable; lower scores look more like genuine inquiries.

Thresholds for each verdict are configurable per account, so you decide where needs_review begins and ends. A low-confidence result can intentionally become needs_review even when the score sits mid-range.

Error responses

Errors return a non-2xx status and a consistent JSON shape. The request_id is always included so you can trace any failure. A service_unavailable response means screening is temporarily down — it never implies the submitted lead is legitimate, so hold and retry rather than letting it through. For Analyze, provider failures currently fall back to a conservative deterministic classifier and return a valid 200; provider_unavailable is reserved.

// 400 Bad Request
{
  "error": {
    "code": "validation_failed",
    "message": "Lead text is required.",
    "request_id": "lfreq_..."
  }
}

This is the stable public error-code vocabulary. Reserved codes remain part of that vocabulary even when the Analyze endpoint currently handles the condition through a successful fallback response.

Integration guidance

Call LeadFilter wherever a lead enters your world. A common pattern is to screen on form submission or CRM webhook, then branch on the verdict.

• Route likely_legit straight into your pipeline.
• Send needs_review to a queue for a human to confirm.
• Hold or tag likely_spam — keep the audit trail either way.

Store the request_id with your lead record so any result can be looked up later in your dashboard logs.