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>"

{
  "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
}

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>"

{
  "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
}

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

page

integer

default:0

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

size

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

content

Person[]

Array of person objects found at the company.

Show Person object properties

string

required

Unique identifier (UUID) for the person.

createdAt

string

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

updatedAt

string

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

firstName

string

required

Person’s first name.

lastName

string

required

Person’s last name.

jobTitle

string

Current job title/position. Can be null.

city

string

City of residence/work. Can be null.

postalCode

string

Postal/zip code. Can be null.

country

string

Country of residence/work. Can be null.

linkedinUrl

string

LinkedIn profile URL (normalized to https://www.linkedin.com format). 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 (matches the requested company ID).

seniority

string

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

industry

string

Industry classification. Can be null.

birthDate

string

ISO 8601 date of birth. 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 professional skills. Defaults to empty array.

languages

array

Array of language proficiencies. Defaults to empty array.

Show Language object properties

language

string

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

level

string

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

educations

array

Array of education records. Defaults to empty array.

Show Education object properties

institution

object

Educational institution details.

Show Institution properties

string

Institution ID. Can be null.

name

string

Institution name. Can be null.

logoUrl

string

Logo URL. Can be null.

linkedinUrl

string

LinkedIn URL. Can be null.

degreeName

string

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

fieldOfStudy

string

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

grade

string

Grade or GPA. Can be null.

dates

object

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

workExperiences

array

Array of work experience records. Defaults to empty array.

Show Work Experience object properties

company

object

Company information. Can be null.

Show Company properties

string

Company ID. Can be null.

name

string

Company name. Can be null.

logoUrl

string

Logo URL. Can be null.

linkedinUrl

string

LinkedIn URL. Can be null.

employees

object

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

dates

object

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

profilePositions

array

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

Show Position properties

company

string

Company name. Can be null.

description

string

Position description. Can be null.

title

string

Job title. Can be null.

employmentType

string

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

location

string

Work location. Can be null.

dates

object

Position dates. Can be null.

certificates

array

Array of professional certificates. Defaults to empty array.

Show Certificate object properties

name

string

Certificate name. Can be null.

authority

string

Issuing authority. Can be null.

url

string

Certificate URL. Can be null.

license_number

string

License number. Can be null.

display_source

string

Display source. Can be null.

date

object

Issue and expiry dates. Can be null.

linkedinProfile

object

LinkedIn profile information. Can be null.

Show LinkedIn Profile properties

headline

string

LinkedIn headline. Can be null.

summary

string

LinkedIn summary/about section. Can be null.

pictureUrl

string

Profile picture URL. Can be null.

baseProviderId

string

Internal provider indentifier. Can be null.

bullhornId

integer

Bullhorn CRM 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.

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.

deletedAt

string

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

totalElements

integer

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

totalPages

integer

Total number of pages available based on size parameter.

page

integer

Current page number (0-indexed).

size

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>"

{
  "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
}

Error Responses

404 Not Found

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

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

400 Bad Request

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.

Get Prospect Company Search Person Prospects

​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