Search People by Company

curl -X GET "https://api.lance.app/api/v1/entities/prospects/company/550e8400-e29b-41d4-a716-446655440000/people/search" \
  -H "Authorization: Bearer <token>"

curl -X GET "https://api.lance.app/api/v1/entities/prospects/company/550e8400-e29b-41d4-a716-446655440000/people/search?page=0&size=50" \
  -H "Authorization: Bearer <token>"

curl -X GET "https://api.lance.app/api/v1/entities/prospects/company/550e8400-e29b-41d4-a716-446655440000/people/search?page=2&size=25" \
  -H "Authorization: Bearer <token>"

{
  "content": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "firstName": "Jane",
      "lastName": "Smith",
      "jobTitle": "VP of Engineering",
      "city": "San Francisco",
      "postalCode": "94105",
      "country": "United States",
      "linkedinUrl": "https://www.linkedin.com/in/janesmith",
      "phones": ["+1-555-987-6543"],
      "emails": ["jane.smith@acmetech.com"],
      "companyId": "550e8400-e29b-41d4-a716-446655440000",
      "seniority": "VP",
      "industry": "Software Development",
      "birthDate": null,
      "departments": ["Engineering"],
      "subDepartments": ["Platform"],
      "functions": ["Engineering Management"],
      "skills": ["Leadership", "Software Architecture", "Team Building"],
      "languages": [
        { "language": "English", "level": "Native" },
        { "language": "Spanish", "level": "Professional" }
      ],
      "educations": [
        {
          "institution": {
            "id": null,
            "name": "Stanford University",
            "logoUrl": "https://media.licdn.com/school/stanford.png",
            "linkedinUrl": "https://www.linkedin.com/school/stanford-university"
          },
          "degreeName": "Master of Science",
          "fieldOfStudy": "Computer Science",
          "grade": null,
          "dates": { "start": "2008", "end": "2010" }
        }
      ],
      "workExperiences": [
        {
          "company": {
            "id": null,
            "name": "Acme Technologies",
            "logoUrl": "https://media.licdn.com/company/acme.png",
            "linkedinUrl": "https://www.linkedin.com/company/acme-technologies",
            "employees": { "start": "201", "end": "500" }
          },
          "dates": { "start": "2020-01", "end": null },
          "profilePositions": [
            {
              "company": "Acme Technologies",
              "description": "Leading the engineering organization...",
              "title": "VP of Engineering",
              "employmentType": "Full-time",
              "location": "San Francisco, CA",
              "dates": { "start": "2020-01", "end": null }
            }
          ]
        }
      ],
      "certificates": [],
      "linkedinProfile": {
        "headline": "VP of Engineering at Acme Technologies | Building the future of enterprise software",
        "summary": "Passionate engineering leader with 15+ years of experience...",
        "pictureUrl": "https://media.licdn.com/profile/janesmith.jpg"
      },
      "baseProviderId": "ark_person_789012",
      "bullhornId": null,
      "crmId": null,
      "leadOwnerId": null,
      "consentStatus": "UNKNOWN",
      "consentSource": null,
      "consentUpdatedAt": null,
      "deletedAt": null
    }
  ],
  "totalElements": 156,
  "totalPages": 7,
  "page": 0,
  "size": 25
}

{
  "content": [],
  "totalElements": 0,
  "totalPages": 0,
  "page": 0,
  "size": 25
}

GET

api

entities

prospects

company

{id}

people

curl -X GET "https://api.lance.app/api/v1/entities/prospects/company/550e8400-e29b-41d4-a716-446655440000/people/search" \
  -H "Authorization: Bearer <token>"

curl -X GET "https://api.lance.app/api/v1/entities/prospects/company/550e8400-e29b-41d4-a716-446655440000/people/search?page=0&size=50" \
  -H "Authorization: Bearer <token>"

curl -X GET "https://api.lance.app/api/v1/entities/prospects/company/550e8400-e29b-41d4-a716-446655440000/people/search?page=2&size=25" \
  -H "Authorization: Bearer <token>"

