Skip to content

Dashboard & Search

Summary numbers, pipeline totals and search across records.

18 endpoints. Every request needs an X-Api-Key header.

Global search

POST/api/v1/search/

Searches the text of contacts, leads, deals, companies and notes, best match first. created_by, a member's public id, finds what that person wrote or did (their notes, including notes on tasks, and their activity), with or without q; send q, created_by or both. Activity is searched when entity_types names it, and by default with created_by. A person narrows only notes and activity, so naming another entity type together with created_by is a 400. Results respect what the caller may see (for example, lead visibility set to "Assigned only").

Body

qstring
entity_typesarray of enum
created_bystring (uuid)
A member's public id (user_id); never an integer.
Response fields 8
qstring
The query, trimmed.
created_bystring (uuid)
The member searched for, as given; null without one.
totalinteger
Rows returned across all types (each type capped at limit), not the true match count.
resultsobject
One list per searched entity type, each at most limit rows.
countsobject
True number of matches per searched entity type, ignoring the cap.
total_matchesinteger
Sum of counts.
limitinteger
The most results returned per entity type (currently 20).
truncatedboolean
True when any entity type had more matches than were returned.
curl -X POST "https://api.vivrecrm.com/api/v1/search/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
{
  "q": "",
  "created_by": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "total": 1,
  "results": {
    "Contact": [
      {
        "created_source": "api_key",
        "created_source_label": "",
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "company": {},
        "first_name": "Asha",
        "last_name": "Rao",
        "full_name": "Asha Rao",
        "job_title": "Head of Operations",
        "email": "[email protected]",
        "email_secondary": "[email protected]",
        "phone_country_code": "+91",
        "phone": "9876543210",
        "phone_secondary_country_code": "",
        "phone_secondary": "",
        "whatsapp_country_code": "+91",
        "whatsapp_number": "9876543210",
        "opted_out_channels": {},
        "last_activity_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",
        "created_by_uuid": null,
        "created_by_username": null,
        "created_by_first_name": null,
        "created_by_last_name": null,
        "created_by_name": null,
        "custom_fields": {}
      }
    ],
    "Lead": [
      {
        "created_source": "api_key",
        "created_source_label": "",
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "contact": {},
        "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"
      }
    ],
    "Deal": [
      {
        "created_source": "api_key",
        "created_source_label": "",
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "contact": {},
        "lead": {},
        "pipeline": {},
        "stage": {},
        "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": {}
      }
    ],
    "Company": [
      {
        "created_source": "api_key",
        "created_source_label": "",
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "organisation": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "name": "Kaveri Foods",
        "contacts_count": null,
        "industry": "",
        "size": "1-10",
        "phone_country_code": "+91",
        "phone": "9876543210",
        "email": "[email protected]",
        "website": "https://kaverifoods.in",
        "linkedin_url": "",
        "company_type": "",
        "owner_uuid": null,
        "owner_name": null,
        "street": "",
        "city": "Hyderabad",
        "state": "",
        "postal_code": "",
        "country": "India",
        "gstin": "",
        "pan": "",
        "annual_revenue": "",
        "annual_revenue_currency": "",
        "employee_count": 1,
        "description": "Annual plan for the Hyderabad team.",
        "founded_year": 1,
        "parent_company": null,
        "tags": null,
        "last_activity_at": "2026-10-17T09:30:00+05:30",
        "created_by_uuid": null,
        "created_by_username": null,
        "created_by_first_name": null,
        "created_by_last_name": null,
        "created_by_name": null,
        "created_at": "2026-10-17T09:30:00+05:30",
        "updated_at": "2026-10-17T09:30:00+05:30",
        "custom_fields": {}
      }
    ],
    "Note": [
      {
        "created_source": "api_key",
        "created_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",
        "content": "Called, wants a demo on Friday.",
        "created_by_uuid": null,
        "created_by_username": null,
        "created_by_first_name": null,
        "created_by_last_name": null,
        "created_by_name": null,
        "edited_by": 1,
        "edited_by_uuid": null,
        "edited_by_username": null,
        "edited_by_first_name": null,
        "edited_by_last_name": null,
        "edited_by_name": null,
        "edited_at": "2026-10-17T09:30:00+05:30",
        "is_ai_generated": true,
        "slash_commands": null,
        "created_at": "2026-10-17T09:30:00+05:30",
        "updated_at": "2026-10-17T09:30:00+05:30"
      }
    ],
    "Activity": [
      {
        "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]"
      }
    ]
  },
  "counts": {
    "Contact": 1,
    "Lead": 1,
    "Deal": 1,
    "Company": 1,
    "Note": 1,
    "Activity": 1
  },
  "total_matches": 1,
  "limit": 1,
  "truncated": true
}

