Search Person Prospects

curl --request POST \
  --url https://api.example.com/api/v1/entities/prospects/person \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "page": 123,
  "size": 123,
  "contact": {
    "contact.fullName": {
      "all": {
        "include": {
          "mode": "<string>",
          "content": [
            "<string>"
          ]
        },
        "exclude": {}
      },
      "any": {}
    },
    "contact.socialMediaLink": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "contact.company": {
      "current": {
        "all": {
          "include": [
            "<string>"
          ],
          "exclude": [
            "<string>"
          ]
        },
        "any": {
          "include": [
            "<string>"
          ],
          "exclude": [
            "<string>"
          ]
        }
      },
      "previous": {
        "all": {
          "include": [
            "<string>"
          ],
          "exclude": [
            "<string>"
          ]
        },
        "any": {
          "include": [
            "<string>"
          ],
          "exclude": [
            "<string>"
          ]
        }
      }
    },
    "contact.seniority": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "contact.location": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "contact.departmentAndFunction": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "contact.skill": {
      "all": {
        "include": {
          "mode": "<string>",
          "content": [
            "<string>"
          ]
        },
        "exclude": {}
      },
      "any": {}
    },
    "contact.certification": {
      "all": {
        "include": {
          "mode": "<string>",
          "content": [
            "<string>"
          ]
        },
        "exclude": {}
      },
      "any": {}
    },
    "contact.keyword": {
      "all": {
        "include": {
          "sources": [
            {}
          ],
          "content": [
            "<string>"
          ]
        },
        "exclude": {}
      },
      "any": {}
    },
    "contact.socialMedia": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "contact.language": {
      "all": {
        "include": {
          "mode": "<string>",
          "content": [
            "<string>"
          ]
        },
        "exclude": {}
      },
      "any": {},
      "range": {}
    },
    "contact.education": {
      "school": {
        "all": {
          "include": [
            "<string>"
          ],
          "exclude": [
            "<string>"
          ]
        },
        "any": {}
      },
      "degree": {},
      "fieldOfStudy": {},
      "date": {}
    },
    "contact.profileBadge": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "contact.experience": {
      "current": {
        "title": {
          "all": {
            "include": {
              "mode": "<string>",
              "content": [
                "<string>"
              ]
            },
            "exclude": {}
          },
          "any": {}
        },
        "duration": {
          "currentCompany": {
            "min": {
              "year": 123,
              "month": 123
            },
            "max": {
              "year": 123,
              "month": 123
            }
          },
          "currentJob": {},
          "total": {}
        }
      },
      "previous": {
        "title": {}
      }
    }
  },
  "account": {
    "account.nameOrDomain": {},
    "account.domain": {},
    "account.socialMediaLink": {},
    "account.phoneNumber": {},
    "account.industry": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "account.location": {},
    "account.productAndServices": {},
    "account.socialMedia": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "account.type": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "account.foundedYear": {},
    "account.employeeSize": {
      "type": "<string>",
      "range": [
        {}
      ]
    },
    "account.revenue": {},
    "account.language": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "range": {}
    },
    "account.geoLocation": {
      "position": {},
      "radius": 123,
      "unit": "<string>"
    },
    "account.keyword": {
      "all": {
        "include": {
          "sources": [
            {}
          ],
          "content": [
            "<string>"
          ]
        },
        "exclude": {}
      },
      "any": {}
    },
    "account.funding": {
      "type": [
        {}
      ],
      "totalAmount": {},
      "lastAmount": {},
      "duration": {}
    },
    "account.metric": {
      "employee": [
        {}
      ],
      "growth": [
        {}
      ]
    }
  }
}
'