{
  "content": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "firstName": "Jane",
      "lastName": "Smith",
      "jobTitle": "VP of Engineering",
      "city": "San Francisco",
      "postalCode": "94105",
      "country": "United States",
      "linkedinUrl": "https://www.linkedin.com/in/janesmith",
      "phones": ["+1-555-987-6543"],
      "emails": ["jane.smith@acmetech.com"],
      "companyId": "550e8400-e29b-41d4-a716-446655440000",
      "seniority": "VP",
      "industry": "Software Development",
      "birthDate": null,
      "departments": ["Engineering"],
      "subDepartments": ["Platform"],
      "functions": ["Engineering Management"],
      "skills": ["Leadership", "Software Architecture", "Team Building"],
      "languages": [
        { "language": "English", "level": "Native" },
        { "language": "Spanish", "level": "Professional" }
      ],
      "educations": [
        {
          "institution": {
            "id": null,
            "name": "Stanford University",
            "logoUrl": "https://media.licdn.com/school/stanford.png",
            "linkedinUrl": "https://www.linkedin.com/school/stanford-university"
          },
          "degreeName": "Master of Science",
          "fieldOfStudy": "Computer Science",
          "grade": null,
          "dates": { "start": "2008", "end": "2010" }
        }
      ],
      "workExperiences": [
        {
          "company": {
            "id": null,
            "name": "Acme Technologies",
            "logoUrl": "https://media.licdn.com/company/acme.png",
            "linkedinUrl": "https://www.linkedin.com/company/acme-technologies",
            "employees": { "start": "201", "end": "500" }
          },
          "dates": { "start": "2020-01", "end": null },
          "profilePositions": [
            {
              "company": "Acme Technologies",
              "description": "Leading the engineering organization...",
              "title": "VP of Engineering",
              "employmentType": "Full-time",
              "location": "San Francisco, CA",
              "dates": { "start": "2020-01", "end": null }
            }
          ]
        }
      ],
      "certificates": [],
      "linkedinProfile": {
        "headline": "VP of Engineering at Acme Technologies | Building the future of enterprise software",
        "summary": "Passionate engineering leader with 15+ years of experience...",
        "pictureUrl": "https://media.licdn.com/profile/janesmith.jpg"
      },
      "baseProviderId": "ark_person_789012",
      "bullhornId": null,
      "crmId": null,
      "leadOwnerId": null,
      "consentStatus": "UNKNOWN",
      "consentSource": null,
      "consentUpdatedAt": null,
      "deletedAt": null
    }
  ],
  "totalElements": 156,
  "totalPages": 7,
  "page": 0,
  "size": 25
}

{
  "content": [],
  "totalElements": 0,
  "totalPages": 0,
  "page": 0,
  "size": 25
}

Search for people (contacts/employees) at a specific company using the Lance database. Results are automatically mapped and upserted to the database for future reference.

Authentication

This endpoint requires authentication. The user must be logged in.

The search prioritizes company matching in this order: LinkedIn URL, domain, then company name. Companies must have at least one of these identifiers to be searchable.

Request

Path Parameters

string

required

The unique identifier (UUID) of the company to search people for.

Query Parameters

integer

default:0

Page number for pagination (0-indexed). Values less than 0 are normalized to 0.

integer

default:25

Number of results per page. Must be between 1 and 100. Values outside this range are clamped to the nearest valid value.

Response

Person[]

Array of person objects found at the company.

Show Person object properties

string

required

Unique identifier (UUID) for the person.

string

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

string

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

string

required

Person’s first name.

string

required

Person’s last name.

string

Current job title/position. Can be null.

string

City of residence/work. Can be null.

string

Postal/zip code. Can be null.

string

Country of residence/work. Can be null.

string