Filter field metadata

GET/api/v1/filter-fields/{entity}/

Parameters

entitypath, stringRequired
Response fields 2
entityenum
The entity, capitalised.
fieldsarray of object
curl "https://api.vivrecrm.com/api/v1/filter-fields/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
{
  "entity": "Lead",
  "fields": [
    {
      "key": "",
      "label": "",
      "type": "string",
      "group": "",
      "choices": [],
      "is_custom": true,
      "can_be_empty": true,
      "field_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    }
  ]
}

A list's quick-view chips and default columns

GET/api/v1/list-views/{list_name}/

The quick-view chips shown above a list, each with the filter value it stands for (worked out now, in the organization's time zone, with "mine" written as "@me"), and the list's columns in their default order. Any member may read it.

Parameters

list_namepath, enumRequired
Response fields 3
liststring
quick_viewsarray of object
columnsarray of object

Can also return 404.

curl "https://api.vivrecrm.com/api/v1/list-views/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
{
  "list": "",
  "quick_views": [
    {
      "key": "",
      "label": "",
      "filter": {}
    }
  ],
  "columns": [
    {
      "key": "",
      "label": "",
      "group": "",
      "visible": true,
      "locked": true
    }
  ]
}

Dashboard summary

GET/api/v1/dashboard/summary/

Response fields 13
pipeline_value_by_currencyobject
Map of currency code to summed deal value in that currency. Never summed across currencies.
deals_openinteger
deals_won_this_monthinteger
Deals won in the selected period (named for the default 30d window).
deals_lost_this_monthinteger
Deals lost in the selected period.
win_ratenumber
Won / (won + lost) in the period, as a percentage rounded to 1 dp; 0.0 when none closed.
tasks_due_todayinteger
contacts_totalinteger
leads_totalinteger
total_companiesinteger
period_startstring (date)
time_rangeenum
Present only when no from_date/to_date were given.
from_datestring (date)
Present only for a custom range.
to_datestring (date)
Present only for a custom range.
curl "https://api.vivrecrm.com/api/v1/dashboard/summary/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
{
  "pipeline_value_by_currency": {},
  "deals_open": 1,
  "deals_won_this_month": 1,
  "deals_lost_this_month": 1,
  "win_rate": 120000.0,
  "tasks_due_today": 1,
  "contacts_total": 1,
  "leads_total": 1,
  "total_companies": 1,
  "period_start": "2026-10-31",
  "time_range": "today",
  "from_date": "2026-10-31",
  "to_date": "2026-10-31"
}

Pipeline by stage

GET/api/v1/dashboard/pipeline-by-stage/

curl "https://api.vivrecrm.com/api/v1/dashboard/pipeline-by-stage/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
[
  {
    "stage_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "stage_name": "",
    "pipeline_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "order": 1,
    "deal_count": 1,
    "deal_value_by_currency": {}
  }
]

Activity feed

GET/api/v1/dashboard/activity-feed/

curl "https://api.vivrecrm.com/api/v1/dashboard/activity-feed/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
[
  {
    "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]"
  }
]

Leads by source for a date range

GET/api/v1/dashboard/leads-by-source/

Response fields 2
sourcestring
Source label; leads with no source are grouped under "Unknown".
countinteger
curl "https://api.vivrecrm.com/api/v1/dashboard/leads-by-source/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
{
  "results": [
    {
      "source": "website",
      "count": 1
    }
  ],
  "time_range": "today",
  "period_start": "2026-10-31"
}

Scheduled reports

GET/api/v1/reports/

curl "https://api.vivrecrm.com/api/v1/reports/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
[
  {
    "public_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Kaveri Foods",
    "is_active": true,
    "columns": [
      {
        "field": "",
        "label": "",
        "visible": true,
        "order": 1
      }
    ],
    "filters": null,
    "cadence": "daily",
    "window": "24h",
    "send_hour": 1,
    "recipient_type": "org",
    "specific_users": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "email": "[email protected]",
        "display_name": ""
      }
    ],
    "last_run_at": "2026-10-17T09:30:00+05:30",
    "last_log": null,
    "created_at": "2026-10-17T09:30:00+05:30",
    "updated_at": "2026-10-17T09:30:00+05:30"
  }
]