{
  "totalElements": 1250,
  "totalPages": 125,
  "number": 0,
  "size": 10,
  "first": true,
  "last": false,
  "numberOfElements": 10,
  "empty": false,
  "content": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "firstName": "Sarah",
      "lastName": "Johnson",
      "jobTitle": "Chief Technology Officer",
      "city": "Austin",
      "postalCode": null,
      "country": "United States",
      "linkedinUrl": "https://www.linkedin.com/in/sarahjohnson",
      "phones": [],
      "emails": [],
      "companyId": "660e8400-e29b-41d4-a716-446655440001",
      "seniority": "c_suite",
      "industry": "Software",
      "departments": ["Engineering", "Technology"],
      "subDepartments": [],
      "functions": ["technology_operations", "engineering_technical"],
      "skills": ["Cloud Architecture", "Team Leadership", "Python", "AWS"],
      "languages": [{ "language": "English", "level": "Native" }],
      "educations": [
        {
          "institution": {
            "id": null,
            "name": "MIT",
            "logoUrl": null,
            "linkedinUrl": "https://www.linkedin.com/school/mit"
          },
          "degreeName": "MS",
          "fieldOfStudy": "Computer Science",
          "grade": null,
          "dates": { "start": "2008", "end": "2010" }
        }
      ],
      "workExperiences": [
        {
          "company": {
            "id": null,
            "name": "TechStartup Inc",
            "logoUrl": "https://logo.example.com/techstartup.png",
            "linkedinUrl": "https://www.linkedin.com/company/techstartup",
            "employees": { "start": "100", "end": "250" }
          },
          "dates": { "start": "2021-03", "end": null },
          "profilePositions": [
            {
              "company": "TechStartup Inc",
              "description": "Leading technology strategy and engineering teams",
              "title": "Chief Technology Officer",
              "employmentType": "Full-time",
              "location": "Austin, TX",
              "dates": { "start": "2021-03", "end": null }
            }
          ]
        }
      ],
      "certificates": [],
      "linkedinProfile": {
        "headline": "CTO at TechStartup Inc | Building Scalable Solutions",
        "summary": "Technology leader with 15+ years of experience...",
        "pictureUrl": "https://media.licdn.com/dms/image/..."
      },
      "baseProviderId": "baseProvider_person_abc123",
      "bullhornId": null,
      "crmId": null,
      "leadOwnerId": null,
      "consentStatus": "UNKNOWN",
      "consentSource": null,
      "consentUpdatedAt": null,
      "deletedAt": null,
      "birthDate": null,
      "company": {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z",
        "name": "TechStartup Inc",
        "description": "Innovative software company focused on enterprise solutions",
        "summary": "Enterprise SaaS provider",
        "headcount": "100-250",
        "industry": "Software",
        "phones": [],
        "linkedinUrl": "https://www.linkedin.com/company/techstartup",
        "websiteUrl": "https://www.techstartup.com",
        "domain": "techstartup.com",
        "city": "Austin",
        "postalCode": "78701",
        "country": "United States",
        "logoUrl": "https://logo.example.com/techstartup.png",
        "legalName": "TechStartup Inc.",
        "foundedYear": 2018,
        "revenue": "$10M-$50M",
        "baseProviderId": "baseProvider_company_xyz789",
        "bullhornId": null,
        "crmId": null,
        "location": null
      }
    }
  ]
}

POST

api

entities

prospects

person

Search Person Prospects

curl --request POST \
  --url https://api.example.com/api/v1/entities/prospects/person \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "page": 123,
  "size": 123,
  "contact": {
    "contact.fullName": {
      "all": {
        "include": {
          "mode": "<string>",
          "content": [
            "<string>"
          ]
        },
        "exclude": {}
      },
      "any": {}
    },
    "contact.socialMediaLink": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "contact.company": {
      "current": {
        "all": {
          "include": [
            "<string>"
          ],
          "exclude": [
            "<string>"
          ]
        },
        "any": {
          "include": [
            "<string>"
          ],
          "exclude": [
            "<string>"
          ]
        }
      },
      "previous": {
        "all": {
          "include": [
            "<string>"
          ],
          "exclude": [
            "<string>"
          ]
        },
        "any": {
          "include": [
            "<string>"
          ],
          "exclude": [
            "<string>"
          ]
        }
      }
    },
    "contact.seniority": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "contact.location": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "contact.departmentAndFunction": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "contact.skill": {
      "all": {
        "include": {
          "mode": "<string>",
          "content": [
            "<string>"
          ]
        },
        "exclude": {}
      },
      "any": {}
    },
    "contact.certification": {
      "all": {
        "include": {
          "mode": "<string>",
          "content": [
            "<string>"
          ]
        },
        "exclude": {}
      },
      "any": {}
    },
    "contact.keyword": {
      "all": {
        "include": {
          "sources": [
            {}
          ],
          "content": [
            "<string>"
          ]
        },
        "exclude": {}
      },
      "any": {}
    },
    "contact.socialMedia": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "contact.language": {
      "all": {
        "include": {
          "mode": "<string>",
          "content": [
            "<string>"
          ]
        },
        "exclude": {}
      },
      "any": {},
      "range": {}
    },
    "contact.education": {
      "school": {
        "all": {
          "include": [
            "<string>"
          ],
          "exclude": [
            "<string>"
          ]
        },
        "any": {}
      },
      "degree": {},
      "fieldOfStudy": {},
      "date": {}
    },
    "contact.profileBadge": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "contact.experience": {
      "current": {
        "title": {
          "all": {
            "include": {
              "mode": "<string>",
              "content": [
                "<string>"
              ]
            },
            "exclude": {}
          },
          "any": {}
        },
        "duration": {
          "currentCompany": {
            "min": {
              "year": 123,
              "month": 123
            },
            "max": {
              "year": 123,
              "month": 123
            }
          },
          "currentJob": {},
          "total": {}
        }
      },
      "previous": {
        "title": {}
      }
    }
  },
  "account": {
    "account.nameOrDomain": {},
    "account.domain": {},
    "account.socialMediaLink": {},
    "account.phoneNumber": {},
    "account.industry": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "account.location": {},
    "account.productAndServices": {},
    "account.socialMedia": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "account.type": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      }
    },
    "account.foundedYear": {},
    "account.employeeSize": {
      "type": "<string>",
      "range": [
        {}
      ]
    },
    "account.revenue": {},
    "account.language": {
      "all": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "any": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "range": {}
    },
    "account.geoLocation": {
      "position": {},
      "radius": 123,
      "unit": "<string>"
    },
    "account.keyword": {
      "all": {
        "include": {
          "sources": [
            {}
          ],
          "content": [
            "<string>"
          ]
        },
        "exclude": {}
      },
      "any": {}
    },
    "account.funding": {
      "type": [
        {}
      ],
      "totalAmount": {},
      "lastAmount": {},
      "duration": {}
    },
    "account.metric": {
      "employee": [
        {}
      ],
      "growth": [
        {}
      ]
    }
  }
}
'

