Lead Intelligence

Qualify an inbound lead by stated intent and your criteria, and recommend follow-up priority.

Endpoint

POST https://kovca.io/api/v1/leads/qualify

Authenticate with your API key in the Authorization: Bearer header. Send JSON with Content-Type: application/json; bodies are limited to 16 KB.

Budget minimums, served countries, and territory routing are applied exactly in code. The inquiry is interpreted for buying intent, timeline, and stated needs, and your plain-language criteria are checked one at a time. The API accepts no personal or demographic fields and never infers budget, authority, or company size that wasn't stated. It never contacts leads or updates your CRM.

Request body

Field	Type	Description
message	string, required	The inquiry, up to 4,000 characters.
company	object, optional	name, industry, size, and country (ISO 3166 alpha-2).
requirements, timeline, product_interest	string, optional	From your form or CRM.
budget	object, optional	{ amount, currency }.
qualification_criteria	object, optional	min_budget { amount, currency } and countries (checked in code), and up to 10 criteria in plain language.
routing_rules	object[], optional	{ territory, countries }. The first territory listing the company's country is returned.

Example request

{
  "message": "We're replacing our current tool for 120 sales reps and need the Salesforce integration. Can you send pricing for an annual plan? We want to sign before the end of next month.",
  "company": {
    "name": "Northwind Traders",
    "industry": "Wholesale distribution",
    "size": "500-1000",
    "country": "US"
  },
  "budget": {
    "amount": 60000,
    "currency": "USD"
  },
  "product_interest": "Sales analytics",
  "qualification_criteria": {
    "min_budget": {
      "amount": 20000,
      "currency": "USD"
    },
    "countries": [
      "US",
      "CA",
      "GB",
      "DE"
    ],
    "criteria": [
      "Needs at least 50 user seats",
      "Uses Salesforce or plans to integrate with it"
    ]
  },
  "routing_rules": [
    {
      "territory": "North America",
      "countries": [
        "US",
        "CA"
      ]
    },
    {
      "territory": "EMEA",
      "countries": [
        "GB",
        "DE",
        "FR"
      ]
    }
  ]
}

Response

200 OK

{
  "request_id": "req_Fy4pV8nKs2QwL6tM",
  "qualification": "hot",
  "intent": "purchase_ready",
  "fit": "meets_criteria",
  "recommended_action": "prioritize_followup",
  "territory": "North America",
  "signals": [
    "explicit_buying_intent",
    "near_term_timeline",
    "budget_stated",
    "requirements_stated"
  ],
  "criteria_results": [
    {
      "criterion": "min_budget",
      "result": "met",
      "evidence": "qualification_criteria.min_budget"
    },
    {
      "criterion": "countries",
      "result": "met",
      "evidence": "qualification_criteria.countries"
    },
    {
      "criterion": "Needs at least 50 user seats",
      "result": "met",
      "evidence": "qualification_criteria.criteria[0]"
    },
    {
      "criterion": "Uses Salesforce or plans to integrate with it",
      "result": "met",
      "evidence": "qualification_criteria.criteria[1]"
    }
  ],
  "missing_information": []
}

Field	Type	Description
request_id	string	Unique ID for this request.
qualification	"hot" \| "warm" \| "cold" \| "unqualified" \| "insufficient_information"	See below.
intent	"purchase_ready" \| "evaluating" \| "information_request" \| "existing_customer_or_support" \| "not_a_sales_inquiry" \| "unclear"	What the sender wants. See below.
fit	"meets_criteria" \| "does_not_meet" \| "unknown" \| "not_evaluated"	Against your criteria only; not_evaluated when you send none.
recommended_action	"prioritize_followup" \| "standard_followup" \| "nurture" \| "request_information" \| "manual_review"	Follow-up priority.
territory	string \| null	From routing_rules, or null.
signals	"explicit_buying_intent" \| "near_term_timeline" \| "budget_stated" \| "requirements_stated" \| "budget_below_minimum" \| "country_not_served" \| "criteria_not_met" \| "criteria_unknown"[]	What drove the result.
criteria_results	object[]	{ criterion, result (met, not_met, unknown), evidence }. Budget in a different currency is unknown, never converted.
missing_information	"budget" \| "timeline" \| "company" \| "qualification_criteria"[]	What would sharpen the result.

Qualification (first match wins)

unqualified → manual_review: Not a sales inquiry, or an existing customer or support request.
unqualified → nurture: A criterion isn't met.
insufficient_information → request_information: The intent is unclear.
hot → prioritize_followup: Explicit buying intent with a near-term timeline.
warm → standard_followup: Buying intent without a near-term timeline, or active evaluation.
cold → nurture: An information request or early research.

Intent

purchase_ready: Explicit buying intent: asks for pricing, a quote, a contract, a trial to buy, or names a purchase decision or date.
evaluating: Actively comparing options or scoping a project, without a stated decision to buy yet.
information_request: General questions or early research, with no project or purchase described.
existing_customer_or_support: An existing customer asking for help, billing, or account changes.
not_a_sales_inquiry: Not a prospective buyer: spam, a job application, a partnership or vendor pitch, or an unrelated message.
unclear: The message doesn't say enough to tell what the sender wants.

Poor fit

Request

{
  "message": "Looking for a simple dashboard for my two-person bakery. What would it cost?",
  "company": {
    "name": "Sunrise Bakery",
    "country": "US"
  },
  "budget": {
    "amount": 500,
    "currency": "USD"
  },
  "qualification_criteria": {
    "min_budget": {
      "amount": 20000,
      "currency": "USD"
    },
    "countries": [
      "US",
      "CA",
      "GB",
      "DE"
    ],
    "criteria": [
      "Needs at least 50 user seats",
      "Uses Salesforce or plans to integrate with it"
    ]
  }
}

Code

curl https://kovca.io/api/v1/leads/qualify \
  -H "Authorization: Bearer $KOVCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "We'\''re replacing our current tool for 120 sales reps and need the Salesforce integration. Can you send pricing for an annual plan? We want to sign before the end of next month.",
  "company": {
    "name": "Northwind Traders",
    "industry": "Wholesale distribution",
    "size": "500-1000",
    "country": "US"
  },
  "budget": {
    "amount": 60000,
    "currency": "USD"
  },
  "product_interest": "Sales analytics",
  "qualification_criteria": {
    "min_budget": {
      "amount": 20000,
      "currency": "USD"
    },
    "countries": [
      "US",
      "CA",
      "GB",
      "DE"
    ],
    "criteria": [
      "Needs at least 50 user seats",
      "Uses Salesforce or plans to integrate with it"
    ]
  },
  "routing_rules": [
    {
      "territory": "North America",
      "countries": [
        "US",
        "CA"
      ]
    },
    {
      "territory": "EMEA",
      "countries": [
        "GB",
        "DE",
        "FR"
      ]
    }
  ]
}'

Errors

400 INVALID_REQUEST: a field is missing, too long, the wrong type, or not allowed. The message names the field.
413 PAYLOAD_TOO_LARGE: the body is larger than 16 KB.
401 UNAUTHORIZED, 429 RATE_LIMITED, 503 SERVICE_UNAVAILABLE, 504 TIMEOUT: see Errors and limits.

Limitations

Fit is judged only against criteria you send. Without them, qualification reflects intent and timing, not fit.
No enrichment: the API doesn't look up companies or people.
Never uses or accepts personal traits or protected characteristics.
Request data is processed to produce the result and is not stored by Kovca.