API Reference

Overview

LeadFlags scores inbound leads with predefined quality criteria and returns a numeric score, quality level, flags, 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.

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":"Pieter van der Berg","email":"pieter@bedrijf.nl","phone":"+31612345678","message":"Interested in enterprise plan","source":"website","country":"NL"}'

fetch("https://leadflags.com/api/score-lead/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    name: "Jane Doe",
    email: "jane@company.com",
    phone: "+34912345678",
    message: "Interested in enterprise plan",
    source: "website",
    country: "ES"
  })
})
  .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' => 'Pieter van der Berg',
    'email' => 'pieter@bedrijf.nl',
    'phone' => '+31612345678',
    'message' => 'Interested in enterprise plan',
    'source' => 'website',
    'country' => 'NL'
  ]),
  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": "Jane Doe",
        "email": "jane@company.com",
        "phone": "+34912345678",
        "message": "Interested in enterprise plan",
        "source": "website",
        "country": "ES"
    }
)
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: 'Pieter van der Berg',
  email: 'pieter@bedrijf.nl',
  phone: '+31612345678',
  message: 'Interested in enterprise plan',
  source: 'website',
  country: 'NL'
}.to_json
res = http.request(req)
data = JSON.parse(res.body)

Response format

On success (200), the response body is (example for the request above — complete lead, no flags):

{
  "score": 100,
  "quality": "high",
  "flags": [],
  "recommended_action": "call_immediately"
}

Quality levels & recommended actions

Default thresholds (customizable via query params ?mid=80&low=50 for Enterprise):

Flags reference

Flags explain why the score was reduced. Each flag has a severity (Low, Medium, High, Critical) that reflects its relative importance. Exact score weights are internal and may change over time.

Name

Email

Phone

Message

Source

Country

Thresholds, rate limits & support

Thresholds

A threshold is the limit at which something changes. In our case: score threshold and action threshold. Example: score ≥ 80 → call immediately; score ≥ 50 → review; score < 50 → do not call.

Custom thresholds (Enterprise)

Pass query parameters mid=X and low=X to set your own cutoffs.

Example: POST /api/score-lead?mid=70&low=40 — then score ≥ 70 is high, ≥ 40 is medium, < 40 is low. Defaults: mid=80, low=50.

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, flags, 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. You decide how to route (call immediately, queue for review, or do not call).