{
  "totalElements": 1250,
  "totalPages": 125,
  "number": 0,
  "size": 10,
  "first": true,
  "last": false,
  "numberOfElements": 10,
  "empty": false,
  "content": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "firstName": "Sarah",
      "lastName": "Johnson",
      "jobTitle": "Chief Technology Officer",
      "city": "Austin",
      "postalCode": null,
      "country": "United States",
      "linkedinUrl": "https://www.linkedin.com/in/sarahjohnson",
      "phones": [],
      "emails": [],
      "companyId": "660e8400-e29b-41d4-a716-446655440001",
      "seniority": "c_suite",
      "industry": "Software",
      "departments": ["Engineering", "Technology"],
      "subDepartments": [],
      "functions": ["technology_operations", "engineering_technical"],
      "skills": ["Cloud Architecture", "Team Leadership", "Python", "AWS"],
      "languages": [{ "language": "English", "level": "Native" }],
      "educations": [
        {
          "institution": {
            "id": null,
            "name": "MIT",
            "logoUrl": null,
            "linkedinUrl": "https://www.linkedin.com/school/mit"
          },
          "degreeName": "MS",
          "fieldOfStudy": "Computer Science",
          "grade": null,
          "dates": { "start": "2008", "end": "2010" }
        }
      ],
      "workExperiences": [
        {
          "company": {
            "id": null,
            "name": "TechStartup Inc",
            "logoUrl": "https://logo.example.com/techstartup.png",
            "linkedinUrl": "https://www.linkedin.com/company/techstartup",
            "employees": { "start": "100", "end": "250" }
          },
          "dates": { "start": "2021-03", "end": null },
          "profilePositions": [
            {
              "company": "TechStartup Inc",
              "description": "Leading technology strategy and engineering teams",
              "title": "Chief Technology Officer",
              "employmentType": "Full-time",
              "location": "Austin, TX",
              "dates": { "start": "2021-03", "end": null }
            }
          ]
        }
      ],
      "certificates": [],
      "linkedinProfile": {
        "headline": "CTO at TechStartup Inc | Building Scalable Solutions",
        "summary": "Technology leader with 15+ years of experience...",
        "pictureUrl": "https://media.licdn.com/dms/image/..."
      },
      "baseProviderId": "baseProvider_person_abc123",
      "bullhornId": null,
      "crmId": null,
      "leadOwnerId": null,
      "consentStatus": "UNKNOWN",
      "consentSource": null,
      "consentUpdatedAt": null,
      "deletedAt": null,
      "birthDate": null,
      "company": {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z",
        "name": "TechStartup Inc",
        "description": "Innovative software company focused on enterprise solutions",
        "summary": "Enterprise SaaS provider",
        "headcount": "100-250",
        "industry": "Software",
        "phones": [],
        "linkedinUrl": "https://www.linkedin.com/company/techstartup",
        "websiteUrl": "https://www.techstartup.com",
        "domain": "techstartup.com",
        "city": "Austin",
        "postalCode": "78701",
        "country": "United States",
        "logoUrl": "https://logo.example.com/techstartup.png",
        "legalName": "TechStartup Inc.",
        "foundedYear": 2018,
        "revenue": "$10M-$50M",
        "baseProviderId": "baseProvider_company_xyz789",
        "bullhornId": null,
        "crmId": null,
        "location": null
      }
    }
  ]
}

Searches for person prospects using data providers with extensive filtering capabilities. Results are automatically mapped to domain objects and persisted to the global database (companies and persons are upserted), returning enriched lead objects with associated company data.

Authentication

This endpoint requires authentication. The user must be signed in to access prospect search functionality.

This endpoint performs a search against the Lance database of 400+ million professional profiles. Results are automatically saved to Lance’s database, deduplicating and merging with existing records.

Request

The request body allows filtering by both account (company) criteria and contact (person) criteria. All filters are optional and can be combined.

Pagination

page

integer

default:"0"

Page number for pagination (0-indexed)

size

integer

default:"10"

Number of results per page. Must be between 0 and 100.

Contact Filters

contact

object

Filters for the individual/person being searched

Show Contact filter properties

contact.fullName

object

Filter by person’s full name with search modes

Show Filter structure

all

object

Match all conditions

Show all properties

include

object

mode

string

