---
title: "Search people on LinkedIn"
method: GET
path: "/v1/linkedin/search"
---

# Search people on LinkedIn

`GET /v1/linkedin/search`

## Request

- Base URL: `https://api.veezee.io`
- URL: `https://api.veezee.io/v1/linkedin/search`
- Auth: HTTP bearer

Find people on LinkedIn by keywords and filters. The right tool when you have a name, role, or 'who is the X at Y' question without a profile URL. Pass keywords (free text: name, title, or both) and any of first_name, last_name, title, school, current_company, past_company. If keywords is omitted it is derived from the name or title filters; school or company filters alone are rejected with INVALID_INPUT, so include keywords with those. Company filters accept a company name, slug, numeric id, or URN. current_company names are matched by LinkedIn's own company search: typo-tolerant and fuzzy, so results can include people whose headline merely mentions the company; when you need exact filtering, pass the numeric id or URN (linkedin_get_company returns both). past_company names are resolved to an id for you. Costs 10 credits including the first 10 results; each further 10 results add 1 credit (limit max 30; trial keys max 10). A cursor page is a NEW call priced the same way by its own limit, so one limit=30 call is much cheaper than three limit=10 pages; prefer a larger limit over paginating. Do NOT combine a past_company NAME or a company-URL filter with limit=30: resolving those spends one of the call's three internal fetches, so that combination is rejected; keep limit<=20 with them or pass the numeric id. current_company names never spend a fetch, so they combine with any limit. Returns name, position, location, urn, public_identifier per result, a cursor for the next page, and total_matches. Results with is_anonymous=true are private profiles; do not pass them to linkedin_get_profile. For one known person with a URL/slug, call linkedin_get_profile directly instead.

## Query parameters

- `keywords` string: Free-text query: a name, a title, or both.
- `first_name` string: First-name filter, exact match.
- `last_name` string: Last-name filter, exact match.
- `title` string: Current job title filter.
- `school` string: School or university name filter.
- `current_company` string: Company name, slug, numeric id, or urn:li:fsd_company URN. Names are fuzzy-matched by LinkedIn; ids and URNs filter exactly.
- `past_company` string: Same accepted forms as current_company; names are resolved to an id server-side.
- `limit` integer: How many results to return.
- `cursor` string: Cursor from a previous page.
- `freshness` 'recent' | 'realtime': recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.
- `max_credits` integer: Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.

## Headers

- `Idempotency-Key` string

## Response `200`

people_search envelope (schema_version 2)

- PeopleSearchEnvelope
  - `entity` 'people_search', required
  - `platform` 'linkedin' | 'reddit' | 'x', nullable, required
  - `canonical_url` string, nullable, required
  - `data_as_of` string, nullable, required
  - `schema_version` '2', required
  - `common` object, required
    - `results` object[], required
      - `name` string, required
      - `position` string, nullable, required
      - `location` string, nullable, required
      - `followers` integer, nullable, required
      - `is_verified` boolean, nullable, required
      - `image_url` string, nullable, required
      - `url` string, nullable, required
      - `urn` string, required
      - `public_identifier` string, nullable, required
      - `is_anonymous` boolean, required: True when the profile is private: it exists but linkedin_get_profile cannot dereference it. Do not retry.
    - `cursor` string, nullable, required: Pass back to fetch the next page. Null when exhausted.
    - `next_url` string, nullable, required: Ready-to-GET REST URL for the next page.
    - `total_matches` integer, nullable, required
    - `returned_count` integer, required
    - `truncation_hint` string, nullable, required: Present when total_matches far exceeds returned results; says which filter to add.
  - `platform_fields` object, required
  - `freshness` object, nullable, required
    - `source_retrieved_at` string, nullable, required: When the data was fetched from the source. ISO 8601.
    - `served_at` string, required
    - `cache_age_seconds` integer, nullable, required
    - `served_from_cache` boolean, required: True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are.
    - `freshness_requested` 'recent' | 'realtime', required
    - `freshness_served` 'recent' | 'realtime' | 'stale', required
  - `usage` object, required
    - `receipt_id` string, nullable, required
    - `credits_quoted` integer, required
    - `credits_charged` integer, required
    - `balance_remaining` integer, nullable, required
    - `free_tier_hint` string: Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key. Near the daily cap on unclaimed keys it also carries a claim link to relay to your human (claiming adds one-time credits).

## Other responses

- `400`: INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED
- `401`: UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED
- `402`: INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS
- `403`: NOT_ENTITLED | TRIAL_CAP_EXCEEDED
- `404`: NOT_FOUND
- `409`: IDEMPOTENCY_KEY_REUSED
- `413`: PAYLOAD_TOO_LARGE
- `429`: CONCURRENCY_LIMIT | RATE_LIMITED
- `500`: INTERNAL
- `502`: UPSTREAM_UNAVAILABLE
- `503`: BUDGET_EXHAUSTED

---

[API](https://skmtc.dev/veezee/apis/veezee-api.md) · [All operations](https://skmtc.dev/veezee/apis/veezee-api/llms.txt) · [OpenAPI document](https://skmtc.dev/veezee/apis/veezee-api/revisions/6f1831474e70?raw)