Get Leads

Retrieve leads with optional filtering, sorting, pagination, and date range.

Returns a list of leads matching your criteria. Without any filters, returns the most recent leads sorted by creation date (newest first).

Time-based filtering (start_date / end_date):

Use start_date and end_date query parameters to filter leads by creation date. Both accept ISO 8601 UTC strings. When provided, only leads created within that range are returned.

• Format: YYYY-MM-DDTHH:MM:SSZ (full) or YYYY-MM-DD (date only, treated as midnight UTC)
• Both are optional — you can provide just start_date (everything after), just end_date (everything before), or both for a specific window.
• Do NOT pass date/timestamp fields inside match_filter_dict — use these dedicated query parameters instead.

Example requests:

• All leads (no date filter): GET /leads
• Leads created in the last 7 days: GET /leads?start_date=2026-03-22T00:00:00Z&end_date=2026-03-29T23:59:59Z
• Leads created since March 1st: GET /leads?start_date=2026-03-01
• Leads created before a specific date: GET /leads?end_date=2026-03-15T23:59:59Z
• Leads from Google created in the last 7 days: GET /leads?start_date=2026-03-22&end_date=2026-03-29&match_filter_dict={"lead_source": "Google"}

Other Query Parameters:

• match_filter_dict (optional): JSON-encoded MongoDB query to filter leads by non-date fields. Filterable fields: lead_status, lead_source, name, email_list, phone_list, tags, employer_name, profession, title. Examples:
  • {"lead_status": "contacted"} — only contacted leads
  • {"lead_source": "Google"} — leads from Google
  • {"tags": {"$in": ["vip"]}} — leads tagged "vip"
  • {"_id": {"$in": ["ObjectId('64a856b9c9ac463f751ba187')"]}} — lookup by ID (requires eval_object_id=true)
• eval_object_id (default: false): Set to true when your filter uses ObjectId('...') syntax.
• sort_dict (default: {"_id": -1}): JSON-encoded sort criteria. Example: {"created_ts": 1} for oldest first.
• page_size (default: 50, max: 500): Number of records per page.
• page_num (default: 1): Page number (1-indexed).

Response: Paginated object with leads array, page_size, and page_num.