Search match mode: SMART, WORD, or STRICT

content

string[]

Array of names to include

exclude

object

Same structure as include

any

object

Match any condition (same structure as all)

Filter by social media profile URLs (include/exclude arrays)

Show socialMediaLink properties

all

object

include

string[]

Social media URLs to include (all must match)

exclude

string[]

Social media URLs to exclude

any

object

include

string[]

Social media URLs to include (any can match)

exclude

string[]

Social media URLs to exclude

contact.company

object

Filter by current and/or previous companies

Show Company filter structure

current

object

Filter by current company names

Show current properties

all

object

include

string[]

Company names to include (all must match)

exclude

string[]

Company names to exclude

any

object

include

string[]

Company names to include (any can match)

exclude

string[]

Company names to exclude

object

Filter by previous company names

Show previous properties

all

object

include

string[]

Company names to include (all must match)

exclude

string[]

Company names to exclude

any

object

include

string[]

Company names to include (any can match)

exclude

string[]

Company names to exclude

contact.seniority

object

Filter by seniority level. Values: senior, manager, entry, mid-level, director, c_suite, intern, founder, owner, head, vp, partner

Show seniority properties

all

object

include

string[]

Seniority levels to include (all must match)

exclude

string[]

Seniority levels to exclude

any

object

include

string[]

Seniority levels to include (any can match)

exclude

string[]

Seniority levels to exclude

contact.location

object

Filter by person’s location (include/exclude arrays)

Show location properties

all

object

include

string[]

Locations to include (all must match)

exclude

string[]

Locations to exclude

any

object

include

string[]

Locations to include (any can match)

exclude

string[]

Locations to exclude

contact.departmentAndFunction

object

Filter by department and job function. Extensive list including:Executive: c_suite, executive, founderProduct: product_management, product_development, product_mangementEngineering: master_engineering_technical, artificial_intelligence_machine_learning, bioengineering, biometrics, business_intelligence, chemical_engineering, cloud_mobility, data_science, devops, emerging_technology_innovation, engineering_technical, industrial_engineering, mechanic, mobile_development, project_management, research_development, scrum_master_agile_coach, software_development, support_technical_services, technician, technology_operations, test_quality_assurance, ui_ux, web_developmentDesign: marketing, digital_marketing, design, all_design, product_ui_ux_design, graphic_designEducation: education, teacher, principal, superintendent, professorFinance: master_finance, accounting, finance, financial_planning_analysis, financial_reporting, financial_strategy, financial_systems, internal_audit_control, investor_relations, mergers_acquisitions, financial_risk, sourcing_procurement, tax, treasuryHR: master_human_resources, compensation_benefits, culture_diversity_inclusion, employee_labor_relations, health_safety, human_resource_information_system, human_resources, hr_business_partner, learning_development, organizational_development, recruiting_talent_acquisition, talent_management, workforce_mangementIT: master_information_technology, application_development, business_service_management_itsm, collaboration_web_app, data_center, data_warehouse, database_administration, ecommerce_development, enterprise_architecture, help_desk_desktop_services, hr_financial_erp_systems, information_security, information_technology, infrastructure, it_asset_management, it_audit_it_compliance, it_operations, it_procurement, it_strategy, networking, project_program_management, quality_assurance, retail_store_systems, servers, storage_disaster_recovery, telecommunications, virtualizationLegal: master_legal, compliance, contracts, ediscovery, governmental_affairs_regulatory_law, intellectual_property_patent, labor_employment, lawyer_attorney, legal, legal_counsel, legal_operations, litigation, privacyMarketing: master_marketing, advertising, brand_management, content_marketing, customer_experience, customer_marketing, demand_generation, ecommerce_marketing, event_marketing, field_marketing, lead_generation, marketing_analytics_insights, marketing_communications, product_marketing, public_relations, search_engine_optimization_pay_per_click, social_media_marketing, strategic_communications, technical_marketingSales: sales, field_outside_sales, master_sales, account_management, business_development, channel_sales, customer_retention_development, inside_sales, partnerships, sales_enablement, sales_engineering, sales_operations, sales_trainingMedical: medical_health, chiropractics, dentistry, doctors_physicians, first_responder, infectious_disease, medical_administration, medical_education_training, medicine, neurology, nursing, nutrition_dietetics, oncology, pathology, pharmacy, physical_therapy, psychology, public_health, radiology, social_workOperations: master_operations, call_center, construction, corporate_strategy, customer_service_support, enterprise_resource_planning, facilities_management, leasing, logistics, office_operations, operations, physical_security, project_development, quality_management, real_estate, store_operations, supply_chain, customer_successConsulting: consulting, consultant

Show departmentAndFunction properties

all

object

include

string[]

Departments/functions to include (all must match)

exclude

string[]

Departments/functions to exclude

any

object

include

string[]

Departments/functions to include (any can match)

exclude

string[]

Departments/functions to exclude

contact.skill

object

Filter by skills with search modes (SMART, WORD, STRICT)

Show skill properties

all

object

