Scoring profiles

A profile is a JSON document that says what to extract from a message and how to score it. You define the criteria; the model only extracts facts and answers your questions with quotes from the message — the score itself is always computed by code, so the same facts always give the same score.

The document

{
  "name": "Home renovation",
  "brief": "Residential renovation company. Best customers are home owners with a budget from $15,000 who want to start within three months.",
  "extract": [ … ],
  "criteria": [ … ],
  "scoring": { "method": "points" },
  "tiers": [ { "name": "hot", "minScore": 70 }, { "name": "warm", "minScore": 40 }, { "name": "cold", "minScore": 0 } ],
  "dimensions": [ { "id": "what", "label": "What" }, { "id": "when", "label": "When" } ],
  "junk": { "enabled": true, "extraRules": [], "blockDomains": [], "allowDomains": [] }
}

brief describes the business in a few sentences; it helps the model understand what counts as a lead and how to read the messages. Check a document without saving it with POST /v1/profiles/validate — it returns every problem at once, with paths.

Start from a template

You don't have to write the document from scratch. Leadveyor has built-in templates for common businesses:

Template IDForVariables
plumbingPlumbersservice_radius_km
electricalElectriciansservice_radius_km
hvacHeating and air conditioningservice_radius_km
roofingRoofersservice_radius_km
renovationRenovation and buildingservice_radius_km, min_budget, great_budget
cleaningCleaning companiesservice_radius_km
landscapingLandscapersservice_radius_km, min_budget
catering_eventsCaterers, venues, event servicesservice_radius_km, min_guests, great_guests
professional_servicesLawyers, accountants, consultants—
b2b_softwareSoftware and B2B demo requestsmin_company_size, enterprise_size
local_serviceAny local service, a starting pointservice_radius_km

Create a profile from one, with your own numbers. Variables you leave out use the template's defaults; money is in the workspace currency:

curl https://core.leadveyor.com/v1/profiles \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "renovation", "variables": { "service_radius_km": 25, "min_budget": 20000 }, "name": "Our renovations" }'

The result is an ordinary draft: change any criterion, test it, publish it. GET /v1/templates/{id} shows a template's document before you use it. Service-area criteria use the distance from the workspace address — set the address in the workspace settings, or the distance stays unknown.

Write it from a description

Or describe the business in plain words and let AI draft the whole profile — fields, criteria with points, escalations, disqualifiers and junk rules:

curl https://core.leadveyor.com/v1/profiles/generate \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{ "brief": "Plumbing business in Brisbane. Our best jobs are emergencies and bathroom renovations from $15k. We also replace hot water systems. No commercial or strata work, no new builds." }'

The response has the new profile with the generated document as its draft (nothing is published), assumptions — what the AI assumed that you didn't say, worth checking — and dropped, any generated criteria left out because they were invalid. Add templateId (and variables) to start from a template and adapt it. It takes 10–30 seconds and costs about $0.02. Then review the draft, test it on a few real messages and publish.

The more specific the description, the better the profile: say what you do, where, which jobs or customers are best, and what you never take on. The workspace's business description, currency, language and address are used too.

Fields to extract

Contact details, a summary, the service and the address are always extracted. Add the fields that matter to you:

"extract": [
  { "key": "budget", "type": "money", "description": "Project budget" },
  { "key": "guests", "type": "number", "description": "Number of guests", "range": "min" },
  { "key": "event_date", "type": "date", "description": "Date of the event" },
  { "key": "property_type", "type": "enum", "values": ["house", "apartment", "commercial"] }
]

Types: string, text, number, money, date, datetime, boolean, enum, multi_enum, email, phone, url.

  • Money is stored as { "amount": 15000, "currency": "USD" }; without a currency in the message, the workspace currency is used.
  • Ranges keep both ends: "100–150 guests" becomes { "value": 100, "min": 100, "max": 150 }. range picks the value used by simple conditions: min (default), max or mid.
  • Dates always keep the customer's wording in asWritten. Relative dates ("this Saturday") are resolved from the day the message arrived. Vague periods ("next month", "in spring") become a range of days; "TBA" stays empty.

Criteria

Four types of criteria, up to 30 per profile:

