Contacts
A contact is a person, matched by email or phone across all their leads with no time limit. Mark VIP or blocked people, and see how many of their leads were won or lost.
The Contact object
Properties
- Name
object- Type
- 'contact'
- 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
name- Type
- string or null
- Description
Display name.
- Name
firstName- Type
- string or null
- Description
- Name
lastName- Type
- string or null
- Description
- Name
company- Type
- string or null
- Description
- Name
emails- Type
- array of string
- Description
- Name
phones- Type
- array of string
- Description
- Name
vip- Type
- boolean
- Description
- Name
blocked- Type
- boolean
- Description
- Name
metadata- Type
- object
- Description
Your own key-value pairs (strings), e.g. an ID in your CRM.
- Name
stats- Type
- object
- Description
- 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).
People who sent 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
email- Type
- string
- Description
- Name
phone- Type
- string
- Description
Any format; matched by the last 9 digits
- Name
vip- Type
- 'true' | 'false'
- Description
- Name
blocked- Type
- 'true' | 'false'
- Description
- Name
legacy_id- Type
- string
- Description
Original contact ID, for contacts imported from another system
Request
curl https://core.leadveyor.com/v1/contacts \
-H "Authorization: Bearer {api_key}" \
-H "Leadveyor-Workspace: {workspace_id}" # account-wide keys only
Response 200
{
"object": "list",
"data": [
{
"object": "contact",
"id": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
"workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
"livemode": true,
"name": "Tom Baker",
"firstName": "Tom",
"lastName": "Baker",
"company": null,
"emails": [
"tom.baker@example.com"
],
"phones": [
"0412555777"
],
"vip": false,
"blocked": false,
"metadata": {},
"stats": {
"leads": 1,
"won": 1,
"lost": 0,
"lastLeadAt": "2026-10-23T15:07:26.371Z"
},
"legacy": null,
"createdAt": "2026-10-23T15:07:26.390Z",
"updatedAt": "2026-10-23T15:07:26.390Z"
}
],
"has_more": false,
"next_cursor": null
}
One contact with lead and outcome counts
Path parameters
- Name
id- Type
- string
- Description
Unique identifier, prefixed by the object type.
Request
curl https://core.leadveyor.com/v1/contacts/ctc_7Rm2Kx9Pq4Lz1Wv6Tn3Hb8Dc \
-H "Authorization: Bearer {api_key}" \
-H "Leadveyor-Workspace: {workspace_id}" # account-wide keys only
Response 200
{
"object": "contact",
"id": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
"workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
"livemode": true,
"name": "Tom Baker",
"firstName": "Tom",
"lastName": "Baker",
"company": null,
"emails": [
"tom.baker@example.com"
],
"phones": [
"0412555777"
],
"vip": false,
"blocked": false,
"metadata": {},
"stats": {
"leads": 1,
"won": 1,
"lost": 0,
"lastLeadAt": "2026-10-23T15:07:26.371Z"
},
"legacy": null,
"createdAt": "2026-10-23T15:07:26.390Z",
"updatedAt": "2026-10-23T15:07:26.390Z"
}
Mark VIP or blocked, fix name or company, set your metadata
Path parameters
- Name
id- Type
- string
- Description
Unique identifier, prefixed by the object type.
Optional attributes
- Name
name- Type
- string or null
- Description
Display name.
- Name
company- Type
- string or null
- Description
- Name
vip- Type
- boolean
- Description
- Name
blocked- Type
- boolean
- Description
Mark as never-a-customer (spam, competitor)
- Name
metadata- Type
- object
- Description
Replaces your key-values, e.g. a CRM id
Request
curl -X PATCH https://core.leadveyor.com/v1/contacts/ctc_7Rm2Kx9Pq4Lz1Wv6Tn3Hb8Dc \
-H "Authorization: Bearer {api_key}" \
-H "Leadveyor-Workspace: {workspace_id}" # account-wide keys only \
-H "Content-Type: application/json" \
-d '{
"name": null,
"company": null,
"vip": false,
"blocked": false
}'
Response 200
{
"object": "contact",
"id": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
"workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
"livemode": true,
"name": "Tom Baker",
"firstName": "Tom",
"lastName": "Baker",
"company": null,
"emails": [
"tom.baker@example.com"
],
"phones": [
"0412555777"
],
"vip": false,
"blocked": false,
"metadata": {},
"stats": {
"leads": 1,
"won": 1,
"lost": 0,
"lastLeadAt": "2026-10-23T15:07:26.371Z"
},
"legacy": null,
"createdAt": "2026-10-23T15:07:26.390Z",
"updatedAt": "2026-10-23T15:07:26.390Z"
}
All leads of this person, 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/contacts/ctc_7Rm2Kx9Pq4Lz1Wv6Tn3Hb8Dc/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
}