API Reference

Overview

LeadFlags scores inbound leads with predefined quality criteria and returns a numeric score, quality level, risk flags, positive signals, and a recommended action.

Use LeadFlags before CRM ingestion to filter low-quality leads, reduce wasted calls, and focus your team on leads that convert.

Try in Postman — import the collection and run requests from Postman.

Base URL

All API requests use this base:

Example: POST https://leadflags.com/api/score-lead/

Endpoint

POST /api/score-lead

Accepts a JSON body with lead data. No required fields; send only what you have.

Headers (required)

Body

Arbitrary JSON object—no fixed schema. We detect scoring fields by key aliases (case-insensitive, - and _ treated the same). Unknown keys are stored as metadata and not used for scoring.

{
  "contactEmail": "user@example.com",
  "tel": "+34987654321",
  "_leadflags_map": {
    "contactEmail": "email",
    "tel": "phone"
  }
}

Request examples

All examples send the same JSON body and require X-API-Key. Replace YOUR_API_KEY with your key.

curl -X POST "https://leadflags.com/api/score-lead/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"name":"Alex","email":"alex@fastgrowth-labs.co","phone":"+44 7700 900123","company":"FastGrowth Labs","job_title":"Consultant","industry":"Growth Consulting","company_size":"1-10","country":"UK","source":"facebook_ads","message":"Hi, looking for more info."}'

fetch("https://leadflags.com/api/score-lead/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    name: "Alex",
    email: "alex@fastgrowth-labs.co",
    phone: "+44 7700 900123",
    company: "FastGrowth Labs",
    job_title: "Consultant",
    industry: "Growth Consulting",
    company_size: "1-10",
    country: "UK",
    source: "facebook_ads",
    message: "Hi, looking for more info."
  })
})
  .then(res => res.json())
  .then(data => console.log(data));

$ch = curl_init("https://leadflags.com/api/score-lead/");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Alex',
    'email' => 'alex@fastgrowth-labs.co',
    'phone' => '+44 7700 900123',
    'company' => 'FastGrowth Labs',
    'job_title' => 'Consultant',
    'industry' => 'Growth Consulting',
    'company_size' => '1-10',
    'country' => 'UK',
    'source' => 'facebook_ads',
    'message' => 'Hi, looking for more info.'
  ]),
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'X-API-Key: YOUR_API_KEY'
  ],
  CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);

import requests

response = requests.post(
    "https://leadflags.com/api/score-lead/",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_API_KEY"
    },
    json={
        "name": "Alex",
        "email": "alex@fastgrowth-labs.co",
        "phone": "+44 7700 900123",
        "company": "FastGrowth Labs",
        "job_title": "Consultant",
        "industry": "Growth Consulting",
        "company_size": "1-10",
        "country": "UK",
        "source": "facebook_ads",
        "message": "Hi, looking for more info."
    }
)
data = response.json()

require 'net/http'
require 'json'

uri = URI("https://leadflags.com/api/score-lead/")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = (uri.scheme == 'https')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['X-API-Key'] = 'YOUR_API_KEY'
req.body = {
  name: 'Alex',
  email: 'alex@fastgrowth-labs.co',
  phone: '+44 7700 900123',
  company: 'FastGrowth Labs',
  job_title: 'Consultant',
  industry: 'Growth Consulting',
  company_size: '1-10',
  country: 'UK',
  source: 'facebook_ads',
  message: 'Hi, looking for more info.'
}.to_json
res = http.request(req)
data = JSON.parse(res.body)

Response format

On success (200), the response body includes score, quality, risk flags, positive signals, and recommended action. Example:

{
  "score": 73,
  "quality": "high",
  "risk_flags": ["random_name"],
  "positive_signals": ["quality_message", "business_domain_detected"],
  "recommended_action": "standard_priority"
}

Example response with detection_meta:

{
  "score": 73,
  "quality": "high",
  "risk_flags": ["random_name"],
  "positive_signals": ["quality_message", "business_domain_detected"],
  "recommended_action": "standard_priority",
  "detection_meta": {
    "email": { "source": "contactEmail", "method": "explicit_map" },
    "phone": { "source": "tel", "method": "synonym" }
  }
}

Quality levels & recommended actions

Score is mapped to a quality level and a generic recommended action (customizable via ?mid=70&low=40 for Enterprise):

Use recommended_action to route leads in your CRM or workflow. Actions are CRM-agnostic (no call-specific wording).

Flags reference

The API returns two lists: risk_flags (signals that reduce the score) and positive_signals (trust signals). Internal detection details (e.g. which key was used for a field) are not exposed in the response. Below are the semantic flags you may see; relative severity is implied by their presence, not by numeric weights.

Name

Email

Phone

Message

Source

Country

Cross-field & consistency

These flags compare two or more fields. They reduce confidence but do not invalidate the lead by themselves.

Positive signals (positive_signals)

These appear in positive_signals and indicate trust or quality signals.

Thresholds, rate limits & support

Thresholds

Thresholds define how score ranges map to quality and recommended action. Custom thresholds are available for Enterprise.

Custom thresholds (Enterprise)

Pass query parameters mid=X and low=X to set your own cutoffs (e.g. ?mid=70&low=40).

Optional query parameters

Rate limit

How many requests you can make per minute. Examples: Starter 60 req/min, Growth 300 req/min, Scale 1,000 req/min. This protects the server, prevents abuse, and prioritizes premium clients.

Priority processing

When there's load: Starter uses the normal queue; Growth and Scale use the fast queue. At first this can be symbolic, but it sends a clear value message.

Support

Email support: We reply when we can. No guaranteed response times.

Fast / priority support: Response in < 24h. Priority over Starter. You don't need a full support team for this.

IP allowlist (Enterprise)

Only traffic from authorised IPs is accepted. Clients ask for it for security and compliance.

Early access to new features

Growth (and similar) see new features first, help validate them, and feel premium.

Errors

Error responses use standard HTTP status codes and a JSON body with error and optional message.

400 Bad Request — invalid_json

Request body is not valid JSON.

{
  "error": "invalid_json"
}

401 Unauthorized

Missing or invalid X-API-Key header.

{
  "error": "Unauthorized",
  "message": "Valid X-API-Key header required"
}

405 Method Not Allowed

Endpoint only accepts POST.

{
  "error": "Method Not Allowed"
}

Response includes Allow: POST header.

200 OK

Success. Body contains score, quality, risk_flags, positive_signals, recommended_action.

Best practices

• Send only what you have. Don’t invent or guess data. Empty or omitted fields are scored accordingly.
• Use LeadFlags before CRM ingestion. Score at the gate so you don’t store or process low-quality leads.
• Log score and flags in your system. Keep a record for routing, analytics, and auditing.
• Treat recommended_action as a suggestion. Use high_priority, standard_priority, review, or discard to route leads in your CRM or workflow.