include

object

mode

string

Search match mode: SMART, WORD, or STRICT

content

string[]

Array of skills to include

exclude

object

Same structure as include

any

object

Same structure as all

contact.certification

object

Filter by certifications with search modes

Show certification properties

all

object

include

object

mode

string

Search match mode: SMART, WORD, or STRICT

content

string[]

Array of certifications to include

exclude

object

Same structure as include

any

object

Same structure as all

contact.keyword

object

Filter by keywords across multiple profile sources.Sources: ORGANIZATION, TEST_SCORE, AWARD, WORK_HISTORY_DESCRIPTION, PUBLICATION, SUMMARY, PATENT, VOLUNTEERING, HEADLINE, EDUCATION_DESCRIPTION, COURSE, PROJECTS, SKILL, LANGUAGE_SKILL, CERTIFICATION

Show keyword properties

all

object

include

object

sources

object[]

Array of source configurations with:

mode: SMART, WORD, or STRICT
source: one of the sources listed above

content

string[]

Keywords to search for

exclude

object

Same structure as include

any

object

Same structure as all

Filter by social media presence. Values: FACEBOOK, INSTAGRAM, TWITTER, LINKEDIN

Show socialMedia properties

all

object

include

string[]

Social media platforms to include (all must match)

exclude

string[]

Social media platforms to exclude

any

object

include

string[]

Social media platforms to include (any can match)

exclude

string[]

Social media platforms to exclude

contact.language

object

Filter by language skills with proficiency range. Supports 49 languages: english, spanish, french, portuguese, german, dutch, italian, chinese, turkish, polish, russian, swedish, arabic, indonesian, danish, czech, norwegian, japanese, korean, romanian, ukrainian, thai, hindi, malay, tagalog, vietnamese, finnish, persian, greek, hungarian, bengali, marathi, telugu, panjabi, serbian, slovak, croatian, lithuanian, latvian, albanian, icelandic, armenian, bosnian, tamil, javanese, malayalam, kannada, burmese

Show language properties

all

object

include

object

mode

string

Search match mode: SMART, WORD, or STRICT

content

string[]

Array of language enum values to include (e.g., ["english", "german"])

exclude

object

Same structure as include

any

object

Same structure as all

range

object

Range filter for number of languages

start

number

Minimum count

end

number

Maximum count

contact.education

object

Filter by education background

Show Education filter structure

school

object

all

object

include

string[]

School names to include

exclude

string[]

School names to exclude

any

object

Same structure as all

degree

object

Filter by degree types with search mode (SMART, WORD, STRICT)

fieldOfStudy

object

Filter by fields of study with search mode

date

object

Education date range filter

start

number

Start year

end

number

End year

present

boolean

Currently enrolled

contact.profileBadge

object

Filter by LinkedIn profile badges. Values: PREMIUM, OPEN_TO_WORK, INFLUENCER

Show profileBadge properties

all

object

include

string[]

Profile badges to include (all must match)

exclude

string[]

Profile badges to exclude

any

object

include

string[]

Profile badges to include (any can match)

exclude

string[]

Profile badges to exclude

contact.experience

object

Filter by work experience

Show Experience filter structure

current

object

Current role filters

Show current properties

title

object

Filter by current job title with search modes (SMART, WORD, STRICT)

all

object

include

object

mode

string

Search match mode

content

string[]

Job titles to include

exclude

object

Same structure as include

any

object

Same structure as all

duration

object

Duration filters for current position

currentCompany

object

Time at current company

min

object

year

number

Minimum years

month

number

Minimum months

max

object

year

number

Maximum years

month

number

Maximum months

currentJob

object

Time in current role (same structure as currentCompany)

total

object

Total work experience (same structure as currentCompany)

object

Previous role filters

Show previous properties

title

object

Filter by previous job titles with search modes

Account Filters

account

object

Filters for the company/account associated with the person

Show Account filter properties

account.nameOrDomain

object

Filter by company name or domain with search modes (SMART, WORD, STRICT)

account.domain

object

Filter by company domain (include/exclude arrays)

Filter by company social media profile URLs (include/exclude arrays)

account.phoneNumber

object

Filter by company phone numbers (include/exclude arrays)

account.industry

object

Filter by industry. Supports 900+ industries including: software development, it services and it consulting, financial services, hospitals and health care, manufacturing, retail, construction, real estate, education, marketing, biotechnology, telecommunications, saas, fintech, artificial intelligence (ai), generative ai, and many more.

Show industry properties

all

object

include

string[]

Industries to include (all must match)

exclude

string[]

Industries to exclude

any

object

include

string[]

Industries to include (any can match)

exclude

string[]

Industries to exclude

account.location

object

Filter by company location (include/exclude arrays)

account.productAndServices

object

Filter by company products and services with search modes (SMART, WORD, STRICT)

Filter by company social media presence. Values: FACEBOOK, INSTAGRAM, TWITTER, LINKEDIN

Show socialMedia properties

all

object

include

string[]

Social media platforms to include (all must match)