Create a scheduled report

POST/api/v1/reports/

Body

namestringRequired
cadenceenumRequired
One of daily, weekly, monthly, manual.
is_activeboolean
columnsarray of object
filtersobject
A list of conditions (all must match) or a nested AND/OR/NOT group.
windowenum
One of 24h, 7d, 30d, mtd, all.
send_hourinteger
recipient_typeenum
One of org, admins, specific_users.
specific_user_idsarray of string (uuid)
User public ids; required (non-empty) when recipient_type is specific_users. Non-members are dropped silently.
Response fields 14
public_idstring (uuid)
namestring
is_activeboolean
columnsarray of object
filtersobject
A list of conditions (all must match) or a nested AND/OR/NOT group.
cadenceenum
windowenum
send_hourinteger
Hour on the organization's local clock.
recipient_typeenum
specific_usersarray of object
last_run_atstring (date-time)
last_logobject
created_atstring (date-time)
updated_atstring (date-time)
curl -X POST "https://api.vivrecrm.com/api/v1/reports/" \
  -H "X-Api-Key: $VIVRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kaveri Foods", "cadence": "daily"}'
Response 201
{
  "public_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Kaveri Foods",
  "is_active": true,
  "columns": [
    {
      "field": "",
      "label": "",
      "visible": true,
      "order": 1
    }
  ],
  "filters": null,
  "cadence": "daily",
  "window": "24h",
  "send_hour": 1,
  "recipient_type": "org",
  "specific_users": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "email": "[email protected]",
      "display_name": ""
    }
  ],
  "last_run_at": "2026-10-17T09:30:00+05:30",
  "last_log": null,
  "created_at": "2026-10-17T09:30:00+05:30",
  "updated_at": "2026-10-17T09:30:00+05:30"
}

A report download's progress

GET/api/v1/reports/downloads/{download_id}/

Parameters

download_idpath, stringRequired
Response fields 5
statusenum
row_countinteger
errorstring
expires_atstring (date-time)
urlstring
/api/v1/reports/downloads/{id}/file/?token=... when ready, else null.
curl "https://api.vivrecrm.com/api/v1/reports/downloads/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
{
  "status": "pending",
  "row_count": 1,
  "error": "",
  "expires_at": "2026-10-17T09:30:00+05:30",
  "url": ""
}

Download a finished report file

GET/api/v1/reports/downloads/{download_id}/file/

Parameters

download_idpath, stringRequired
curl "https://api.vivrecrm.com/api/v1/reports/downloads/7c9e6679-7425-40de-944b-e07fc1f90ae7/file/" \
  -H "X-Api-Key: $VIVRE_API_KEY"

Scheduled reports that are failing

GET/api/v1/reports/health/

Response fields 4
activeinteger
Active reports in the organization.
failed_7dinteger
partial_7dinteger
last_failureobject
Latest failed or partial run in the last 7 days, or null.
curl "https://api.vivrecrm.com/api/v1/reports/health/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
{
  "active": 1,
  "failed_7d": 1,
  "partial_7d": 1,
  "last_failure": null
}

Report builder fields

GET/api/v1/reports/schema/

The columns, filter-only fields and operators a scheduled report can use. Admins only.

