--- 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` ## Request - Base URL: `https://fapi.ambivo.com` (the document declares no server; this is the origin it was published from) - URL: `https://fapi.ambivo.com/crm/lookup/leads` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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 ## Changes - **2026-08-06** `165a6d16a9a0`: 1 info - endpoint added [Operation history](https://skmtc.dev/ambivo/apis/ambivo-api/changes/crm/lookup/leads/post.md) --- [API](https://skmtc.dev/ambivo/apis/ambivo-api.md) - [All operations](https://skmtc.dev/ambivo/apis/ambivo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ambivo/apis/ambivo-api/revisions/165a6d16a9a0?raw)