TypeDecided byEffect
ruleA condition on the extracted factsAdds points (or a grade, see levels)
aiThe model answers your question with a quoteAdds points (or a grade)
disqualifyA condition or a questionTier becomes disqualified, whatever the score
escalateA condition or a questionTier becomes the highest (or tier), whatever the score
"criteria": [
  { "id": "budget_15k", "type": "rule", "label": "Budget from $15k",
    "condition": { "field": "fields.budget", "op": "gte", "value": 15000 }, "points": 30 },
  { "id": "owner", "type": "ai", "label": "Home owner",
    "question": "Is the customer the owner of the property (not a tenant or agent)?", "points": 20,
    "guidance": "Phrases like 'my house', 'our home' or 'we bought' mean yes. A landlord renovating a rental also counts." },
  { "id": "commercial", "type": "disqualify", "label": "Commercial property",
    "condition": { "field": "fields.property_type", "op": "eq", "value": "commercial" },
    "reason": "We don't take commercial projects" },
  { "id": "urgent", "type": "escalate", "label": "Urgent job",
    "question": "Does the customer need the work done within a week?", "reason": "Call back today" }
]

guidance gives the model detailed instructions for one question: keywords, defaults, edge cases. Every answer is met, not_met or unknown; a met answer must quote the message, and a quote that isn't found in the message is rejected. That also protects you from messages that try to talk the model into a higher score.

Conditions

{ "field": "fields.budget", "op": "gte", "value": 15000 }
{ "all": [ { "field": "location.distanceKm", "op": "lte", "value": 30 }, { "field": "fields.guests", "op": "gte", "value": 50 } ] }
{ "any": [ … ] }
{ "not": { "field": "contact.emailFree", "op": "eq", "value": true } }

Operators: eq, neq, gt, gte, lt, lte, in, nin, contains, exists, within. within takes an ISO 8601 duration from today ("P14D", "P3M").

Fields: fields.<key> for your fields, plus contact.name, contact.emails, contact.phones, contact.company, contact.emailDomains, contact.emailFree, request.summary, request.service, location.address, location.distanceKm, location.driveMinutes, language, inbound.channel, inbound.localTime, inbound.dayOfWeek, inbound.isBusinessHours.

Missing data is never treated as "yes" or "no": a condition on a missing field is unknown. An unknown criterion earns no points and lowers the evaluation's confidence, so you can tell a weak lead from one that simply said too little. A disqualifier never fires on unknown data. A date range counts only when the whole range agrees — "next month" is within 60 days, but "in spring" isn't within 14.

Levels

Instead of fixed points, a criterion can grade the answer:

{ "id": "distance", "type": "rule", "label": "Distance from depot",
  "levels": [
    { "grade": 5, "condition": { "field": "location.distanceKm", "op": "lte", "value": 15 } },
    { "grade": 3, "condition": { "field": "location.distanceKm", "op": "lte", "value": 40 } },
    { "grade": 1, "condition": { "field": "location.distanceKm", "op": "gt", "value": 40 } }
  ] }

The first matching level wins. AI criteria use description instead of condition for each level; the model picks the level that fits.

With "method": "points", each level also has points — what the lead earns when that level is chosen. grade is then just the level's number for the model (unique within the criterion):

{ "id": "wedding", "type": "ai", "label": "Wedding lead time",
  "question": "Is it a wedding, and how far away is it?",
  "levels": [
    { "grade": 3, "points": 30, "description": "Wedding 9 or more months from today" },
    { "grade": 2, "points": 20, "description": "Wedding 3 to 9 months from today" },
    { "grade": 1, "points": 10, "description": "Wedding less than 3 months from today" }
  ] }

Scores and tiers

  • "method": "points" (recommended): the score is the plain sum of the points earned — each level's points, or a criterion's points when it has no levels and is met — capped to 0–100. Unknown criteria earn 0. If no criterion could be determined, the lead is unscored.
  • "method": "sum" (default when scoring is omitted): the score is the points earned as a share of the maximum possible points, from 0 to 100. Points can be negative (a penalty).
  • "method": "average": the score is the average grade of all graded criteria, as a percentage of maxGrade (default 5).

The tier is the first one whose minScore the score reaches. Two tiers are reserved: disqualified (a disqualify criterion matched) and unscored (nothing could be determined).

dimensions group criteria into a breakdown (for example who / what / when / where, or budget / authority / need / timeline). Each dimension gets its own score and confidence in the evaluation; dimensions don't change the overall score.

Junk

Spam, newsletters, sales pitches and auto-replies are filtered before extraction. Only a confident "not a lead" stops a message — when in doubt, it is processed. Add your own rules in plain language (extraRules), and always-junk or never-junk sender domains (blockDomains, allowDomains).

Versions

Profiles are versioned. Edit a draft (PUT or PATCH /v1/profiles/{id}/draft), then publish it as a new version. Every evaluation records the profile version it used, and POST /v1/profiles/{id}/activate rolls back to any earlier version. Score past messages again with a new profile by reprocessing them.

Was this page helpful?