Response fields 3
column_fieldsarray of object
filter_only_fieldsarray of object
filter_opsobject
Map of op name to its metadata. Keys: eq, neq, contains, gt, lt, gte, lte, in, not_in, is_null, is_not_null.
curl "https://api.vivrecrm.com/api/v1/reports/schema/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
{
  "column_fields": [
    {
      "key": "",
      "entity": "lead",
      "field": "",
      "label": "",
      "type": "text",
      "options": [],
      "filterable": true,
      "filter_key": "",
      "filter_ops": [],
      "custom": true,
      "required": true,
      "field_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    }
  ],
  "filter_only_fields": [
    {
      "key": "",
      "entity": "lead",
      "field": "",
      "label": "",
      "type": "user_id",
      "options": [],
      "filter_ops": []
    }
  ],
  "filter_ops": {}
}

Retrieve a scheduled report

GET/api/v1/reports/{report_id}/

Parameters

report_idpath, stringRequired
Response fields 14
public_idstring (uuid)
namestring
is_activeboolean
columnsarray of object
filtersobject
A list of conditions (all must match) or a nested AND/OR/NOT group.
cadenceenum
windowenum
send_hourinteger
Hour on the organization's local clock.
recipient_typeenum
specific_usersarray of object
last_run_atstring (date-time)
last_logobject
created_atstring (date-time)
updated_atstring (date-time)
curl "https://api.vivrecrm.com/api/v1/reports/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
{
  "public_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Kaveri Foods",
  "is_active": true,
  "columns": [
    {
      "field": "",
      "label": "",
      "visible": true,
      "order": 1
    }
  ],
  "filters": null,
  "cadence": "daily",
  "window": "24h",
  "send_hour": 1,
  "recipient_type": "org",
  "specific_users": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "email": "[email protected]",
      "display_name": ""
    }
  ],
  "last_run_at": "2026-10-17T09:30:00+05:30",
  "last_log": null,
  "created_at": "2026-10-17T09:30:00+05:30",
  "updated_at": "2026-10-17T09:30:00+05:30"
}

Update a scheduled report

PATCH/api/v1/reports/{report_id}/

Parameters

report_idpath, stringRequired

Body

namestring
is_activeboolean
columnsarray of object
filtersobject
A list of conditions (all must match) or a nested AND/OR/NOT group.
cadenceenum
One of daily, weekly, monthly, manual.
windowenum
One of 24h, 7d, 30d, mtd, all.
send_hourinteger
recipient_typeenum
One of org, admins, specific_users.
specific_user_idsarray of string (uuid)
User public ids; required (non-empty) when recipient_type is specific_users. Non-members are dropped silently.
Response fields 14
public_idstring (uuid)
namestring
is_activeboolean
columnsarray of object
filtersobject
A list of conditions (all must match) or a nested AND/OR/NOT group.
cadenceenum
windowenum
send_hourinteger
Hour on the organization's local clock.
recipient_typeenum
specific_usersarray of object
last_run_atstring (date-time)
last_logobject
created_atstring (date-time)
updated_atstring (date-time)
curl -X PATCH "https://api.vivrecrm.com/api/v1/reports/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kaveri Foods"}'
Response 200
{
  "public_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Kaveri Foods",
  "is_active": true,
  "columns": [
    {
      "field": "",
      "label": "",
      "visible": true,
      "order": 1
    }
  ],
  "filters": null,
  "cadence": "daily",
  "window": "24h",
  "send_hour": 1,
  "recipient_type": "org",
  "specific_users": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "email": "[email protected]",
      "display_name": ""
    }
  ],
  "last_run_at": "2026-10-17T09:30:00+05:30",
  "last_log": null,
  "created_at": "2026-10-17T09:30:00+05:30",
  "updated_at": "2026-10-17T09:30:00+05:30"
}

Delete a scheduled report

DELETE/api/v1/reports/{report_id}/

Parameters

report_idpath, stringRequired
curl -X DELETE "https://api.vivrecrm.com/api/v1/reports/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-Api-Key: $VIVRE_API_KEY"

A scheduled report's runs

GET/api/v1/reports/{report_id}/logs/

Parameters

report_idpath, stringRequired
curl "https://api.vivrecrm.com/api/v1/reports/7c9e6679-7425-40de-944b-e07fc1f90ae7/logs/" \
  -H "X-Api-Key: $VIVRE_API_KEY"
Response 200
[
  {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "period_label": "",
    "triggered_by": "schedule",
    "status": "sent",
    "recipient_count": 1,
    "row_count": 1,
    "error": "",
    "created_at": "2026-10-17T09:30:00+05:30"
  }
]

Run a scheduled report now

POST/api/v1/reports/{report_id}/run/

Parameters

report_idpath, stringRequired

Body

deliveryenum
Omit to mail the report's stored recipients. One of download, admins, org, specific_users.
user_idsarray of string (uuid)
Member public ids; required when delivery is specific_users.
curl -X POST "https://api.vivrecrm.com/api/v1/reports/7c9e6679-7425-40de-944b-e07fc1f90ae7/run/" \
  -H "X-Api-Key: $VIVRE_API_KEY"