---
title: "Paginated leads lookup by marketing source"
method: POST
path: "/crm/lookup/leads"
tags: ["CRM Service Calls"]
---

# Paginated leads lookup by marketing source

`POST /crm/lookup/leads`

Query leads by marketing source (lead_source) with pagination and journey tracking.

## Search Options

- **lead_source**: Required. The marketing source to filter by (exact match)
- **include_converted**: Include leads converted to contacts (default: true)
- **include_disqualified**: Include disqualified leads (default: false)

## Pagination

- **page_size**: Number of items per page (default: 50, max: 100)
- **page_num**: Page number, 1-indexed (default: 1)

## Privacy Notice

This endpoint returns **only aggregate activity metrics** per lead. It does NOT expose:

- Names or personal identifying information
- Actual comment content or details
- Owner/assigned user information
- Deal values or commission-sensitive data

## Use Cases

- **Partner Analytics**: View all leads from your marketing source
- **Journey Tracking**: Track conversion progress of your leads
- **Performance Monitoring**: Monitor lead-to-opportunity conversion rates

## Inactivity Period

The `inactivity_days` parameter (default: 30) determines whether activity is considered
"recent". The `has_recent_activity` field indicates if the most recent
activity falls within this threshold.

## Query parameters

- `page_size` integer — Number of leads per page
- `page_num` integer — Page number (1-indexed)
- `inactivity_days` integer — Number of days to consider for inactivity threshold

## Request body

- LeadsLookupRequest — Request for paginated leads lookup by marketing source. Used by partners to query all leads from their marketing source.
  - `lead_source` string, required — Marketing source / lead source to filter by
  - `include_converted` boolean — Include leads that have been converted to contacts
  - `include_disqualified` boolean — Include disqualified/inactive leads

## Response `200`

Lookup successful

- LeadsLookupResponse — Paginated response for leads lookup by marketing source. Privacy-safe: returns journey metrics without exposing sensitive data.
  - `leads` LeadJourneyItem[], required — List of lead journey items
    - `lead_id` string, required — Internal lead record ID
    - `external_id` string, nullable — External/partner reference ID if set
    - `lead` LeadJourneyInfo, required — Privacy-safe lead information for journey tracking. Exposes only aggregate activity metrics without PII.
      - `exists` boolean, required — Whether a matching lead record was found
      - `is_active` boolean — Whether the lead is in an active state (not disqualified/inactive)
      - `is_converted` boolean — Whether the lead has been converted to a contact
      - `has_activity` boolean — Whether there has been any activity on this lead
      - `comment_count` integer — Number of comments/touchpoints on the lead
      - `days_since_last_activity` integer, nullable — Days since last activity, null if no activity
      - `activity_summary` string, nullable — Human-readable activity summary
      - `created_date` string, nullable — Date the lead was created (ISO 8601)
    - `contact` ContactJourneyInfo, required — Privacy-safe contact information for journey tracking. Exposes only aggregate activity metrics without PII.
      - `exists` boolean, required — Whether a matching contact record was found
      - `is_active` boolean — Whether the contact is in an active state
      - `has_activity` boolean — Whether there has been any activity on this contact
      - `comment_count` integer — Number of comments/touchpoints on the contact
      - `days_since_last_activity` integer, nullable — Days since last activity, null if no activity
      - `activity_summary` string, nullable — Human-readable activity summary
      - `created_date` string, nullable — Date the contact was created (ISO 8601)
      - `converted_from_lead` boolean — Whether this contact was converted from a lead
    - `opportunity` OpportunityJourneyInfo, required — Privacy-safe opportunity information for journey tracking. Exposes stage and dates only - no values or sensitive details.
      - `exists` boolean, required — Whether an opportunity exists for this person
      - `stage` string, nullable — Current opportunity stage (e.g., discovery, negotiation, closed_won)
      - `is_closed` boolean — Whether the opportunity is in a closed state
      - `is_won` boolean — Whether the opportunity was won (closed_won)
      - `created_date` string, nullable — Date the opportunity was created (ISO 8601)
      - `expected_close_date` string, nullable — Expected close date (ISO 8601)
      - `close_date` string, nullable — Actual close date if closed (ISO 8601)
      - `opportunity_count` integer — Total number of opportunities for this person
    - `journey_stage` 'lead' | 'contact' | 'opportunity' | 'closed', nullable — Current stage in the journey
    - `has_recent_activity` boolean — True if person has activity within the configured threshold (default 30 days)
    - `total_touchpoints` integer — Total touchpoints across all stages
    - `first_seen_date` string, nullable — Earliest date this lead entered the system (ISO 8601)
  - `lead_source` string, required — The marketing source that was queried
  - `total_count` integer, required — Total number of leads matching the query
  - `page_size` integer, required — Number of items per page
  - `page_num` integer, required — Current page number (1-indexed)
  - `total_pages` integer, required — Total number of pages

## Other responses

- `401` — Missing or invalid authorization token
- `422` — Validation error
- `429` — Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.net/ambivo/apis/ambivo-api.md) · [All operations](https://skmtc.net/ambivo/apis/ambivo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ambivo/ambivo-api/versions/165a6d16a9a0/schema)