Leads
A lead is a customer enquiry extracted from a message: who it is, what they want, where, the profile fields and the current evaluation (score, tier and the reason for every criterion). Repeat messages from the same person are merged into their lead.
The Lead object
Properties
- Name
object- Type
- 'lead'
- Description
The object type.
- Name
id- Type
- string
- Description
Unique identifier, prefixed by the object type.
- Name
workspaceId- Type
- string
- Description
The workspace this object belongs to.
- Name
livemode- Type
- boolean
- Description
true for live data, false for data created with a test key.
- Name
sourceId- Type
- string
- Description
The source the message came through.
- Name
inboundIds- Type
- array of string
- Description
The messages this lead was built from (the first one and merged repeats).
- Name
contactId- Type
- string or null
- Description
The person (same email or phone); null without email and phone
- Name
contact- Type
- object
- Description
Who: name, first and last name, emails, phones, other contact methods, company.
- Name
request- Type
- object
- Description
What the customer wants: a one-or-two-sentence summary in the workspace language, and the service.
- Name
location- Type
- object
- Description
Where: address, city, postcode, country; with coordinates, distance (km) and drive time (minutes) from the business when known.
- Name
language- Type
- string or null
- Description
Language of the message (ISO 639-1).
- Name
fields- Type
- object
- Description
Values of the profile fields, typed: numbers, { amount, currency } for money, { value, asWritten } for dates; ranges keep min and max.
- Name
evaluation- Type
- Evaluation
- Description
Current evaluation: score (0–100), tier, confidence, the result and evidence of every criterion, dimensions, and what decided the tier.
- Name
outcome- Type
- Outcome or null
- Description
What happened to the lead, as reported by you
- Name
state- Type
- 'active' | 'archived'
- Description
active, or archived.
- Name
metadata- Type
- object
- Description
Your own key-value pairs (strings), e.g. an ID in your CRM.
- Name
legacy- Type
- object or null
- Description
Original ID and number, for records imported from another system
- Name
createdAt- Type
- string
- Description
When it was created (ISO 8601).
- Name
updatedAt- Type
- string
- Description
When it was last changed (ISO 8601).
Scored leads, newest first
Query parameters
- Name
limit- Type
- integer
- Description
1–100, default 20
- Name
starting_after- Type
- string
- Description
ID of the last item of the previous page
- Name
tier- Type
- string
- Description
e.g. hot, critical, disqualified, unscored
- Name
min_score- Type
- number or null
- Description
- Name
source_id- Type
- string
- Description
- Name
state- Type
- 'active' | 'archived'
- Description
active, or archived.
- Name
contact_id- Type
- string
- Description
- Name
outcome- Type
- 'won' | 'lost' | 'no_response' | 'disqualified' | 'other' | 'none'
- Description
none = no outcome yet
- Name
legacy_id- Type
- string
- Description
Original lead ID, for leads imported from another system (any state)
Request
curl https://core.leadveyor.com/v1/leads \
-H "Authorization: Bearer {api_key}" \
-H "Leadveyor-Workspace: {workspace_id}" # account-wide keys only
Response 200
{
"object": "list",
"data": [
{
"object": "lead",
"id": "lead_u8jzPde0IgxLd6GncfBAepfJ",
"workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
"livemode": true,
"sourceId": "src_IhKtJ0RlgLKOmxgJTeKdNnFR",
"inboundIds": [
"inb_IBXuDL7DxtpYlSXpfKtHF4vU"
],
"contactId": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
"contact": {
"name": "Tom Baker",
"firstName": "Tom",
"lastName": "Baker",
"emails": [
"tom.baker@example.com"
],
"phones": [
"0412555777"
],
"other": [],
"company": null
},
"request": {
"summary": "Customer wants a bathroom renovation in their apartment in Queens, with a budget of about $15k, starting next month.",
"service": "Bathroom renovation"
},
"location": {
"address": null,
"city": "Queens",
"postcode": null,
"country": null
},
"language": "en",
"fields": {
"budget": {
"amount": 15000,
"currency": "USD"
},
"start_date": {
"value": "2026-12-01",
"min": "2026-12-01",
"max": "2026-12-31",
"asWritten": "next month"
},
"property_type": "apartment",
"project_type": "bathroom"
},
"evaluation": {
"confidence": 0.8,
"criteria": [
{
"id": "budget_15k",
"label": "Budget from $15k",
"type": "rule",
"result": "met",
"grade": null,
"points": 30,
"evidence": null,
"dimension": "what"
},
{
"id": "big_project",
"label": "Kitchen, full home or extension",
"type": "rule",
"result": "not_met",
"grade": null,
"points": 0,
"evidence": null,
"dimension": "what"
}
],
"dimensions": [
{
"id": "what",
"label": "What",
"score": 69,
"confidence": 1,
"known": [
"budget_15k",
"big_project"
],
"unknown": []
},
{
"id": "when",
"label": "When",
"score": null,
"confidence": 0,
"known": [],
"unknown": [
"start_soon"
]
}
],
"decidedBy": null,
"score": 60,
"tier": "warm",
"id": "eval_uvSwMFLZDe1f8rESQedUStPK",
"profileId": "prof_R0CsTy4Qwb8DwkNhFdnXsiVp",
"profileVersion": 1,
"evaluatedAt": "2026-10-23T15:07:26.371Z"
},
"outcome": {
"status": "won",
"value": {
"amount": 14800,
"currency": "USD"
},
"reason": null,
"occurredAt": "2026-11-02T09:30:00.000Z",
"recordedAt": "2026-10-23T15:38:00.591Z",
"recordedBy": {
"type": "api_key",
"id": "key_zz63FfkCzJr4i0B3JrTAwR4y"
}
},
"state": "active",
"metadata": {},
"legacy": null,
"createdAt": "2026-10-23T15:07:26.371Z",
"updatedAt": "2026-10-23T15:38:00.591Z"
}
],
"has_more": false,
"next_cursor": null
}
One lead with its current evaluation
Path parameters
- Name
id- Type
- string
- Description
Unique identifier, prefixed by the object type.
Request
curl https://core.leadveyor.com/v1/leads/lead_2Ph6Tc9Ks4Wm1Lx7Qv3Nb8Dr \
-H "Authorization: Bearer {api_key}" \
-H "Leadveyor-Workspace: {workspace_id}" # account-wide keys only
Response 200
{
"object": "lead",
"id": "lead_u8jzPde0IgxLd6GncfBAepfJ",
"workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
"livemode": true,
"sourceId": "src_IhKtJ0RlgLKOmxgJTeKdNnFR",
"inboundIds": [
"inb_IBXuDL7DxtpYlSXpfKtHF4vU"
],
"contactId": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
"contact": {
"name": "Tom Baker",
"firstName": "Tom",
"lastName": "Baker",
"emails": [
"tom.baker@example.com"
],
"phones": [
"0412555777"
],
"other": [],
"company": null
},
"request": {
"summary": "Customer wants a bathroom renovation in their apartment in Queens, with a budget of about $15k, starting next month.",
"service": "Bathroom renovation"
},
"location": {
"address": null,
"city": "Queens",
"postcode": null,
"country": null
},
"language": "en",
"fields": {
"budget": {
"amount": 15000,
"currency": "USD"
},
"start_date": {
"value": "2026-12-01",
"min": "2026-12-01",
"max": "2026-12-31",
"asWritten": "next month"
},
"property_type": "apartment",
"project_type": "bathroom"
},
"evaluation": {
"confidence": 0.8,
"criteria": [
{
"id": "budget_15k",
"label": "Budget from $15k",
"type": "rule",
"result": "met",
"grade": null,
"points": 30,
"evidence": null,
"dimension": "what"
},
{
"id": "big_project",
"label": "Kitchen, full home or extension",
"type": "rule",
"result": "not_met",
"grade": null,
"points": 0,
"evidence": null,
"dimension": "what"
}
],
"dimensions": [
{
"id": "what",
"label": "What",
"score": 69,
"confidence": 1,
"known": [
"budget_15k",
"big_project"
],
"unknown": []
},
{
"id": "when",
"label": "When",
"score": null,
"confidence": 0,
"known": [],
"unknown": [
"start_soon"
]
}
],
"decidedBy": null,
"score": 60,
"tier": "warm",
"id": "eval_uvSwMFLZDe1f8rESQedUStPK",
"profileId": "prof_R0CsTy4Qwb8DwkNhFdnXsiVp",
"profileVersion": 1,
"evaluatedAt": "2026-10-23T15:07:26.371Z"
},
"outcome": {
"status": "won",
"value": {
"amount": 14800,
"currency": "USD"
},
"reason": null,
"occurredAt": "2026-11-02T09:30:00.000Z",
"recordedAt": "2026-10-23T15:38:00.591Z",
"recordedBy": {
"type": "api_key",
"id": "key_zz63FfkCzJr4i0B3JrTAwR4y"
}
},
"state": "active",
"metadata": {},
"legacy": null,
"createdAt": "2026-10-23T15:07:26.371Z",
"updatedAt": "2026-10-23T15:38:00.591Z"
}
Evaluation history of a lead, newest first
Path parameters
- Name
id- Type
- string
- Description
Unique identifier, prefixed by the object type.
Query parameters
- Name
limit- Type
- integer
- Description
1–100, default 20
- Name
starting_after- Type
- string
- Description
ID of the last item of the previous page
Request
curl https://core.leadveyor.com/v1/leads/lead_2Ph6Tc9Ks4Wm1Lx7Qv3Nb8Dr/evaluations \
-H "Authorization: Bearer {api_key}" \
-H "Leadveyor-Workspace: {workspace_id}" # account-wide keys only
Response 200
{
"object": "list",
"data": [
{
"score": null,
"tier": "tier",
"confidence": 0,
"decidedBy": {
"id": "id",
"type": "disqualify",
"reason": "reason"
},
"dimensions": [
{
"id": "id",
"label": "label",
"score": null,
"confidence": 0,
"known": [
"known"
],
"unknown": [
"unknown"
]
}
],
"criteria": [
{
"id": "id",
"label": "label",
"type": "rule",
"result": "met",
"grade": null,
"points": 0,
"evidence": null,
"dimension": null
}
],
"object": "evaluation",
"id": "id",
"leadId": "lead_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
"inboundId": "inbo_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
"jobId": "job_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
"profileId": "prof_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
"profileVersion": 0,
"pipelineVersion": "pipelineVersion",
"createdAt": "2026-11-02T09:30:00.000Z"
}
],
"has_more": false,
"next_cursor": null
}
Record what happened to the lead: won, lost, … (replaces an earlier outcome)
Path parameters
- Name
id- Type
- string
- Description
Unique identifier, prefixed by the object type.
Required attributes
- Name
status- Type
- 'won' | 'lost' | 'no_response' | 'disqualified' | 'other'
- Description
Current status.
Optional attributes
- Name
amount- Type
- number
- Description
Deal value
- Name
currency- Type
- string
- Description
ISO 4217; default: the workspace currency
- Name
reason- Type
- string or null
- Description
Why, especially for lost
- Name
occurredAt- Type
- string
- Description
When it happened; default: now
Request
curl -X POST https://core.leadveyor.com/v1/leads/lead_2Ph6Tc9Ks4Wm1Lx7Qv3Nb8Dr/outcome \
-H "Authorization: Bearer {api_key}" \
-H "Leadveyor-Workspace: {workspace_id}" # account-wide keys only \
-H "Content-Type: application/json" \
-d '{
"status": "won",
"amount": 0,
"currency": "currency",
"reason": null
}'
Response 200
{
"object": "lead",
"id": "lead_u8jzPde0IgxLd6GncfBAepfJ",
"workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
"livemode": true,
"sourceId": "src_IhKtJ0RlgLKOmxgJTeKdNnFR",
"inboundIds": [
"inb_IBXuDL7DxtpYlSXpfKtHF4vU"
],
"contactId": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
"contact": {
"name": "Tom Baker",
"firstName": "Tom",
"lastName": "Baker",
"emails": [
"tom.baker@example.com"
],
"phones": [
"0412555777"
],
"other": [],
"company": null
},
"request": {
"summary": "Customer wants a bathroom renovation in their apartment in Queens, with a budget of about $15k, starting next month.",
"service": "Bathroom renovation"
},
"location": {
"address": null,
"city": "Queens",
"postcode": null,
"country": null
},
"language": "en",
"fields": {
"budget": {
"amount": 15000,
"currency": "USD"
},
"start_date": {
"value": "2026-12-01",
"min": "2026-12-01",
"max": "2026-12-31",
"asWritten": "next month"
},
"property_type": "apartment",
"project_type": "bathroom"
},
"evaluation": {
"confidence": 0.8,
"criteria": [
{
"id": "budget_15k",
"label": "Budget from $15k",
"type": "rule",
"result": "met",
"grade": null,
"points": 30,
"evidence": null,
"dimension": "what"
},
{
"id": "big_project",
"label": "Kitchen, full home or extension",
"type": "rule",
"result": "not_met",
"grade": null,
"points": 0,
"evidence": null,
"dimension": "what"
}
],
"dimensions": [
{
"id": "what",
"label": "What",
"score": 69,
"confidence": 1,
"known": [
"budget_15k",
"big_project"
],
"unknown": []
},
{
"id": "when",
"label": "When",
"score": null,
"confidence": 0,
"known": [],
"unknown": [
"start_soon"
]
}
],
"decidedBy": null,
"score": 60,
"tier": "warm",
"id": "eval_uvSwMFLZDe1f8rESQedUStPK",
"profileId": "prof_R0CsTy4Qwb8DwkNhFdnXsiVp",
"profileVersion": 1,
"evaluatedAt": "2026-10-23T15:07:26.371Z"
},
"outcome": {
"status": "won",
"value": {
"amount": 14800,
"currency": "USD"
},
"reason": null,
"occurredAt": "2026-11-02T09:30:00.000Z",
"recordedAt": "2026-10-23T15:38:00.591Z",
"recordedBy": {
"type": "api_key",
"id": "key_zz63FfkCzJr4i0B3JrTAwR4y"
}
},
"state": "active",
"metadata": {},
"legacy": null,
"createdAt": "2026-10-23T15:07:26.371Z",
"updatedAt": "2026-10-23T15:38:00.591Z"
}
Remove the outcome (the deal was reopened)
Path parameters
- Name
id- Type
- string
- Description
Unique identifier, prefixed by the object type.
Request
curl -X DELETE https://core.leadveyor.com/v1/leads/lead_2Ph6Tc9Ks4Wm1Lx7Qv3Nb8Dr/outcome \
-H "Authorization: Bearer {api_key}" \
-H "Leadveyor-Workspace: {workspace_id}" # account-wide keys only
Response 200
{
"object": "lead",
"id": "lead_u8jzPde0IgxLd6GncfBAepfJ",
"workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
"livemode": true,
"sourceId": "src_IhKtJ0RlgLKOmxgJTeKdNnFR",
"inboundIds": [
"inb_IBXuDL7DxtpYlSXpfKtHF4vU"
],
"contactId": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
"contact": {
"name": "Tom Baker",
"firstName": "Tom",
"lastName": "Baker",
"emails": [
"tom.baker@example.com"
],
"phones": [
"0412555777"
],
"other": [],
"company": null
},
"request": {
"summary": "Customer wants a bathroom renovation in their apartment in Queens, with a budget of about $15k, starting next month.",
"service": "Bathroom renovation"
},
"location": {
"address": null,
"city": "Queens",
"postcode": null,
"country": null
},
"language": "en",
"fields": {
"budget": {
"amount": 15000,
"currency": "USD"
},
"start_date": {
"value": "2026-12-01",
"min": "2026-12-01",
"max": "2026-12-31",
"asWritten": "next month"
},
"property_type": "apartment",
"project_type": "bathroom"
},
"evaluation": {
"confidence": 0.8,
"criteria": [
{
"id": "budget_15k",
"label": "Budget from $15k",
"type": "rule",
"result": "met",
"grade": null,
"points": 30,
"evidence": null,
"dimension": "what"
},
{
"id": "big_project",
"label": "Kitchen, full home or extension",
"type": "rule",
"result": "not_met",
"grade": null,
"points": 0,
"evidence": null,
"dimension": "what"
}
],
"dimensions": [
{
"id": "what",
"label": "What",
"score": 69,
"confidence": 1,
"known": [
"budget_15k",
"big_project"
],
"unknown": []
},
{
"id": "when",
"label": "When",
"score": null,
"confidence": 0,
"known": [],
"unknown": [
"start_soon"
]
}
],
"decidedBy": null,
"score": 60,
"tier": "warm",
"id": "eval_uvSwMFLZDe1f8rESQedUStPK",
"profileId": "prof_R0CsTy4Qwb8DwkNhFdnXsiVp",
"profileVersion": 1,
"evaluatedAt": "2026-10-23T15:07:26.371Z"
},
"outcome": {
"status": "won",
"value": {
"amount": 14800,
"currency": "USD"
},
"reason": null,
"occurredAt": "2026-11-02T09:30:00.000Z",
"recordedAt": "2026-10-23T15:38:00.591Z",
"recordedBy": {
"type": "api_key",
"id": "key_zz63FfkCzJr4i0B3JrTAwR4y"
}
},
"state": "active",
"metadata": {},
"legacy": null,
"createdAt": "2026-10-23T15:07:26.371Z",
"updatedAt": "2026-10-23T15:38:00.591Z"
}