exclude

string[]

Social media platforms to exclude

any

object

include

string[]

Social media platforms to include (any can match)

exclude

string[]

Social media platforms to exclude

account.type

object

Filter by company type. Values: PRIVATELY_HELD, PUBLIC_COMPANY, GOVERNMENT_AGENCY, PARTNERSHIP, SOLE_PROPRIETORSHIP, NON_PROFIT, EDUCATIONAL, SELF_OWNED, SELF_EMPLOYED

Show type properties

all

object

include

string[]

Company types to include (all must match)

exclude

string[]

Company types to exclude

any

object

include

string[]

Company types to include (any can match)

exclude

string[]

Company types to exclude

account.foundedYear

object

Filter by company founded year range {start, end}

account.employeeSize

object

Filter by employee count range

Show Range structure

type

string

Must be RANGE

range

array

Array of {start, end} objects

account.revenue

object

Filter by company revenue range (same structure as employeeSize)

account.language

object

Filter by company operating language. Supports 49 languages: english, spanish, french, portuguese, german, dutch, italian, chinese, turkish, polish, russian, swedish, arabic, indonesian, danish, czech, norwegian, japanese, korean, romanian, ukrainian, thai, hindi, malay, tagalog, vietnamese, finnish, persian, greek, hungarian, bengali, marathi, telugu, panjabi, serbian, slovak, croatian, lithuanian, latvian, albanian, icelandic, armenian, bosnian, tamil, javanese, malayalam, kannada, burmese.

Show language properties

all

object

include

string[]

Language enum values to include (all must match)

exclude

string[]

Language enum values to exclude

any

object

include

string[]

Language enum values to include (any can match)

exclude

string[]

Language enum values to exclude

range

object

Range filter for number of languages

start

number

Minimum count

end

number

Maximum count

account.geoLocation

object

Filter by geographic location

Show GeoLocation structure

position

object

{lat, lng} coordinates

radius

number

Search radius

unit

string

km or mi

account.keyword

object

Search by keywords across company data sources.

Show keyword properties

all

object

include

object

sources

object[]

Array of source configurations with mode (SMART, WORD, STRICT) and source. Sources: NAME, KEYWORD, SEO, DESCRIPTION, INDUSTRY

content

string[]

Keywords to search for

exclude

object

Same structure as include

any

object

Same structure as all

account.funding

object

Filter by funding details

Show Funding filter structure

type

array

Funding types: PRE_SEED, SEED, SERIES_A through SERIES_J, VENTURE_ROUND, ANGEL, PRIVATE_EQUITY, DEBT_FINANCING, CONVERTIBLE_NOTE, GRANT, CORPORATE_ROUND, EQUITY_CROWDFUNDING, PRODUCT_CROWDFUNDING, SECONDARY_MARKET, POST_IPO_EQUITY, POST_IPO_DEBT, POST_IPO_SECONDARY, NON_EQUITY_ASSISTANCE, INITIAL_COIN_OFFERING, UNDISCLOSED, SERIES_UNKNOWN, FUNDING_ROUND

totalAmount

object

Total funding amount range {start, end}

lastAmount

object

Last funding round amount range {start, end}

duration

object

Funding date range {start, end} as ISO timestamps

account.metric

object

Filter by company metrics

Show Metrics filter structure

employee

object[]

Array of employee count filters by department. Each object has:

function: array of department enums (program_and_project_management, education, purchasing, accounting, sales, research, operations, customer_success_and_support, legal, product_management, media_and_communication, real_estate, quality_assurance, consulting, arts_and_design, healthcare_services, entrepreneurship, engineering, community_and_social_services, marketing, information_technology, business_development, administrative, military_and_protective_services, finance, human_resources, support)
start: minimum employee count
end: maximum employee count

growth

object[]

Array of headcount growth filters by department. Each object has:

function: array of department enums (same as employee, also accepts custom strings)
start: minimum growth percentage
end: maximum growth percentage
timeFrame: ONE, THREE, SIX, TWELVE, or TWENTY_FOUR (months)

Response

Returns a paginated response containing leads (persons with associated company data).

content

Lead[]

Array of lead objects matching the search criteria

Show Lead object properties

string

required

Unique identifier (UUID) for the person

createdAt

string

ISO 8601 timestamp when the person was created. Can be null.

updatedAt

string

ISO 8601 timestamp when the person was last updated. Can be null.

firstName

string

required

Person’s first name

lastName

string

required

Person’s last name

jobTitle

string

Person’s current job title. Can be null.

city

string

Person’s city. Can be null.

postalCode

string

Person’s postal/zip code. Can be null.

country

string

Person’s country. Can be null.

linkedinUrl

string

Person’s LinkedIn profile URL. Can be null.

phones

string[]

Array of phone numbers. Defaults to empty array.

emails

string[]

Array of email addresses (lowercased). Defaults to empty array.

companyId

string

UUID of the associated company. Can be null.

seniority

string

Person’s seniority level. Can be null.

industry

