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 ID | For | Variables |
|---|---|---|
plumbing | Plumbers | service_radius_km |
electrical | Electricians | service_radius_km |
hvac | Heating and air conditioning | service_radius_km |
roofing | Roofers | service_radius_km |
renovation | Renovation and building | service_radius_km, min_budget, great_budget |
cleaning | Cleaning companies | service_radius_km |
landscaping | Landscapers | service_radius_km, min_budget |
catering_events | Caterers, venues, event services | service_radius_km, min_guests, great_guests |
professional_services | Lawyers, accountants, consultants | — |
b2b_software | Software and B2B demo requests | min_company_size, enterprise_size |
local_service | Any local service, a starting point | service_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 }.rangepicks the value used by simple conditions:min(default),maxormid. - 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:
| Type | Decided by | Effect |
|---|---|---|
rule | A condition on the extracted facts | Adds points (or a grade, see levels) |
ai | The model answers your question with a quote | Adds points (or a grade) |
disqualify | A condition or a question | Tier becomes disqualified, whatever the score |
escalate | A condition or a question | Tier 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'spoints, or a criterion'spointswhen it has no levels and is met — capped to 0–100. Unknown criteria earn 0. If no criterion could be determined, the lead isunscored."method": "sum"(default whenscoringis 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 ofmaxGrade(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.