Deals
Opportunities in a pipeline: stages, values, won and lost.
List deals
GET/api/v1/deals/
Parameters
cursorquery, string- Opaque pagination cursor (follow next/previous URLs).
searchquery, stringorderingquery, string- A column of the list,
-for descending: assigned_to__first_name,closed_at, contact__first_name,created_at, currency,expected_close_date,last_activity_at, pipeline__name, stage__name, status, title,updated_at, value; orcf__<custom field>on the paged route. Anything else is a 400. Default-created_at. statusquery, stringopen(the default),won,lost,abandoned, orall.filterquery, string- The filter panel's compound filter, as JSON: {op, conditions}. Fields from GET filter-fields/deal/.
pipeline_idquery, string- Pipeline public id.
stage_idquery, string- Stage public id.
stagequery, string- Stage name.
owner_idquery, string- Owner (user) public id.
tag_idquery, string- Tag public id.
lead_idquery, string- The lead's deals.
contact_idquery, string- The contact's deals; one from elsewhere lists nothing.
drawquery, integer- When present, answers the paged list,
{draw, recordsTotal, recordsFiltered, data}, paged bystartandlengthinstead of the cursor envelope.recordsTotalcounts every deal the caller may see. startquery, integer- Paged list: offset (default 0).
lengthquery, integer- Paged list: rows (default 50, max 500).
Response fields 25
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectleadobjectpipelineobjectstageobjecttitlestringstatusenumvaluestringcurrencystringexpected_close_datestring (date)closed_atstring (date)lost_reasonstringlast_activity_atstring (date-time)assigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjectstage_namestringcreated_atstring (date-time)updated_atstring (date-time)custom_fieldsobject
curl "https://api.vivrecrm.com/api/v1/deals/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/deals/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/", {
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": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"lead_origin": "import",
"source": "website",
"status": "new",
"score": 1,
"created_at": "2026-10-17T09:30:00+05:30"
},
"pipeline": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"is_default": true,
"stages": [],
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
},
"stage": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
},
"title": "Kaveri Foods renewal",
"status": "open",
"value": "",
"currency": "INR",
"expected_close_date": "2026-10-31",
"closed_at": "2026-10-17T09:30:00+05:30",
"lost_reason": "",
"last_activity_at": "2026-10-17T09:30:00+05:30",
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"stage_name": "",
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30",
"custom_fields": {}
}
]
}Create deal
POST/api/v1/deals/
Parameters
Idempotency-Keyheader, string- Unique key for safe retries (24h replay window).
Body
titlestringRequiredcontact_idstring, can be nulllead_idstring, can be nullpipeline_idstringstage_idstringvaluestring, can be nullcurrencystringexpected_close_datestring (date), can be nullassigned_to_idstring, can be nullcustom_fieldsobject
Response fields 25
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectleadobjectpipelineobjectstageobjecttitlestringstatusenumvaluestringcurrencystringexpected_close_datestring (date)closed_atstring (date)lost_reasonstringlast_activity_atstring (date-time)assigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjectstage_namestringcreated_atstring (date-time)updated_atstring (date-time)custom_fieldsobject
curl -X POST "https://api.vivrecrm.com/api/v1/deals/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Kaveri Foods renewal", "currency": "INR"}'import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/deals/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"title": "Kaveri Foods renewal",
"currency": "INR"
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"title": "Kaveri Foods renewal",
"currency": "INR"
}),
});
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": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"lead_origin": "import",
"source": "website",
"status": "new",
"score": 1,
"created_at": "2026-10-17T09:30:00+05:30"
},
"pipeline": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"is_default": true,
"stages": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
}
],
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
},
"stage": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
},
"title": "Kaveri Foods renewal",
"status": "open",
"value": "",
"currency": "INR",
"expected_close_date": "2026-10-31",
"closed_at": "2026-10-17T09:30:00+05:30",
"lost_reason": "",
"last_activity_at": "2026-10-17T09:30:00+05:30",
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"stage_name": "",
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30",
"custom_fields": {}
}Retrieve a deal
GET/api/v1/deals/{public_id}/
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
Response fields 25
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectleadobjectpipelineobjectstageobjecttitlestringstatusenumvaluestringcurrencystringexpected_close_datestring (date)closed_atstring (date)lost_reasonstringlast_activity_atstring (date-time)assigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjectstage_namestringcreated_atstring (date-time)updated_atstring (date-time)custom_fieldsobject
curl "https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/deals/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/deals/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": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"lead_origin": "import",
"source": "website",
"status": "new",
"score": 1,
"created_at": "2026-10-17T09:30:00+05:30"
},
"pipeline": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"is_default": true,
"stages": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
}
],
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
},
"stage": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
},
"title": "Kaveri Foods renewal",
"status": "open",
"value": "",
"currency": "INR",
"expected_close_date": "2026-10-31",
"closed_at": "2026-10-17T09:30:00+05:30",
"lost_reason": "",
"last_activity_at": "2026-10-17T09:30:00+05:30",
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"stage_name": "",
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30",
"custom_fields": {}
}Replace a deal
PUT/api/v1/deals/{public_id}/
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
Body
titlestringRequiredcontact_idstring, can be nulllead_idstring, can be nullpipeline_idstringstage_idstringvaluestring, can be nullcurrencystringexpected_close_datestring (date), can be nullassigned_to_idstring, can be nullcustom_fieldsobject
Response fields 25
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectleadobjectpipelineobjectstageobjecttitlestringstatusenumvaluestringcurrencystringexpected_close_datestring (date)closed_atstring (date)lost_reasonstringlast_activity_atstring (date-time)assigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjectstage_namestringcreated_atstring (date-time)updated_atstring (date-time)custom_fieldsobject
curl -X PUT "https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Kaveri Foods renewal", "currency": "INR"}'import os, requests
resp = requests.put(
"https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"title": "Kaveri Foods renewal",
"currency": "INR"
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
method: "PUT",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"title": "Kaveri Foods renewal",
"currency": "INR"
}),
});
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": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"lead_origin": "import",
"source": "website",
"status": "new",
"score": 1,
"created_at": "2026-10-17T09:30:00+05:30"
},
"pipeline": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"is_default": true,
"stages": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
}
],
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
},
"stage": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
},
"title": "Kaveri Foods renewal",
"status": "open",
"value": "",
"currency": "INR",
"expected_close_date": "2026-10-31",
"closed_at": "2026-10-17T09:30:00+05:30",
"lost_reason": "",
"last_activity_at": "2026-10-17T09:30:00+05:30",
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"stage_name": "",
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30",
"custom_fields": {}
}Update a deal
PATCH/api/v1/deals/{public_id}/
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
Body
titlestringRequiredcontact_idstring, can be nulllead_idstring, can be nullpipeline_idstringstage_idstringvaluestring, can be nullcurrencystringexpected_close_datestring (date), can be nullassigned_to_idstring, can be nullcustom_fieldsobject
Response fields 25
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectleadobjectpipelineobjectstageobjecttitlestringstatusenumvaluestringcurrencystringexpected_close_datestring (date)closed_atstring (date)lost_reasonstringlast_activity_atstring (date-time)assigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjectstage_namestringcreated_atstring (date-time)updated_atstring (date-time)custom_fieldsobject
curl -X PATCH "https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Kaveri Foods renewal", "currency": "INR"}'import os, requests
resp = requests.patch(
"https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"title": "Kaveri Foods renewal",
"currency": "INR"
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
method: "PATCH",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"title": "Kaveri Foods renewal",
"currency": "INR"
}),
});
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": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"lead_origin": "import",
"source": "website",
"status": "new",
"score": 1,
"created_at": "2026-10-17T09:30:00+05:30"
},
"pipeline": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"is_default": true,
"stages": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
}
],
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
},
"stage": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
},
"title": "Kaveri Foods renewal",
"status": "open",
"value": "",
"currency": "INR",
"expected_close_date": "2026-10-31",
"closed_at": "2026-10-17T09:30:00+05:30",
"lost_reason": "",
"last_activity_at": "2026-10-17T09:30:00+05:30",
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"stage_name": "",
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30",
"custom_fields": {}
}Delete a deal
DELETE/api/v1/deals/{public_id}/
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
curl -X DELETE "https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.delete(
"https://api.vivrecrm.com/api/v1/deals/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/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
method: "DELETE",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(resp.status);Mark deal won
POST/api/v1/deals/{public_id}/won/
Moves the deal into its pipeline's Won stage and closes it. Works on an open deal, and on a Lost or Abandoned one, which is closed again as won. Needs the permission to mark deals won or lost (deal.won_lost).
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
Body
closed_atstring (date)- Close date, not in the future (organization's date). Default today in the organization's time zone.
Response fields 25
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectleadobjectpipelineobjectstageobjecttitlestringstatusenumvaluestringcurrencystringexpected_close_datestring (date)closed_atstring (date)lost_reasonstringlast_activity_atstring (date-time)assigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjectstage_namestringcreated_atstring (date-time)updated_atstring (date-time)custom_fieldsobject
Can also return 400, 409.
curl -X POST "https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/won/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/won/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/won/", {
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": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"lead_origin": "import",
"source": "website",
"status": "new",
"score": 1,
"created_at": "2026-10-17T09:30:00+05:30"
},
"pipeline": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"is_default": true,
"stages": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
}
],
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
},
"stage": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
},
"title": "Kaveri Foods renewal",
"status": "open",
"value": "",
"currency": "INR",
"expected_close_date": "2026-10-31",
"closed_at": "2026-10-17T09:30:00+05:30",
"lost_reason": "",
"last_activity_at": "2026-10-17T09:30:00+05:30",
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"stage_name": "",
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30",
"custom_fields": {}
}Mark deal lost
POST/api/v1/deals/{public_id}/lost/
Moves the deal into its pipeline's Lost stage and closes it, with an optional reason. Needs the permission to mark deals won or lost (deal.won_lost).
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
Body
reasonstring- Why it was lost or abandoned (stored as
lost_reason). Default empty. closed_atstring (date)- Close date, not in the future. Default today in the organization's time zone.
Response fields 25
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectleadobjectpipelineobjectstageobjecttitlestringstatusenumvaluestringcurrencystringexpected_close_datestring (date)closed_atstring (date)lost_reasonstringlast_activity_atstring (date-time)assigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjectstage_namestringcreated_atstring (date-time)updated_atstring (date-time)custom_fieldsobject
Can also return 400, 409.
curl -X POST "https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/lost/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/lost/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/lost/", {
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": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"lead_origin": "import",
"source": "website",
"status": "new",
"score": 1,
"created_at": "2026-10-17T09:30:00+05:30"
},
"pipeline": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"is_default": true,
"stages": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
}
],
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
},
"stage": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
},
"title": "Kaveri Foods renewal",
"status": "open",
"value": "",
"currency": "INR",
"expected_close_date": "2026-10-31",
"closed_at": "2026-10-17T09:30:00+05:30",
"lost_reason": "",
"last_activity_at": "2026-10-17T09:30:00+05:30",
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"stage_name": "",
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30",
"custom_fields": {}
}Mark deal abandoned
POST/api/v1/deals/{public_id}/abandoned/
Moves the deal into its pipeline's Abandoned stage and closes it, with an optional reason. Needs the permission to mark deals won or lost (deal.won_lost).
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
Body
reasonstring- Why it was lost or abandoned (stored as
lost_reason). Default empty. closed_atstring (date)- Close date, not in the future. Default today in the organization's time zone.
Response fields 25
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectleadobjectpipelineobjectstageobjecttitlestringstatusenumvaluestringcurrencystringexpected_close_datestring (date)closed_atstring (date)lost_reasonstringlast_activity_atstring (date-time)assigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjectstage_namestringcreated_atstring (date-time)updated_atstring (date-time)custom_fieldsobject
Can also return 400, 409.
curl -X POST "https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/abandoned/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/abandoned/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/abandoned/", {
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": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"lead_origin": "import",
"source": "website",
"status": "new",
"score": 1,
"created_at": "2026-10-17T09:30:00+05:30"
},
"pipeline": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"is_default": true,
"stages": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
}
],
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
},
"stage": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
},
"title": "Kaveri Foods renewal",
"status": "open",
"value": "",
"currency": "INR",
"expected_close_date": "2026-10-31",
"closed_at": "2026-10-17T09:30:00+05:30",
"lost_reason": "",
"last_activity_at": "2026-10-17T09:30:00+05:30",
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"stage_name": "",
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30",
"custom_fields": {}
}Reopen a closed deal
POST/api/v1/deals/{public_id}/reopen/
Moves a closed deal back to the open stage it closed from, or to its pipeline's last open stage, and clears the close date and reason. Needs the permission to mark deals won or lost (deal.won_lost).
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
Response fields 25
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectleadobjectpipelineobjectstageobjecttitlestringstatusenumvaluestringcurrencystringexpected_close_datestring (date)closed_atstring (date)lost_reasonstringlast_activity_atstring (date-time)assigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjectstage_namestringcreated_atstring (date-time)updated_atstring (date-time)custom_fieldsobject
Can also return 400, 409.
curl -X POST "https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/reopen/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/reopen/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/reopen/", {
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": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"lead_origin": "import",
"source": "website",
"status": "new",
"score": 1,
"created_at": "2026-10-17T09:30:00+05:30"
},
"pipeline": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"is_default": true,
"stages": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
}
],
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
},
"stage": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
},
"title": "Kaveri Foods renewal",
"status": "open",
"value": "",
"currency": "INR",
"expected_close_date": "2026-10-31",
"closed_at": "2026-10-17T09:30:00+05:30",
"lost_reason": "",
"last_activity_at": "2026-10-17T09:30:00+05:30",
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"stage_name": "",
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30",
"custom_fields": {}
}List participants
GET/api/v1/deals/{public_id}/participants/
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
curl "https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/participants/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/participants/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/participants/", {
method: "GET",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(await resp.json());[
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact_public_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact_name": "",
"role": "Champion",
"created_at": "2026-10-17T09:30:00+05:30"
}
]Add participant
POST/api/v1/deals/{public_id}/participants/
Parameters
public_idpath, stringRequired- The record's public id (a UUID).
Body
rolestringRequired- One of the participant roles (see /deals/participant-roles/), matched in any case.
contact_uuidstring (uuid)- Alternate key, read only when
contact_idis not sent.
Response fields 6
idstring (uuid)contact_idstring- The contact's integer primary key, rendered as a string.
contact_public_idstring (uuid)contact_namestringroleenumcreated_atstring (date-time)
curl -X POST "https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/participants/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"role": ""}'import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/participants/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"role": ""
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/participants/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"role": ""
}),
});
console.log(await resp.json());{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact_public_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact_name": "",
"role": "Champion",
"created_at": "2026-10-17T09:30:00+05:30"
}The roles a deal participant may have
GET/api/v1/deals/participant-roles/
curl "https://api.vivrecrm.com/api/v1/deals/participant-roles/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/deals/participant-roles/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/participant-roles/", {
method: "GET",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(await resp.json());[
{
"value": "Champion",
"label": ""
}
]Bulk move stage
POST/api/v1/deals/bulk-move-stage/
The target stage decides each deal's status: Won, Lost or Abandoned closes the deals (for Lost and Abandoned the reason, if given, is kept as lost_reason), and an open stage reopens closed ones. Moving deals into or out of a closed stage also needs the permission to mark deals won or lost (deal.won_lost).
Body
deal_idsarray of string (uuid)Required- All must be live deals of the organization in the stage's pipeline, else 400.
stage_idstring (uuid)Requiredreasonstring- Written as the activity line on each deal; default "Deal stage moved to <stage>".
Response fields 5
updated_countinteger- Deals moved. The target stage decides the status: Won, Lost or Abandoned closes them, and an open stage reopens closed ones.
skipped_countinteger- Always 0; kept for older clients (closed deals used to be left where they were).
deal_idsarray of string (uuid)- Public ids of the deals moved.
stage_idstring (uuid)stage_namestring
curl -X POST "https://api.vivrecrm.com/api/v1/deals/bulk-move-stage/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"deal_ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"], "stage_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/deals/bulk-move-stage/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"deal_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"stage_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/bulk-move-stage/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"deal_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"stage_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}),
});
console.log(await resp.json());{
"updated_count": 1,
"skipped_count": 1,
"deal_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"stage_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"stage_name": ""
}Ids of every deal the list shows
GET/api/v1/deals/ids/
"Select all N matching". Takes the list's own query (search, status (open by default; all, won, lost), stage, pipeline, owner and tag), 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/deals/ids/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/deals/ids/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/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
}Deal counts and values for the list's cards
GET/api/v1/deals/stats/
Response fields 6
totalintegeropenintegeropen_valueobject- Currency -> value of the open deals.
won_this_monthinteger- Won, closed this month.
won_value_this_monthobject- Currency -> value of those.
closing_this_monthinteger- Open, expected to close this month.
curl "https://api.vivrecrm.com/api/v1/deals/stats/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/deals/stats/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/stats/", {
method: "GET",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(await resp.json());{
"total": 1,
"open": 1,
"open_value": {},
"won_this_month": 1,
"won_value_this_month": {},
"closing_this_month": 1
}Bulk reassign owner
POST/api/v1/deals/bulk-assign/
Needs deal.bulk_assign (admins by default). Emits deal.assigned / deal.unassigned per deal whose owner changed and tells the new owner once.
Parameters
Idempotency-Keyheader, string- Unique key for safe retries (24h replay window).
Body
deal_idsarray of string (uuid)Required- All must be live deals 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_countintegerdeal_idsarray of string (uuid)- Public ids of the deals reassigned (deals 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/deals/bulk-assign/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"deal_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/deals/bulk-assign/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"deal_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/deals/bulk-assign/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"deal_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"assigned_to_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}),
});
console.log(await resp.json());{
"updated_count": 1,
"deal_ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
],
"assigned_to_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}Bulk soft-delete
POST/api/v1/deals/bulk-delete/
Needs deal.bulk_delete (admins by default). Best-effort, per id.
Body
idsarray of string (uuid)Required- Deal public ids. A value that is not a UUID is reported in failed.
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/deals/bulk-delete/" \
-H "X-Api-Key: $VIVRE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]}'import os, requests
resp = requests.post(
"https://api.vivrecrm.com/api/v1/deals/bulk-delete/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
json={
"ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
]
},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/bulk-delete/", {
method: "POST",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"ids": [
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
]
}),
});
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
}Add tags to many deals
POST/api/v1/deals/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/deals/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/deals/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/deals/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 deals
POST/api/v1/deals/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/deals/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/deals/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/deals/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"
}A deal's activity timeline
GET/api/v1/deals/{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/deals/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/deals/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/deals/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]"
}
]
}Company links made before deals stopped linking to companies (read only)
GET/api/v1/deals/{public_id}/companies/
Parameters
public_idpath, stringRequired
curl "https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/companies/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.get(
"https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/companies/",
headers={"X-Api-Key": os.environ["VIVRE_API_KEY"]},
)
print(resp.json())const resp = await fetch("https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/companies/", {
method: "GET",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(await resp.json());[
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"company": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods"
},
"created_at": "2026-10-17T09:30:00+05:30"
}
]Remove a participant from a deal
DELETE/api/v1/deals/{public_id}/participants/{participant_id}/
Parameters
public_idpath, stringRequiredparticipant_idpath, stringRequired
curl -X DELETE "https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/participants/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
-H "X-Api-Key: $VIVRE_API_KEY"import os, requests
resp = requests.delete(
"https://api.vivrecrm.com/api/v1/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/participants/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/deals/7c9e6679-7425-40de-944b-e07fc1f90ae7/participants/7c9e6679-7425-40de-944b-e07fc1f90ae7/", {
method: "DELETE",
headers: {
"X-Api-Key": process.env.VIVRE_API_KEY,
},
});
console.log(resp.status);Restore a deleted deal
POST/api/v1/deals/{public_id}/restore/
Parameters
public_idpath, stringRequired
Response fields 25
created_sourceenumcreated_source_labelstringidstring (uuid)organisationstring (uuid)contactobjectleadobjectpipelineobjectstageobjecttitlestringstatusenumvaluestringcurrencystringexpected_close_datestring (date)closed_atstring (date)lost_reasonstringlast_activity_atstring (date-time)assigned_to_uuidobjectassigned_to_usernameobjectassigned_to_first_nameobjectassigned_to_last_nameobjectassigned_to_nameobjectstage_namestringcreated_atstring (date-time)updated_atstring (date-time)custom_fieldsobject
curl -X POST "https://api.vivrecrm.com/api/v1/deals/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/deals/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/deals/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": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"lead_origin": "import",
"source": "website",
"status": "new",
"score": 1,
"created_at": "2026-10-17T09:30:00+05:30"
},
"pipeline": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"is_default": true,
"stages": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
}
],
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30"
},
"stage": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Kaveri Foods",
"order": 1,
"probability": 1,
"stage_type": "open",
"color": "",
"created_at": "2026-10-17T09:30:00+05:30"
},
"title": "Kaveri Foods renewal",
"status": "open",
"value": "",
"currency": "INR",
"expected_close_date": "2026-10-31",
"closed_at": "2026-10-17T09:30:00+05:30",
"lost_reason": "",
"last_activity_at": "2026-10-17T09:30:00+05:30",
"assigned_to_uuid": null,
"assigned_to_username": null,
"assigned_to_first_name": null,
"assigned_to_last_name": null,
"assigned_to_name": null,
"stage_name": "",
"created_at": "2026-10-17T09:30:00+05:30",
"updated_at": "2026-10-17T09:30:00+05:30",
"custom_fields": {}
}curl "https://api.vivrecrm.com/api/v1/deals/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/deals/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/deals/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 deal
POST/api/v1/deals/{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/deals/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/deals/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/deals/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 deal
DELETE/api/v1/deals/{public_id}/tags/{tag_id}/
Parameters
public_idpath, stringRequiredtag_idpath, stringRequired
curl -X DELETE "https://api.vivrecrm.com/api/v1/deals/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/deals/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/deals/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);