LinkedIn profile URL (normalized to https://www.linkedin.com format). Can be null.

string[]

Array of phone numbers. Defaults to empty array.

string[]

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

string

UUID of the associated company (matches the requested company ID).

string

Seniority level (e.g., “Senior”, “Manager”, “Director”). Can be null.

string

Industry classification. Can be null.

string

ISO 8601 date of birth. Can be null.

string[]

Array of department names. Defaults to empty array.

string[]

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

string[]

Array of job functions. Defaults to empty array.

string[]

Array of professional skills. Defaults to empty array.

array

Array of language proficiencies. Defaults to empty array.

Show Language object properties

string

Language name (e.g., “English”, “German”). Can be null.

string

Proficiency level (e.g., “Native”, “Fluent”). Can be null.

array

Array of education records. Defaults to empty array.

Show Education object properties

object

Educational institution details.

Show Institution properties

string

Institution ID. Can be null.

string

Institution name. Can be null.

string

Logo URL. Can be null.

string

LinkedIn URL. Can be null.

string

Degree name (e.g., “Bachelor of Science”). Can be null.

string

Field of study (e.g., “Computer Science”). Can be null.

string

Grade or GPA. Can be null.

object

Start and end dates with start and end as string dates. Can be null.

array

Array of work experience records. Defaults to empty array.

Show Work Experience object properties

object

Company information. Can be null.

Show Company properties

string

Company ID. Can be null.

string

Company name. Can be null.

string

Logo URL. Can be null.

string

LinkedIn URL. Can be null.

object

Employee count range with start and end. Can be null.

object

Employment dates with start and end as string dates. Can be null.

array

Array of positions held at the company. Can be null.

Show Position properties

string

Company name. Can be null.

string

Position description. Can be null.

string

Job title. Can be null.

string

Employment type (Full-time, Part-time, etc.). Can be null.

string

Work location. Can be null.

object

Position dates. Can be null.

array

Array of professional certificates. Defaults to empty array.

Show Certificate object properties

string

Certificate name. Can be null.

string

Issuing authority. Can be null.

string

Certificate URL. Can be null.

string

License number. Can be null.

string

Display source. Can be null.

object

Issue and expiry dates. Can be null.

object

LinkedIn profile information. Can be null.

Show LinkedIn Profile properties

string

LinkedIn headline. Can be null.

string

LinkedIn summary/about section. Can be null.

string

Profile picture URL. Can be null.

string

Internal provider indentifier. Can be null.

integer

Bullhorn CRM identifier. Can be null.

string

Generic CRM identifier. Can be null.

string

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

GDPR consent status. Values: UNKNOWN, OPTOUT. Defaults to UNKNOWN.

Source of consent information. Can be null.

ISO 8601 timestamp when consent was last updated. Can be null.

string

ISO 8601 timestamp when the person was soft-deleted. Null if active.

integer

Total number of people matching the search criteria across all pages.

integer

Total number of pages available based on size parameter.

integer

Current page number (0-indexed).

integer

Number of results per page.

Examples

curl -X GET "https://api.lance.app/api/v1/entities/prospects/company/550e8400-e29b-41d4-a716-446655440000/people/search" \
  -H "Authorization: Bearer <token>"

curl -X GET "https://api.lance.app/api/v1/entities/prospects/company/550e8400-e29b-41d4-a716-446655440000/people/search?page=0&size=50" \
  -H "Authorization: Bearer <token>"

curl -X GET "https://api.lance.app/api/v1/entities/prospects/company/550e8400-e29b-41d4-a716-446655440000/people/search?page=2&size=25" \
  -H "Authorization: Bearer <token>"

{
  "content": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "firstName": "Jane",
      "lastName": "Smith",
      "jobTitle": "VP of Engineering",
      "city": "San Francisco",
      "postalCode": "94105",
      "country": "United States",
      "linkedinUrl": "https://www.linkedin.com/in/janesmith",
      "phones": ["+1-555-987-6543"],
      "emails": ["jane.smith@acmetech.com"],
      "companyId": "550e8400-e29b-41d4-a716-446655440000",
      "seniority": "VP",
      "industry": "Software Development",
      "birthDate": null,
      "departments": ["Engineering"],
      "subDepartments": ["Platform"],
      "functions": ["Engineering Management"],
      "skills": ["Leadership", "Software Architecture", "Team Building"],
      "languages": [
        { "language": "English", "level": "Native" },
        { "language": "Spanish", "level": "Professional" }
      ],
      "educations": [
        {
          "institution": {
            "id": null,
            "name": "Stanford University",
            "logoUrl": "https://media.licdn.com/school/stanford.png",
            "linkedinUrl": "https://www.linkedin.com/school/stanford-university"
          },
          "degreeName": "Master of Science",
          "fieldOfStudy": "Computer Science",
          "grade": null,
          "dates": { "start": "2008", "end": "2010" }
        }
      ],
      "workExperiences": [
        {
          "company": {
            "id": null,
            "name": "Acme Technologies",
            "logoUrl": "https://media.licdn.com/company/acme.png",
            "linkedinUrl": "https://www.linkedin.com/company/acme-technologies",
            "employees": { "start": "201", "end": "500" }
          },
          "dates": { "start": "2020-01", "end": null },
          "profilePositions": [
            {
              "company": "Acme Technologies",
              "description": "Leading the engineering organization...",
              "title": "VP of Engineering",
              "employmentType": "Full-time",
              "location": "San Francisco, CA",
              "dates": { "start": "2020-01", "end": null }
            }
          ]
        }
      ],
      "certificates": [],
      "linkedinProfile": {
        "headline": "VP of Engineering at Acme Technologies | Building the future of enterprise software",
        "summary": "Passionate engineering leader with 15+ years of experience...",
        "pictureUrl": "https://media.licdn.com/profile/janesmith.jpg"
      },
      "baseProviderId": "ark_person_789012",
      "bullhornId": null,
      "crmId": null,
      "leadOwnerId": null,
      "consentStatus": "UNKNOWN",
      "consentSource": null,
      "consentUpdatedAt": null,
      "deletedAt": null
    }
  ],
  "totalElements": 156,
  "totalPages": 7,
  "page": 0,
  "size": 25
}