string

Person’s industry. Can be null.

departments

string[]

Array of department names. Defaults to empty array.

subDepartments

string[]

Array of sub-department names. Defaults to empty array.

functions

string[]

Array of job functions. Defaults to empty array.

skills

string[]

Array of skills. Defaults to empty array.

languages

Language[]

Array of language proficiencies with language and level fields.

educations

Education[]

Array of educational background with institution, degree, field of study, and dates.

workExperiences

WorkExperience[]

Array of work history with company details and profile positions.

certificates

Certificate[]

Array of certifications with name, authority, and dates.

linkedinProfile

object

LinkedIn profile data with headline, summary, and pictureUrl.

baseProviderId

string

Internal data provider identifier. Can be null.

crmId

string

Generic CRM identifier. Can be null.

leadOwnerId

string

ID of the user who owns this lead. Can be null.

company

Company

Associated company data. Can be null.

Show Company object properties

string

required

Unique identifier (UUID)

createdAt

string

ISO 8601 timestamp when the company was created. Can be null.

updatedAt

string

ISO 8601 timestamp when the company was last updated. Can be null.

name

string

required

Company name

description

string

Company description. Can be null.

summary

string

Brief company summary. Can be null.

headcount

string

Employee count range. Can be null.

industry

string

Industry classification. Can be null.

phones

string[]

Company phone numbers.

linkedinUrl

string

Company LinkedIn URL. Can be null.

websiteUrl

string

Company website URL. Can be null.

domain

string

Company domain. Can be null.

city

string

Headquarters city. Can be null.

postalCode

string

Headquarters postal code. Can be null.

country

string

Headquarters country. Can be null.

logoUrl

string

Company logo URL. Can be null.

legalName

string

Legal/registered company name. Can be null.

foundedYear

number

Year founded. Can be null.

revenue

string

Revenue range. Can be null.

location

object

Detailed location information. Can be null.

baseProviderId

string

Lance internal provider ID. Can be null.

crmId

string

Generic CRM identifier. Can be null.

totalElements

integer

Total number of matching results across all pages. Can be null.

totalPages

integer

Total number of pages available. Can be null.

number

integer

Current page number (0-indexed). Can be null.

size

integer

Number of results per page. Can be null.

first

boolean

Whether this is the first page. Can be null.

last

boolean

Whether this is the last page. Can be null.

numberOfElements

integer

Number of elements on the current page. Can be null.

empty

boolean

Whether the result set is empty. Can be null.

Response Examples

{
  "totalElements": 1250,
  "totalPages": 125,
  "number": 0,
  "size": 10,
  "first": true,
  "last": false,
  "numberOfElements": 10,
  "empty": false,
  "content": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "firstName": "Sarah",
      "lastName": "Johnson",
      "jobTitle": "Chief Technology Officer",
      "city": "Austin",
      "postalCode": null,
      "country": "United States",
      "linkedinUrl": "https://www.linkedin.com/in/sarahjohnson",
      "phones": [],
      "emails": [],
      "companyId": "660e8400-e29b-41d4-a716-446655440001",
      "seniority": "c_suite",
      "industry": "Software",
      "departments": ["Engineering", "Technology"],
      "subDepartments": [],
      "functions": ["technology_operations", "engineering_technical"],
      "skills": ["Cloud Architecture", "Team Leadership", "Python", "AWS"],
      "languages": [{ "language": "English", "level": "Native" }],
      "educations": [
        {
          "institution": {
            "id": null,
            "name": "MIT",
            "logoUrl": null,
            "linkedinUrl": "https://www.linkedin.com/school/mit"
          },
          "degreeName": "MS",
          "fieldOfStudy": "Computer Science",
          "grade": null,
          "dates": { "start": "2008", "end": "2010" }
        }
      ],
      "workExperiences": [
        {
          "company": {
            "id": null,
            "name": "TechStartup Inc",
            "logoUrl": "https://logo.example.com/techstartup.png",
            "linkedinUrl": "https://www.linkedin.com/company/techstartup",
            "employees": { "start": "100", "end": "250" }
          },
          "dates": { "start": "2021-03", "end": null },
          "profilePositions": [
            {
              "company": "TechStartup Inc",
              "description": "Leading technology strategy and engineering teams",
              "title": "Chief Technology Officer",
              "employmentType": "Full-time",
              "location": "Austin, TX",
              "dates": { "start": "2021-03", "end": null }
            }
          ]
        }
      ],
      "certificates": [],
      "linkedinProfile": {
        "headline": "CTO at TechStartup Inc | Building Scalable Solutions",
        "summary": "Technology leader with 15+ years of experience...",
        "pictureUrl": "https://media.licdn.com/dms/image/..."
      },
      "baseProviderId": "baseProvider_person_abc123",
      "bullhornId": null,
      "crmId": null,
      "leadOwnerId": null,
      "consentStatus": "UNKNOWN",
      "consentSource": null,
      "consentUpdatedAt": null,
      "deletedAt": null,
      "birthDate": null,
      "company": {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z",
        "name": "TechStartup Inc",
        "description": "Innovative software company focused on enterprise solutions",
        "summary": "Enterprise SaaS provider",
        "headcount": "100-250",
        "industry": "Software",
        "phones": [],
        "linkedinUrl": "https://www.linkedin.com/company/techstartup",
        "websiteUrl": "https://www.techstartup.com",
        "domain": "techstartup.com",
        "city": "Austin",
        "postalCode": "78701",
        "country": "United States",
        "logoUrl": "https://logo.example.com/techstartup.png",
        "legalName": "TechStartup Inc.",
        "foundedYear": 2018,
        "revenue": "$10M-$50M",
        "baseProviderId": "baseProvider_company_xyz789",
        "bullhornId": null,
        "crmId": null,
        "location": null
      }
    }
  ]
}

