diff --git a/CLAUDE.md b/CLAUDE.md index 3ec7924..cb47ffb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -23,9 +23,10 @@ and step-by-step playbooks). This file is just the quick rules. - **Responses are hand-written models, but the spec — not an example — is the source of truth.** This used to say response schemas were example-only; that is no longer true and following it produced three phantom `Company` fields. The live spec now publishes real - response `properties` on 20 of the 21 endpoints (only `GET /changelog/` is still - example-only), and **every** response object schema is `additionalProperties: false` (236 - of 236). So the spec's key set is *exhaustive*: a field absent from it is not "maybe + response `properties` on all 21 endpoints, and 238 of its 245 response object schemas are + `additionalProperties: false`. The 7 open ones are the `Person` objects and the waterfall + result items, where the API may send keys the spec doesn't list. Everywhere else the spec's + key set is *exhaustive*: a field absent from it is not "maybe undocumented", it provably cannot be returned. Before adding or keeping a response field, check it against the live spec — never against a fixture in `tests/data.py`, which proves only that you wrote the fixture. Audit playbook in `docs/CONTEXT.md` §10. diff --git a/README.md b/README.md index ff4861a..2d81e04 100644 --- a/README.md +++ b/README.md @@ -131,24 +131,22 @@ later are preserved): ```python Person( full_name="Jordan Lee", - # Derived from the first position as " | @" — not the + # Derived from the matched position as " | @" — not the # free-text headline written on the LinkedIn profile. headline="VP of Engineering | @Acme", linkedin_url="https://www.linkedin.com/in/example-person", location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"), - # Positions from the profile, in profile order — read `job_is_current` for the - # current role rather than assuming index 0. + # Only the position that matched your filters — `job_is_current` says whether it + # is current (past jobs are searched only with `include_past_jobs`). experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)], # first_name, last_name, skills, education, certifications, … also present ) ``` -**How many positions land in `experiences[]` depends on the endpoint** — and upstream -currently contradicts itself for `search.people`: the changelog entry of 2026-09-21 says -it returns only the position that matched your filters, while the API reference still -says it returns the full position history. Don't rely on either from a search result. If -you need the person's whole career in profile order, `enrichment.person` returns it -unambiguously (1 record on success, free on a miss): +**How many positions land in `experiences[]` depends on the endpoint.** `search.people`, +`search.employee_finder` and `search.waterfall_icp` return one row per person, with only +the position that matched. If you need the person's whole career in profile order, +`enrichment.person` returns it (1 record on success, free on a miss): ```python if person.linkedin_url: # optional on Person; the call requires a str @@ -347,13 +345,14 @@ client = BlitzAPI( The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs `.phone`) is throttled independently, mirroring the API's own limit, which is also per -endpoint (10 req/s on every plan — 50 on plans created before 2026-09-30; check yours -via `client.account.key_info().max_requests_per_seconds`). The default `5.0` -deliberately sits at half the *lowest* cap — raise it to your key's limit to use the -full budget. A single +endpoint and set by your plan (5 req/s on the free trial, 10 on Start, 25 on Scale, +custom on Build Your Infra; 50 on plans created before 2026-09-30). The API counts it per +account, so every API key of the account shares it; check yours via +`client.account.key_info().max_requests_per_seconds`. The default `5.0` is the free-trial +limit — raise it to your key's limit to use the full budget. A single client instance therefore stays under the limit on every endpoint, so a burst on one -never blocks another. Across multiple processes — which share an endpoint's budget — you -may still hit `429`; the retry path handles that. +never blocks another. Across multiple processes (or several keys of one account) — which +share an endpoint's budget — you may still hit `429`; the retry path handles that. Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one endpoint needs longer than the client default: @@ -376,7 +375,7 @@ try: except InsufficientRecordsError as err: ... # 402 — out of records; err.fair_usage.next_reset_at except AuthenticationError: - ... # 401 — bad key + ... # 401 — missing/invalid key, or no access to this endpoint except APIStatusError as err: print(err.status_code, err.message, err.body) except APIResponseValidationError: @@ -386,10 +385,16 @@ except BlitzError: ``` `429` and `5xx` are retried automatically (with backoff) up to `max_retries`; -`401`/`402`/`404` raise immediately. Connect timeouts and connection errors are retried, +`401`/`402`/`404`/`422`/`423` raise immediately. Connect timeouts and connection errors are retried, but a **read timeout is not** — the server may already have processed (and billed) the request, so it surfaces as `APITimeoutError` rather than risking a double charge. +An invalid request body (including an unknown field at any depth) raises `APIStatusError` +with `status_code == 422`: `err.message` sums up the first three problems, and +`err.body["errors"]` lists up to 20 of them, each as `{"field": ..., "message": ...}` with the +full field path and what to fix. A locked account gets `423` +(`{"blocked": true, "message": ...}`), also raised as `APIStatusError`. + ## Forward compatibility Response models subclass a base configured with `extra="allow"`, so a field the API adds diff --git a/docs/CONTEXT.md b/docs/CONTEXT.md index 49b6e41..bec2225 100644 --- a/docs/CONTEXT.md +++ b/docs/CONTEXT.md @@ -28,18 +28,30 @@ Distribution name: **`blitz-api-py`** (PyPI). Import name: **`blitz_api`**. - **Base URL**: `https://api.blitz-api.ai` - **Auth**: `x-api-key` HTTP header (NOT `Authorization`). Key from [app.blitz-api.ai](https://app.blitz-api.ai). -- **Rate limit**: 10 req/s **per endpoint** on all plans (each endpoint has its own - budget); plans created before 2026-09-30 run at 50 req/s. Per-key value in - `key-info.max_requests_per_seconds` and, live, in `fair_usage.rate_limit`. The SDK's - client-side default stays at **5 rps** — half the cap, per the vendor's own SDK docs. +- **Rate limit**: set by the plan — 5 req/s on the free trial, 10 on Start, 25 on Scale, + custom on Build Your Infra; plans created before 2026-09-30 run at 50 — and counted + **per account and per endpoint** over a 1-second window (every key of the account shares + it; each endpoint has its own budget). The account's value is in + `key-info.max_requests_per_seconds` (may be `"unlimited"`) and, live, in + `fair_usage.rate_limit`. The SDK's client-side default stays at **5 rps**, the free-trial + limit. - **OpenAPI**: 3.1.0. `https://api.blitz-api.ai/openapi` reports `info.version` `1.0.0`; the docs-site mirror (`docs.blitz-api.ai/api-reference/v2.openapi.json`) says `2.0.0`. They are two different documents — the live endpoint is the one `gen_enums.py --fetch` reads and the one to audit against. All endpoints are `/v2/...`. -- **Status conventions**: 401 invalid/missing key · 402 insufficient records · - 404 key not found · 422 invalid request body (e.g. a filter list over 50 entries, or - `null` on a required field) · 429 rate limited (official client waits 60 s then - retries) · 5xx server error. +- **Status conventions**: 400 body that is not valid JSON (the SDK always sends JSON) · + 401 invalid/missing key, or a valid key without access to the route · 402 insufficient + records · 404 unknown path, or key-info found no billing account (`"Customer not found"`); + an unknown key is a 401 · 422 invalid request body (e.g. a filter list over its cap, + `null` on a required field, or since 2026-09-28 an unknown field at any depth), with body + `{success: false, message, errors: [{field, message}]}` — `message` sums up the first + three problems, `errors` lists up to 20, each with its full field path · 423 account + locked (`{blocked: true, message}`) · 429 rate limited (the SDK waits `Retry-After`, 1 s + from the API; 60 s if absent, capped at 120 s) · 503 search temporarily unavailable on + the ten search, jobs, TAM and company-distribution endpoints (`{success: false, found: false, message}`, nothing + charged, retriable) · 5xx server error. No special-casing in the SDK: 422 and 423 are + non-retried `APIStatusError`s (`err.body["errors"]` holds the field list), and 503 retries + as a `ServerError`. ### Endpoint → method → response model (all 21) @@ -297,9 +309,8 @@ Internal decisions worth preserving: the Blitz docs' per-rolling-second wording and the official reference client. A token bucket was rejected: its initial capacity lets a fresh client fire `rps` requests *and* refill within the first second, briefly doubling the rate — the exact pattern the docs say - triggers 429 on bulk runs. Default 5 rps — deliberately **half** the API's current - 10 rps/endpoint cap, which is what the vendor's own SDK docs prescribe, and which leaves - throughput on the table for anyone who raises it to their key's + triggers 429 on bulk runs. Default 5 rps — the free-trial limit (Start is 10, Scale 25), + which leaves throughput on the table for anyone who raises it to their key's `max_requests_per_seconds`. `rate_limit_rps=None` disables it. (Auto-detecting the limit from `key-info` on first call was considered but not implemented — would add a surprise network call on construction.) @@ -387,8 +398,8 @@ in 4.0.0**; `tests/test_exceptions.py` pins its absence so it is not reintroduce - **Generated enum member names** are an upper-snake slug of the value (`"IT Services and IT Consulting"` → `IT_SERVICES_AND_IT_CONSULTING`); collisions get a numeric suffix. The `.value` is always the exact API string. -- **`waterfall_icp` response shape came from the docs**, not the spec (its OpenAPI - example is `null`). Shape: `{results: [{icp, ranking, person}]}`. +- **`waterfall_icp` response shape came from the docs** when it was modelled (its OpenAPI + example was `null`); the live spec now types it. Shape: `{results: [{icp, ranking, person}]}`. - **`Company.linkedin_id` is an int**; `Person`/`Experience` linkedin ids are strings. - **`Location` is one superset model over three differently-sized spec sites — the extras are deliberate.** `Person.location` carries all six keys (`city`, `state_code`, @@ -404,11 +415,14 @@ in 4.0.0**; `tests/test_exceptions.py` pins its absence so it is not reintroduce (superset convention, §5) so it reads `None` on `search.companies` and the TAM builders' companies, whose schemas don't list it — audit output will show it SDK-only at those three sites; expected. Note `null` vs `[]` are distinct there (§5). -- **Every response schema in the spec is closed** — all 236 response object schemas carry - `additionalProperties: false`, and most list every key as `required`. So the spec's key - set for a response object is *exhaustive*: an SDK field absent from it is not "maybe - undocumented", it provably cannot be returned. That makes a full model audit mechanical; - see the §10 playbook. +- **Response schemas in the spec are closed, except around `Person`** — 238 of the 245 + response object schemas carry `additionalProperties: false`, and most list every key as + `required`. So the spec's key set for those objects is *exhaustive*: an SDK field absent + from it is not "maybe undocumented", it provably cannot be returned. The 7 open ones are + the `Person` objects (`search.people` / `employee_finder` results, `person` on + `enrichment.person` and the two reverse lookups) and the waterfall result items and their + `person`: the API may send keys there that the spec doesn't list, which `extra="allow"` + keeps. That makes a full model audit mechanical; see the §10 playbook. - **`HQ.postcode` and `HQ.street` are deliberate extras — keep them.** The spec lists neither: every `hq` object in the live spec — `search.companies`, `enrichment.company`, `tam_by_jobs`, `tam_by_people` — has exactly `city`/`state`/`country_code`/`country_name`/`region`/ @@ -430,9 +444,11 @@ in 4.0.0**; `tests/test_exceptions.py` pins its absence so it is not reintroduce (`"Bachelor of Science, Industrial Engineering"`). Removed outright, no alias — the spec-faithful precedent; `extra="allow"` keeps any stray value reachable. - **`Person.headline` is derived**, not the profile's free-text headline: the API builds it - from the first position as `" | @"`. -- **Search filter lists are capped at 50 entries** server-side (422 past that), and - `waterfall_icp`'s `cascade` at 10 tiers. A `RangeFilter` whose `min` exceeds its `max` + from the first entry of `experiences` (the matched position on the searches) as + `" | @"`. +- **Search filter lists are capped at 50 entries** server-side (422 past that), except the + lists in a `waterfall_icp` tier's `location`, capped at 10 (2026-10-20); `cascade` itself + is capped at 10 tiers. A `RangeFilter` whose `min` exceeds its `max` is also a 422 as of 2026-09-16 (`max: 0` still means unbounded). Documented in `filters.py`, not enforced — the SDK doesn't pre-validate list lengths or range ordering (same posture as the advisory enum typing). @@ -552,7 +568,7 @@ the very first `0.1.0`, see the first-release note in `CONTRIBUTING.md`. - No streaming and no built-in response caching. (Per-call `timeout=` IS supported.) - Rate limiter does not auto-detect the per-key limit from `key-info` (defaults to 5 rps, - half the API's 10 rps/endpoint cap; legacy keys are allowed 50). + the free-trial limit; Start is 10, Scale 25, legacy plans 50). - Client-side rate limiting is per process: it mirrors the server's per-endpoint limit for one client, but multiple processes sharing an endpoint's budget can still exceed it and rely on the 429 retry path (see §5). @@ -865,7 +881,8 @@ the history rather than re-litigating it. encoding a plausible-but-unsourced fact (see (6) below). What #30 asked for that *is* unambiguous shipped instead: the README now routes a reader who needs the whole career to `enrichment.person`, which is correct under either reading. **Still an open question for the - API owner; resolve and then state it plainly.** Note `blitz-api-js` **does** assert the narrow + API owner; resolve and then state it plainly.** — *Settled 2026-10-26 by the API code; see + that entry below.* Note `blitz-api-js` **does** assert the narrow side in its README (PR #23) — a live divergence, filed as an issue on that repo. **(5) Smaller fixes.** `TamJobFilter`/`TamPeopleFilter` docstrings claimed inheritance makes `jobs.search` / `search.people` "keep rejecting" the extra keys — true for dict literals @@ -1014,3 +1031,15 @@ the history rather than re-litigating it. `422` body shape (`errors[]`) is not read (`_make_status_error` takes only `message` / `error`, and `body` is passed through untouched), and the cost change is billing-side. Mirror all of this in `blitz-api-js`. +- **2026-10-26** — Synced to the API code and the 2026-10-20 changelog entry. + **(1) `CascadeTier.location` is `PeopleLocationFilter | list[str]`.** Since 2026-10-20 a + tier's `location` is the `people.location` object of `search.people`, each list capped at 10; + the bare list of country codes is the legacy form, still accepted, so it stays in the union + rather than breaking existing callers. Same type in `blitz-api-js`. + **(2) `experiences[]` on the searches is settled by the code**, closing the open question of + 2026-09-22 (4): `search.people`, `search.employee_finder` and `search.waterfall_icp` each + pass one job per person, the one that matched, and `headline` is built from it. + **(3) Docs only:** the rate limit is per plan and per account (§2); the `422` body's + `errors[]` and the `423` locked-account response are documented in the README rather than + given their own exception classes; `company_distribution_by_department` counts current jobs, + not people. diff --git a/src/blitz_api/_constants.py b/src/blitz_api/_constants.py index c3aca89..bd6a2ca 100644 --- a/src/blitz_api/_constants.py +++ b/src/blitz_api/_constants.py @@ -20,10 +20,11 @@ DEFAULT_MAX_RETRIES = 3 #: Default client-side rate limit, applied **per endpoint** (one sliding window each). -#: The API limits each endpoint to 10 req/s independently — 50 on plans created before -#: 2026-09-30 — so this default deliberately sits at half the *lowest* cap. It therefore -#: leaves throughput on the table by design: raise it to your key's actual per-endpoint -#: value, discoverable via ``client.account.key_info().max_requests_per_seconds``. +#: The API limits each endpoint independently, per account, at a rate set by the plan: 5 req/s +#: on the free trial, 10 on Start, 25 on Scale, custom on Build Your Infra (50 on plans created +#: before 2026-09-30). This default is the free-trial limit, so it leaves throughput on the +#: table on paid plans: raise it to your key's actual per-endpoint value, discoverable via +#: ``client.account.key_info().max_requests_per_seconds``. DEFAULT_RATE_LIMIT_RPS = 5.0 #: Seconds to wait after a 429 when the response has no ``Retry-After`` header. diff --git a/src/blitz_api/_exceptions.py b/src/blitz_api/_exceptions.py index 9ac1599..53b810e 100644 --- a/src/blitz_api/_exceptions.py +++ b/src/blitz_api/_exceptions.py @@ -119,7 +119,11 @@ def __init__( class AuthenticationError(APIStatusError): - """401 — the API key is missing or invalid.""" + """401 — the API key is missing or invalid, or valid but without access to this endpoint + (``"You do not have access to this route"``). + + A locked account gets a ``423`` instead, raised as a plain :class:`APIStatusError`. + """ class InsufficientRecordsError(APIStatusError): @@ -131,7 +135,8 @@ class InsufficientRecordsError(APIStatusError): class NotFoundError(APIStatusError): - """404 — the API key or resource does not exist.""" + """404 — unknown path, or ``account.key_info`` found no billing account + (``"Customer not found"``). An unknown key is a ``401``.""" class RateLimitError(APIStatusError): diff --git a/src/blitz_api/resources/_async/enrichment.py b/src/blitz_api/resources/_async/enrichment.py index 74debd5..ac2ed1a 100644 --- a/src/blitz_api/resources/_async/enrichment.py +++ b/src/blitz_api/resources/_async/enrichment.py @@ -173,10 +173,15 @@ async def company_distribution_by_department( ) -> CompanyDistributionByDepartmentResponse: """Get a company's employee count broken down by department. - Employees with no classified department are counted under ``"Other"``. + Counts current **jobs** at the company, not people, once per current job: a person with + two current jobs there counts twice in ``total_employees`` (once in each job's + department), so ``total_employees`` can exceed the one from + ``company_distribution_by_country``. - ``is_recent_hire=True`` counts only people whose current job at the company started - in the last 90 days (a job with no start date is not counted). + Jobs with no classified department are counted under ``"Other"``. + + ``is_recent_hire=True`` counts only the current jobs at the company that started in the + last 90 days (a job with no start date is not counted). """ return await self._client._request( "POST", diff --git a/src/blitz_api/resources/_async/search.py b/src/blitz_api/resources/_async/search.py index 96fa4c8..1ea66a8 100644 --- a/src/blitz_api/resources/_async/search.py +++ b/src/blitz_api/resources/_async/search.py @@ -96,6 +96,10 @@ async def employee_finder( started in the last 90 days (that job must also match ``job_level`` and ``job_function``; a job with no start date never matches). + Each list is capped at 50 entries (a longer one is a ``422``). ``country_code`` + defaults to ``["WORLD"]`` server-side: a list holding ``"WORLD"`` drops the country + filter. ``min_connections_count`` runs 0-500 (``0`` = no lower bound). + Auto-paginates over every matching employee; use ``.iter_pages()`` or ``page=`` for manual control. """ @@ -138,6 +142,11 @@ async def waterfall_icp( ``include_past_jobs``. With ``include_past_jobs`` a tier finds people by a job they held *before* at the company; the company and that tier's title filters must then hold in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set. + + Each tier's ``location`` takes the same object as ``people.location`` on + ``search.people`` (:class:`~blitz_api.types.PeopleLocationFilter`): a person must match + every field you set, and leaving it out searches the whole world. Here each list takes + at most 10 values (a longer one is a ``422``). """ body = { "company_linkedin_url": company_linkedin_url, diff --git a/src/blitz_api/resources/_sync/enrichment.py b/src/blitz_api/resources/_sync/enrichment.py index 80a922f..5c72924 100644 --- a/src/blitz_api/resources/_sync/enrichment.py +++ b/src/blitz_api/resources/_sync/enrichment.py @@ -175,10 +175,15 @@ def company_distribution_by_department( ) -> CompanyDistributionByDepartmentResponse: """Get a company's employee count broken down by department. - Employees with no classified department are counted under ``"Other"``. + Counts current **jobs** at the company, not people, once per current job: a person with + two current jobs there counts twice in ``total_employees`` (once in each job's + department), so ``total_employees`` can exceed the one from + ``company_distribution_by_country``. - ``is_recent_hire=True`` counts only people whose current job at the company started - in the last 90 days (a job with no start date is not counted). + Jobs with no classified department are counted under ``"Other"``. + + ``is_recent_hire=True`` counts only the current jobs at the company that started in the + last 90 days (a job with no start date is not counted). """ return self._client._request( "POST", diff --git a/src/blitz_api/resources/_sync/search.py b/src/blitz_api/resources/_sync/search.py index be68b24..b149b79 100644 --- a/src/blitz_api/resources/_sync/search.py +++ b/src/blitz_api/resources/_sync/search.py @@ -98,6 +98,10 @@ def employee_finder( started in the last 90 days (that job must also match ``job_level`` and ``job_function``; a job with no start date never matches). + Each list is capped at 50 entries (a longer one is a ``422``). ``country_code`` + defaults to ``["WORLD"]`` server-side: a list holding ``"WORLD"`` drops the country + filter. ``min_connections_count`` runs 0-500 (``0`` = no lower bound). + Auto-paginates over every matching employee; use ``.iter_pages()`` or ``page=`` for manual control. """ @@ -140,6 +144,11 @@ def waterfall_icp( ``include_past_jobs``. With ``include_past_jobs`` a tier finds people by a job they held *before* at the company; the company and that tier's title filters must then hold in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set. + + Each tier's ``location`` takes the same object as ``people.location`` on + ``search.people`` (:class:`~blitz_api.types.PeopleLocationFilter`): a person must match + every field you set, and leaving it out searches the whole world. Here each list takes + at most 10 values (a longer one is a ``422``). """ body = { "company_linkedin_url": company_linkedin_url, diff --git a/src/blitz_api/types/enrichment.py b/src/blitz_api/types/enrichment.py index 9a49192..ec21654 100644 --- a/src/blitz_api/types/enrichment.py +++ b/src/blitz_api/types/enrichment.py @@ -142,7 +142,9 @@ class CompanyDistributionByCountryResponse(BlitzResponse): class CompanyDistributionByDepartmentItem(BlitzModel): """Employee count for a single department (Blitz job function). - Employees with no classified department are counted under ``"Other"``. + ``count`` counts current jobs at the company, not people, once per current job: a person + with two current jobs there counts twice in ``total_employees`` (once in each job's + department). Jobs with no classified department are counted under ``"Other"``. ``percentage_ratio`` is the bucket's share of ``total_employees`` (0-100, to 2 decimals). """ @@ -157,6 +159,10 @@ class CompanyDistributionByDepartmentResponse(BlitzResponse): Served by ``POST /v2/enrichment/company-distribution-by-department``. + ``total_employees`` counts current jobs at the company, not people (a person with two + current jobs there counts twice), so it can exceed the one from + ``enrichment.company_distribution_by_country``. + ``found`` is ``False`` (and the call costs no records) when the company is unknown or has no current employees. """ diff --git a/src/blitz_api/types/filters.py b/src/blitz_api/types/filters.py index 506cabb..a29c002 100644 --- a/src/blitz_api/types/filters.py +++ b/src/blitz_api/types/filters.py @@ -6,8 +6,9 @@ a raw string, so power users are never blocked. All keys are optional unless noted; omit a filter to leave it unset. The search -endpoints cap every filter list at **50 entries** — a longer list is rejected with a -``422``, so split a bigger inclusion/exclusion set across several requests. +endpoints cap every filter list at **50 entries** (10 in a waterfall tier's ``location``, +see :class:`CascadeTier`) — a longer list is rejected with a ``422``, so split a bigger +inclusion/exclusion set across several requests. """ from __future__ import annotations @@ -143,7 +144,7 @@ class CompanyFilter(TypedDict, total=False): ``company.tam_by_people``. ``linkedin_url`` is deliberately **not** here: only the people-side endpoints honour - it, and ``search.companies`` accepts-then-ignores it. See :class:`PeopleCompanyFilter`. + it, and ``search.companies`` rejects it with a ``422``. See :class:`PeopleCompanyFilter`. """ name: KeywordFilter @@ -176,11 +177,9 @@ class PeopleCompanyFilter(CompanyFilter, total=False): Extending, rather than leaving ``linkedin_url`` on the shared filter, keeps it off ``search.companies``: the live spec declares it on the ``company`` object of ``/v2/search/people`` and ``/v2/company/tam-by-people`` but **not** - ``/v2/search/companies``, and request schemas are open (no ``additionalProperties: - false``), so that endpoint accepts the key and silently returns results for your other - criteria. That is the same accepted-but-ignored failure mode that got ``linkedin_url`` - removed from :class:`PeopleFilter`, and the same split as :class:`TamPeopleFilter` over - :class:`PeopleFilter`. + ``/v2/search/companies``, which rejects the key with a ``422`` naming the field (since + 2026-09-28; it used to be accepted and ignored). Same split as :class:`TamPeopleFilter` + over :class:`PeopleFilter`. The assignability caveat on :class:`TamJobFilter` applies verbatim: this only rejects a ``search.companies`` call site that passes a *dict literal* carrying ``linkedin_url``. @@ -202,9 +201,12 @@ class PeopleJobTitleFilter(TypedDict, total=False): class PeopleLocationFilter(TypedDict, total=False): - """Location filter for the people side of a people search.""" + """Location filter for the people side of a people search, and for each waterfall tier + (:class:`CascadeTier`). A person must match every field you set. + """ city: KeywordFilter + # Codes such as ``"FR"`` or ``"GB"`` (2-3 letters, any case). country_code: list[str] continent: list[ContinentValue] sales_region: list[SalesRegionValue] @@ -227,9 +229,8 @@ class PeopleFilter(TypedDict, total=False): """People search criteria for ``search.people``. ``linkedin_url`` is deliberately absent: ``/v2/search/people`` stopped honouring it - on 2026-09-11 (the request still succeeds, but the filter is *ignored*, so you get - results for your other criteria instead of the people you asked for). Match specific - people by LinkedIn URL with ``company.tam_by_people`` (:class:`TamPeopleFilter`), + on 2026-09-11, and since 2026-09-28 rejects it with a ``422`` naming the field. Match + specific people by LinkedIn URL with ``company.tam_by_people`` (:class:`TamPeopleFilter`), which still accepts it. This is the persona criteria ``search.people`` and ``company.tam_by_people`` share; @@ -246,6 +247,7 @@ class PeopleFilter(TypedDict, total=False): job_title: PeopleJobTitleFilter job_function: list[JobFunctionValue] job_level: list[JobLevelValue] + # Smallest LinkedIn connection count (0-500, ``0`` = no lower bound); above 500 is a ``422``. min_connections: int location: PeopleLocationFilter # ``| KeywordFilter`` is deliberate: this field was a ``KeywordFilter`` before it gained @@ -286,9 +288,16 @@ class SearchPeopleFilter(PeopleFilter, total=False): class CascadeTier(TypedDict): """One tier of a waterfall ICP cascade, tried in order until results are found. - Only ``include_title`` is required; the server defaults ``location`` to worldwide - and ``include_headline_search`` to ``False`` when omitted. The ``cascade`` list is - capped at **10 tiers**, and each tier at 50 title phrases. + Only ``include_title`` is required; the server defaults ``include_headline_search`` to + ``False`` when omitted. The ``cascade`` list is capped at **10 tiers**, and each tier at + 50 title phrases. + + ``location`` takes the same object as ``people.location`` on ``search.people`` + (:class:`PeopleLocationFilter`): a person must match every field you set, and leaving it + out searches the whole world. Each list in it takes at most **10 values**; a longer list + is a ``422``. A plain list of country codes (``["US", "CA"]``) is the legacy form, still + accepted: it is read as ``country_code``, with the same 10-code cap, and a list holding + ``"WORLD"`` turns the location filter off. ``is_recent_hire``, ``include_active_jobs`` and ``include_past_jobs`` are per-tier keys, not arguments of ``search.waterfall_icp``: each tier can scope its own search, so a @@ -296,7 +305,7 @@ class CascadeTier(TypedDict): """ include_title: list[str] - location: NotRequired[list[str]] + location: NotRequired[PeopleLocationFilter | list[str]] include_headline_search: NotRequired[bool] exclude_title: NotRequired[list[str]] # Only people whose job at the company started in the last 90 days. It covers the jobs diff --git a/src/blitz_api/types/shared.py b/src/blitz_api/types/shared.py index 71ff2be..02db8d1 100644 --- a/src/blitz_api/types/shared.py +++ b/src/blitz_api/types/shared.py @@ -95,8 +95,8 @@ class Person(BlitzModel): full_name: str | None = None nickname: str | None = None civility_title: str | None = None - #: Built from the person's first position as ``" | @"``, not - #: the free-text headline written on the LinkedIn profile. + #: Built from the first entry of ``experiences`` (the matched position on the searches) + #: as ``" | @"``, not the free-text headline on the LinkedIn profile. headline: str | None = None about_me: str | None = None location: Location | None = None @@ -104,12 +104,11 @@ class Person(BlitzModel): connections_count: int | None = None #: Always ``None`` since 2026-09-15; the API keeps the key so clients don't break. profile_picture_url: str | None = None - #: Positions from the person's profile, in profile order. **How many** positions land - #: here depends on the endpoint, and upstream currently contradicts itself for - #: ``search.people``: the changelog entry of 2026-09-21 says it returns only the - #: position that matched your filters, while the docs still say the whole career. - #: ``enrichment.person`` returns the whole career either way. Read ``job_is_current`` - #: rather than assuming index 0 is the current role. + #: Positions from the person's profile. ``search.people``, ``search.employee_finder`` and + #: ``search.waterfall_icp`` return exactly one: the position that matched, which can be a + #: past one with ``include_past_jobs`` (read ``job_is_current``). ``enrichment.person``, + #: ``enrichment.email_to_person`` and ``enrichment.phone_to_person`` return the whole + #: career, in profile order. experiences: BlitzList[Experience] = [] education: BlitzList[Education] = [] skills: BlitzList[str] = [] diff --git a/tests/test_filters.py b/tests/test_filters.py index cce83e0..044a100 100644 --- a/tests/test_filters.py +++ b/tests/test_filters.py @@ -1,9 +1,8 @@ """Tests that the request-filter ``TypedDict``\\s carry the keys their endpoint accepts. -These pin the *splits* — where one endpoint honours a filter key and a sibling -accepts-then-silently-ignores it. Request schemas are open (no ``additionalProperties: -false``), so the API never rejects the extra key; the type is the only thing standing -between a caller and a query that quietly matched on the wrong criteria. +These pin the *splits* — where one endpoint honours a filter key and a sibling rejects +it with a ``422`` (since 2026-09-28; it used to accept and silently ignore it). The type +catches the mistake before the request is sent. """ from __future__ import annotations