Leads
Prospects before they become deals, with status and source.
List leads
GET/api/v1/leads/
Parameters
cursorquery, string- Opaque pagination cursor (follow next/previous URLs).
searchquery, stringorderingquery, string- Field to order by; prefix with '-' for descending.
statusquery, stringassigned_toquery, string
Response fields 31
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectlead_originenumstatusstringsourcestringmediumstringchannelstringplatformstringcampaignstringprioritystringlead_datestring (date)scoreintegerassigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjecttagsobjectcustom_fieldsobjectimport_job_idstring (uuid)is_potential_duplicatebooleanduplicate_reasonenumnotes_countobjectactivities_countobjectdeals_countobjecttasks_countobjectcreated_atstring (date-time)updated_atstring (date-time)
curl "https://api.vivrecrm.com/api/v1/leads/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/leads/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/", {
method: "GET",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(await resp.json());{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"created_source": "api_key",
"created_source_label": "",
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"first_name": "Asha",
"last_name": "Rao",
"full_name": "Asha Rao",
"email": "[email protected]",
"phone": "9876543210",
"phone_country_code": "+91",
"job_title": "Head of Operations",
"whatsapp_number": "9876543210",
"whatsapp_country_code": "+91",
"company_name": null,
"company_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"lead_origin": "import",
"status": "new",
"source": "website",
"medium": "",
"channel": "",
"platform": "",
"campaign": "",
"priority": "",
"lead_date": "2026-10-31",
"score": 1,
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"tags": null,
"custom_fields": {},
"import_job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"is_potential_duplicate": true,
"duplicate_reason": "duplicate",
"notes_count": null,
"activities_count": null,
"deals_count": null,
"tasks_count": null,
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
}
]
}Create lead
POST/api/v1/leads/
Parameters
Idempotency-Keyheader, string- Unique key for safe retries (24h replay window).
Body
contact_idstring, can be nullstatusstringsourcestring, can be nullmediumstring, can be nullchannelstring, can be nullplatformstring, can be nullcampaignstring, can be nullprioritystring, can be nulllead_datestring (date), can be nullscoreintegerassigned_to_idstring, can be nullcustom_fieldsobject
Response fields 31
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectlead_originenumstatusstringsourcestringmediumstringchannelstringplatformstringcampaignstringprioritystringlead_datestring (date)scoreintegerassigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjecttagsobjectcustom_fieldsobjectimport_job_idstring (uuid)is_potential_duplicatebooleanduplicate_reasonenumnotes_countobjectactivities_countobjectdeals_countobjecttasks_countobjectcreated_atstring (date-time)updated_atstring (date-time)
curl -X POST "https://api.vivrecrm.com/api/v1/leads/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "new", "source": "website"}'import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/leads/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"status": "new",
"source": "website"
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"status": "new",
"source": "website"
}),
});
console.log(await resp.json());{
"created_source": "api_key",
"created_source_label": "",
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"first_name": "Asha",
"last_name": "Rao",
"full_name": "Asha Rao",
"email": "[email protected]",
"phone": "9876543210",
"phone_country_code": "+91",
"job_title": "Head of Operations",
"whatsapp_number": "9876543210",
"whatsapp_country_code": "+91",
"company_name": null,
"company_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"lead_origin": "import",
"status": "new",
"source": "website",
"medium": "",
"channel": "",
"platform": "",
"campaign": "",
"priority": "",
"lead_date": "2026-10-31",
"score": 1,
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"tags": null,
"custom_fields": {},
"import_job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"is_potential_duplicate": true,
"duplicate_reason": "duplicate",
"notes_count": null,
"activities_count": null,
"deals_count": null,
"tasks_count": null,
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
}Retrieve a lead
GET/api/v1/leads/{public_id}/
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
Response fields 31
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectlead_originenumstatusstringsourcestringmediumstringchannelstringplatformstringcampaignstringprioritystringlead_datestring (date)scoreintegerassigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjecttagsobjectcustom_fieldsobjectimport_job_idstring (uuid)is_potential_duplicatebooleanduplicate_reasonenumnotes_countobjectactivities_countobjectdeals_countobjecttasks_countobjectcreated_atstring (date-time)updated_atstring (date-time)
curl "https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
method: "GET",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(await resp.json());{
"created_source": "api_key",
"created_source_label": "",
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"first_name": "Asha",
"last_name": "Rao",
"full_name": "Asha Rao",
"email": "[email protected]",
"phone": "9876543210",
"phone_country_code": "+91",
"job_title": "Head of Operations",
"whatsapp_number": "9876543210",
"whatsapp_country_code": "+91",
"company_name": null,
"company_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"lead_origin": "import",
"status": "new",
"source": "website",
"medium": "",
"channel": "",
"platform": "",
"campaign": "",
"priority": "",
"lead_date": "2026-10-31",
"score": 1,
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"tags": null,
"custom_fields": {},
"import_job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"is_potential_duplicate": true,
"duplicate_reason": "duplicate",
"notes_count": null,
"activities_count": null,
"deals_count": null,
"tasks_count": null,
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
}Replace a lead
PUT/api/v1/leads/{public_id}/
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
Body
contact_idstring, can be nullstatusstringsourcestring, can be nullmediumstring, can be nullchannelstring, can be nullplatformstring, can be nullcampaignstring, can be nullprioritystring, can be nulllead_datestring (date), can be nullscoreintegerassigned_to_idstring, can be nullcustom_fieldsobject
Response fields 31
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectlead_originenumstatusstringsourcestringmediumstringchannelstringplatformstringcampaignstringprioritystringlead_datestring (date)scoreintegerassigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjecttagsobjectcustom_fieldsobjectimport_job_idstring (uuid)is_potential_duplicatebooleanduplicate_reasonenumnotes_countobjectactivities_countobjectdeals_countobjecttasks_countobjectcreated_atstring (date-time)updated_atstring (date-time)
curl -X PUT "https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "new", "source": "website"}'import os, requests
resp = requests.put(
"https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"status": "new",
"source": "website"
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
method: "PUT",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"status": "new",
"source": "website"
}),
});
console.log(await resp.json());{
"created_source": "api_key",
"created_source_label": "",
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"first_name": "Asha",
"last_name": "Rao",
"full_name": "Asha Rao",
"email": "[email protected]",
"phone": "9876543210",
"phone_country_code": "+91",
"job_title": "Head of Operations",
"whatsapp_number": "9876543210",
"whatsapp_country_code": "+91",
"company_name": null,
"company_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"lead_origin": "import",
"status": "new",
"source": "website",
"medium": "",
"channel": "",
"platform": "",
"campaign": "",
"priority": "",
"lead_date": "2026-10-31",
"score": 1,
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"tags": null,
"custom_fields": {},
"import_job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"is_potential_duplicate": true,
"duplicate_reason": "duplicate",
"notes_count": null,
"activities_count": null,
"deals_count": null,
"tasks_count": null,
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
}Update a lead
PATCH/api/v1/leads/{public_id}/
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
Body
contact_idstring, can be nullstatusstringsourcestring, can be nullmediumstring, can be nullchannelstring, can be nullplatformstring, can be nullcampaignstring, can be nullprioritystring, can be nulllead_datestring (date), can be nullscoreintegerassigned_to_idstring, can be nullcustom_fieldsobject
Response fields 31
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectlead_originenumstatusstringsourcestringmediumstringchannelstringplatformstringcampaignstringprioritystringlead_datestring (date)scoreintegerassigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjecttagsobjectcustom_fieldsobjectimport_job_idstring (uuid)is_potential_duplicatebooleanduplicate_reasonenumnotes_countobjectactivities_countobjectdeals_countobjecttasks_countobjectcreated_atstring (date-time)updated_atstring (date-time)
curl -X PATCH "https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "new", "source": "website"}'import os, requests
resp = requests.patch(
"https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"status": "new",
"source": "website"
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
method: "PATCH",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"status": "new",
"source": "website"
}),
});
console.log(await resp.json());{
"created_source": "api_key",
"created_source_label": "",
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"first_name": "Asha",
"last_name": "Rao",
"full_name": "Asha Rao",
"email": "[email protected]",
"phone": "9876543210",
"phone_country_code": "+91",
"job_title": "Head of Operations",
"whatsapp_number": "9876543210",
"whatsapp_country_code": "+91",
"company_name": null,
"company_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"lead_origin": "import",
"status": "new",
"source": "website",
"medium": "",
"channel": "",
"platform": "",
"campaign": "",
"priority": "",
"lead_date": "2026-10-31",
"score": 1,
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"tags": null,
"custom_fields": {},
"import_job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"is_potential_duplicate": true,
"duplicate_reason": "duplicate",
"notes_count": null,
"activities_count": null,
"deals_count": null,
"tasks_count": null,
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
}Delete a lead
DELETE/api/v1/leads/{public_id}/
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
curl -X DELETE "https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.delete(
"https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.status_code)const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
method: "DELETE",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(resp.status);Bulk reassign owner
POST/api/v1/leads/bulk-assign/
Body
lead_idsarray of string (uuid)Required- All must be live leads of the organization, else 400.
assigned_to_idstring (uuid)Required- Public id of a member of the organization. Null is not accepted.
Response fields 3
updated_countintegerlead_idsarray of string (uuid)- Public ids of the leads reassigned (leads a non-admin cannot see under "Assigned only" visibility are left out).
assigned_to_idstring (uuid)- The new owner's public id, as sent.
curl -X POST "https://api.vivrecrm.com/api/v1/leads/bulk-assign/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"lead_ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"], "assigned_to_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/leads/bulk-assign/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"lead_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"assigned_to_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/bulk-assign/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"lead_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"assigned_to_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}),
});
console.log(await resp.json());{
"updated_count": 1,
"lead_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"assigned_to_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}Bulk status update
POST/api/v1/leads/bulk-update-status/
Body
lead_idsarray of string (uuid)Required- All must be live leads of the organization, else 400.
statusstringRequired- One of the organization's lead statuses (400 otherwise).
Response fields 5
updated_countintegerlead_idsarray of string (uuid)- Public ids of the leads updated.
statusstringskipped_countinteger- Present only when some leads were skipped (not assigned to the caller under
assigned_only). messagestring- Present only with
skipped_count.
curl -X POST "https://api.vivrecrm.com/api/v1/leads/bulk-update-status/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"lead_ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"], "status": "new"}'import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/leads/bulk-update-status/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"lead_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"status": "new"
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/bulk-update-status/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"lead_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"status": "new"
}),
});
console.log(await resp.json());{
"updated_count": 1,
"lead_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"status": "new",
"skipped_count": 1,
"message": ""
}Bulk soft-delete
POST/api/v1/leads/bulk-delete/
Body
idsarray of string (uuid)- Lead public ids. A value that is not a UUID is reported in failed.
lead_idsarray of string (uuid)- Older name for ids.
Response fields 4
deletedarray of string (uuid)- The ids that were deleted, as strings, in request order (duplicates removed).
deleted_countintegerfailedarray of object- Ids not deleted. An id that is not a UUID, is in another organization, is already deleted or is outside the caller's visibility is reported as "Not found.".
failed_countinteger
curl -X POST "https://api.vivrecrm.com/api/v1/leads/bulk-delete/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/leads/bulk-delete/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/bulk-delete/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(await resp.json());{
"deleted": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"deleted_count": 1,
"failed": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"reason": ""
}
],
"failed_count": 1
}Merge duplicate leads of one contact (lead.bulk_merge; owners and admins by default)
POST/api/v1/leads/bulk-merge/
The kept lead takes over the duplicates' deals, tasks, notes, activity, AI jobs, custom values (its own win) and tags; the duplicates are soft-deleted. Only leads of the same contact merge (400 otherwise). Sends lead.deleted.v1 per duplicate, deal.updated.v1 per moved deal and lead.merged.v1.
Body
primary_lead_idstring (uuid)Required- The lead to keep.
duplicate_lead_idsarray of string (uuid)Required- Must not contain the kept lead. All must be live leads of the same contact that the caller can see.
fieldsobject- Values to keep, checked as an edit of the kept lead is (400 with the lead's own errors). Only these keys are accepted.
Response fields 3
primary_lead_idstring (uuid)merged_countinteger- Duplicates merged in and soft-deleted.
leadobject
curl -X POST "https://api.vivrecrm.com/api/v1/leads/bulk-merge/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"primary_lead_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "duplicate_lead_ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]}'import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/leads/bulk-merge/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"primary_lead_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"duplicate_lead_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
]
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/bulk-merge/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"primary_lead_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"duplicate_lead_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
]
}),
});
console.log(await resp.json());{
"primary_lead_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"merged_count": 1,
"lead": {
"created_source": "api_key",
"created_source_label": "",
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"first_name": "Asha",
"last_name": "Rao",
"full_name": "Asha Rao",
"email": "[email protected]",
"phone": "9876543210",
"phone_country_code": "+91",
"job_title": "Head of Operations",
"whatsapp_number": "9876543210",
"whatsapp_country_code": "+91",
"company_name": null,
"company_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"lead_origin": "import",
"status": "new",
"source": "website",
"medium": "",
"channel": "",
"platform": "",
"campaign": "",
"priority": "",
"lead_date": "2026-10-31",
"score": 1,
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"tags": null,
"custom_fields": {},
"import_job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"is_potential_duplicate": true,
"duplicate_reason": "duplicate",
"notes_count": null,
"activities_count": null,
"deals_count": null,
"tasks_count": null,
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
}
}Add tags to many leads
POST/api/v1/leads/bulk-tag/
Body
entity_idsarray of string (uuid)Required- Public ids of the records. All must be live records of the organization, else 400.
tag_idstring (uuid)Required- The tag's public id.
Response fields 3
created_countinteger- Assignments added (records that already had the tag are not counted).
entity_idsarray of string (uuid)- Public ids of the records acted on, leaving out leads and deals the caller cannot see.
tag_idstring (uuid)
curl -X POST "https://api.vivrecrm.com/api/v1/leads/bulk-tag/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"entity_ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"], "tag_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/leads/bulk-tag/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"entity_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"tag_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/bulk-tag/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"entity_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"tag_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}),
});
console.log(await resp.json());{
"created_count": 1,
"entity_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"tag_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}Remove tags from many leads
POST/api/v1/leads/bulk-untag/
Body
entity_idsarray of string (uuid)Required- Public ids of the records. All must be live records of the organization, else 400.
tag_idstring (uuid)Required- The tag's public id.
Response fields 3
removed_countinteger- Tag assignments deleted.
entity_idsarray of string (uuid)- Public ids of the records acted on, leaving out leads and deals the caller cannot see.
tag_idstring (uuid)
curl -X POST "https://api.vivrecrm.com/api/v1/leads/bulk-untag/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"entity_ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"], "tag_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/leads/bulk-untag/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"entity_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"tag_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/bulk-untag/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"entity_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"tag_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}),
});
console.log(await resp.json());{
"removed_count": 1,
"entity_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"tag_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}Lead counts for the list header
GET/api/v1/leads/stats/
Response fields 5
totalintegeravg_scorenumber- Mean score rounded to 2 places; null when there are no leads.
mineinteger- Assigned to the caller.
unassignedintegerby_statusobject- Count per status. Every status in the organization's list appears (0 included), plus any stored status outside it.
curl "https://api.vivrecrm.com/api/v1/leads/stats/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/leads/stats/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/stats/", {
method: "GET",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(await resp.json());{
"total": 1,
"avg_score": 120000.0,
"mine": 1,
"unassigned": 1,
"by_status": {}
}Ids of every lead the list shows
GET/api/v1/leads/ids/
"Select all N matching". Takes the list's own query (search, filter (compound JSON) and ordering), and answers the public ids in the list's order, up to 10,000, with the total. Pass them in batches to the bulk actions.
Response fields 3
countinteger- Every match, which may be more than
limit. idsarray of string (uuid)- Public ids of the first
limitmatches, in the list's order. limitinteger- The most ids answered: 10,000.
curl "https://api.vivrecrm.com/api/v1/leads/ids/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/leads/ids/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/ids/", {
method: "GET",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(await resp.json());{
"count": 1,
"ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"limit": 1
}A lead's activity timeline
GET/api/v1/leads/{public_id}/activities/
Parameters
public_idpath, stringRequired
Response fields 19
sourceenumsource_labelstringidstring (uuid)organisationstring (uuid)entity_typeenumentity_idstringentity_public_idobjecttypeenumactor_typeenumcreated_by_uuidobjectcreated_by_usernameobjectcreated_by_first_nameobjectcreated_by_last_nameobjectcreated_by_nameobjectis_outboundbooleanresponse_time_secondsintegercontentstringcreated_atstring (date-time)emailobject
curl "https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/activities/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/activities/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/activities/", {
method: "GET",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(await resp.json());{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"source": "api_key",
"source_label": "",
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"entity_type": "Contact",
"entity_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"entity_public_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"type": "email_sent",
"actor_type": "human",
"created_by_uuid": null,
"created_by_username": null,
"created_by_first_name": null,
"created_by_last_name": null,
"created_by_name": null,
"is_outbound": true,
"response_time_seconds": 1,
"content": "Called, wants a demo on Friday.",
"created_at": "2026-10-17T09:30:00+05:30",
"email": "[email protected]"
}
]
}Restore a deleted lead
POST/api/v1/leads/{public_id}/restore/
Parameters
public_idpath, stringRequired
Response fields 31
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectlead_originenumstatusstringsourcestringmediumstringchannelstringplatformstringcampaignstringprioritystringlead_datestring (date)scoreintegerassigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjecttagsobjectcustom_fieldsobjectimport_job_idstring (uuid)is_potential_duplicatebooleanduplicate_reasonenumnotes_countobjectactivities_countobjectdeals_countobjecttasks_countobjectcreated_atstring (date-time)updated_atstring (date-time)
curl -X POST "https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/restore/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/restore/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/restore/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(await resp.json());{
"created_source": "api_key",
"created_source_label": "",
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"first_name": "Asha",
"last_name": "Rao",
"full_name": "Asha Rao",
"email": "[email protected]",
"phone": "9876543210",
"phone_country_code": "+91",
"job_title": "Head of Operations",
"whatsapp_number": "9876543210",
"whatsapp_country_code": "+91",
"company_name": null,
"company_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"lead_origin": "import",
"status": "new",
"source": "website",
"medium": "",
"channel": "",
"platform": "",
"campaign": "",
"priority": "",
"lead_date": "2026-10-31",
"score": 1,
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"tags": null,
"custom_fields": {},
"import_job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"is_potential_duplicate": true,
"duplicate_reason": "duplicate",
"notes_count": null,
"activities_count": null,
"deals_count": null,
"tasks_count": null,
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
}curl "https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/tags/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/tags/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/tags/", {
method: "GET",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(await resp.json());[
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"color_hex": "",
"created_at": "2026-10-17T09:30:00+05:30"
}
]Tag a lead
POST/api/v1/leads/{public_id}/tags/
Parameters
public_idpath, stringRequired
Body
tag_public_idstring (uuid)Required- A tag of the organization not already on this record (400 otherwise).
Response fields 5
idstring (uuid)organisationstring (uuid)namestringcolor_hexstringcreated_atstring (date-time)
curl -X POST "https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/tags/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"tag_public_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/tags/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"tag_public_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/tags/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"tag_public_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}),
});
console.log(await resp.json());{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"color_hex": "",
"created_at": "2026-10-17T09:30:00+05:30"
}Remove a tag from a lead
DELETE/api/v1/leads/{public_id}/tags/{tag_id}/
Parameters
public_idpath, stringRequiredtag_idpath, stringRequired
curl -X DELETE "https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/tags/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.delete(
"https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/tags/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.status_code)const resp = await fetch("https://api.vivrecrm.com/api/v1/leads/7c9e6679-7425-40de-944b-e07fc1f90ae7/tags/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
method: "DELETE",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(resp.status);