Request Examples

Basic Search - CTOs in Software Industry

{
  "contact": {
    "seniority": {
      "any": {
        "include": ["c_suite"]
      }
    },
    "experience": {
      "current": {
        "title": {
          "any": {
            "include": {
              "mode": "SMART",
              "content": ["CTO", "Chief Technology Officer"]
            }
          }
        }
      }
    }
  },
  "account": {
    "industry": {
      "any": {
        "include": ["software development", "software"]
      }
    }
  },
  "page": 0,
  "size": 25
}

Search by Company Size and Location

{
  "contact": {
    "departmentAndFunction": {
      "any": {
        "include": ["sales", "business_development"]
      }
    },
    "location": {
      "any": {
        "include": ["San Francisco", "New York", "Boston"]
      }
    }
  },
  "account": {
    "employeeSize": {
      "type": "RANGE",
      "range": [{ "start": 50, "end": 500 }]
    }
  },
  "page": 0,
  "size": 50
}

Search by Skills and Funding Stage

{
  "contact": {
    "skill": {
      "any": {
        "include": {
          "mode": "SMART",
          "content": ["Machine Learning", "AI", "Python"]
        }
      }
    }
  },
  "account": {
    "funding": {
      "type": ["SERIES_A", "SERIES_B", "SERIES_C"]
    }
  },
  "page": 0,
  "size": 20
}

Search by Keywords Across Profile Sources

{
  "contact": {
    "keyword": {
      "any": {
        "include": {
          "sources": [
            { "mode": "SMART", "source": "HEADLINE" },
            { "mode": "SMART", "source": "SUMMARY" },
            { "mode": "SMART", "source": "SKILL" }
          ],
          "content": ["data engineering", "ETL", "data pipeline"]
        }
      }
    }
  },
  "page": 0,
  "size": 25
}

Search by Experience Duration

{
  "contact": {
    "seniority": {
      "any": {
        "include": ["manager", "director"]
      }
    },
    "experience": {
      "current": {
        "duration": {
          "currentCompany": {
            "min": { "year": 2, "month": 0 },
            "max": { "year": 5, "month": 0 }
          },
          "total": {
            "min": { "year": 8, "month": 0 }
          }
        }
      }
    }
  },
  "page": 0,
  "size": 20
}

Search People Open to Work

{
  "contact": {
    "profileBadge": {
      "any": {
        "include": ["OPEN_TO_WORK"]
      }
    },
    "departmentAndFunction": {
      "any": {
        "include": ["software_development", "data_science"]
      }
    }
  },
  "page": 0,
  "size": 25
}

How It Works

Authentication: The endpoint authenticates the user via Clerk
Validation: Request body is validated against the PeopleSearch_Body schema
Search: Queries the Lance database with the provided filters
Mapping: Maps external provider response data to Lance domain objects (Person and Company)
Persistence: Companies and persons are upserted to the global database using merge logic to preserve existing data
Response: Returns the enriched leads with associated company data

Results are automatically deduplicated during the upsert process. If a person or company already exists in the database (matched by external IDs or other identifiers), the records are merged rather than duplicated.

Notes

Search results are persisted to the database, making subsequent searches faster for the same prospects
The external provider integration uses rate limiting (5 requests per second) to avoid overwhelming the external service
Company data is extracted from the person’s current position or position groups if available
The companyId field in the response links each person to their saved company record
External provider IDs (baseProviderId) are preserved to enable future enrichment and deduplication

Search People by Company Get Prospect Person

​Authentication

​Request

​Pagination

​Contact Filters

​Account Filters

​Response

​Response Examples

​Request Examples

​Basic Search - CTOs in Software Industry

​Search by Company Size and Location

​Search by Skills and Funding Stage

​Search by Keywords Across Profile Sources

​Search by Experience Duration

​Search People Open to Work

​How It Works

​Notes

Authentication

Request

Pagination

Contact Filters

Account Filters

Response

Response Examples

Request Examples

Basic Search - CTOs in Software Industry

Search by Company Size and Location

Search by Skills and Funding Stage

Search by Keywords Across Profile Sources

Search by Experience Duration

Search People Open to Work

How It Works

Notes