{
  "content": [],
  "totalElements": 0,
  "totalPages": 0,
  "page": 0,
  "size": 25
}

Error Responses

Returned when the specified company does not exist in the database.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Company 550e8400-e29b-41d4-a716-446655440000 not found"
  }
}

Returned when the company exists but lacks sufficient data for searching (missing LinkedIn URL, domain, and company name).

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Company cannot be searched in our database: missing LinkedIn URL, domain, and name"
  }
}

Search Strategy

The endpoint uses a prioritized search strategy to find people at a company:

LinkedIn URL (most reliable): If the company has a LinkedIn company page URL, it is used as the primary filter.
Domain (good fallback): If no LinkedIn URL is available, the company’s domain is used to match people.
Company Name (last resort): If neither LinkedIn URL nor domain is available, the company name is used. This may have more false positives as company names are not unique.

Results are automatically upserted to the database. Existing person records are updated with new data, and new persons are created with fresh UUIDs.

Performance Notes

This endpoint is optimized for performance:

Batch fetches existing persons in a single database query
Uses synchronous mapping instead of N+1 database lookups
Bulk upserts all persons in one operation

For large result sets, use pagination to avoid memory issues and improve response times.

Overview

Lead Lists

ICPs

Users

Prospects

Autocomplete

Enrichment

CRM Integration

Credits & Payments

Data Operations

Search People by Company

Authentication

Request

Path Parameters

Query Parameters

Response

Examples

Error Responses

Search Strategy

Performance Notes

​Authentication

​Request

​Path Parameters

​Query Parameters

​Response

​Examples

​Error Responses

​Search Strategy

​Performance Notes

Authentication

Request

Path Parameters

Query Parameters

Response

Examples

Error Responses

Search Strategy

Performance Notes