blitz-api-py 4.1.0__tar.gz → 4.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/CHANGELOG.md +8 -0
  2. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/PKG-INFO +24 -19
  3. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/README.md +22 -17
  4. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/pyproject.toml +1 -1
  5. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_constants.py +5 -4
  6. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_exceptions.py +7 -2
  7. blitz_api_py-4.2.0/src/blitz_api/_version.py +1 -0
  8. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/enrichment.py +8 -3
  9. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/search.py +9 -0
  10. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/enrichment.py +8 -3
  11. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/search.py +9 -0
  12. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/enrichment.py +7 -1
  13. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/filters.py +25 -16
  14. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/shared.py +7 -8
  15. blitz_api_py-4.1.0/src/blitz_api/_version.py +0 -1
  16. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/.gitignore +0 -0
  17. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/LICENSE +0 -0
  18. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/__init__.py +0 -0
  19. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_base_client.py +0 -0
  20. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_client.py +0 -0
  21. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_client_async.py +0 -0
  22. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_client_sync.py +0 -0
  23. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_compat.py +0 -0
  24. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_pagination_async.py +0 -0
  25. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_pagination_base.py +0 -0
  26. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_pagination_sync.py +0 -0
  27. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_rate_limit.py +0 -0
  28. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_rate_limit_async.py +0 -0
  29. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_rate_limit_sync.py +0 -0
  30. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/py.typed +0 -0
  31. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/__init__.py +0 -0
  32. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/__init__.py +0 -0
  33. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/account.py +0 -0
  34. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/changelog.py +0 -0
  35. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/company.py +0 -0
  36. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/jobs.py +0 -0
  37. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/utils.py +0 -0
  38. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
  39. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/account.py +0 -0
  40. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/changelog.py +0 -0
  41. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/company.py +0 -0
  42. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/jobs.py +0 -0
  43. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/utils.py +0 -0
  44. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/__init__.py +0 -0
  45. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/_models.py +0 -0
  46. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/account.py +0 -0
  47. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/changelog.py +0 -0
  48. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/company.py +0 -0
  49. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/enums.py +0 -0
  50. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/jobs.py +0 -0
  51. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/search.py +0 -0
  52. {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/utils.py +0 -0
@@ -1,5 +1,13 @@
1
1
  # Changelog
2
2
 
3
+ ## [4.2.0](https://github.com/api-blitz/blitz-api-py/compare/v4.1.0...v4.2.0) (2026-10-27)
4
+
5
+
6
+ ### Features
7
+
8
+ * sync with the 2026-10-20 API release ([00fb319](https://github.com/api-blitz/blitz-api-py/commit/00fb31984488fa64561dd23e136963dd0eaea7e1))
9
+ * sync with the 2026-10-20 API release ([aba0662](https://github.com/api-blitz/blitz-api-py/commit/aba066208f802d07b1a9fc1a44fd1e023c835e2c))
10
+
3
11
  ## [4.1.0](https://github.com/api-blitz/blitz-api-py/compare/v4.0.0...v4.1.0) (2026-10-15)
4
12
 
5
13
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: blitz-api-py
3
- Version: 4.1.0
3
+ Version: 4.2.0
4
4
  Summary: Typed Python SDK for the Blitz API — B2B data, search, and enrichment.
5
5
  Project-URL: Homepage, https://blitz-api.ai
6
6
  Project-URL: Documentation, https://docs.blitz-api.ai
@@ -10,7 +10,7 @@ Project-URL: Changelog, https://github.com/api-blitz/blitz-api-py/blob/main/CHAN
10
10
  Author-email: Blitz API <founders@blitz-api.ai>
11
11
  License-Expression: MIT
12
12
  License-File: LICENSE
13
- Keywords: b2b,blitz,blitz-api,enrichment,gtm,linkedin,sales,sdk
13
+ Keywords: b2b,blitz,blitz-api,enrichment,gtm,sales,sdk
14
14
  Classifier: Development Status :: 4 - Beta
15
15
  Classifier: Intended Audience :: Developers
16
16
  Classifier: License :: OSI Approved :: MIT License
@@ -162,24 +162,22 @@ later are preserved):
162
162
  ```python
163
163
  Person(
164
164
  full_name="Jordan Lee",
165
- # Derived from the first position as "<job title> | @<employer>" — not the
165
+ # Derived from the matched position as "<job title> | @<employer>" — not the
166
166
  # free-text headline written on the LinkedIn profile.
167
167
  headline="VP of Engineering | @Acme",
168
168
  linkedin_url="https://www.linkedin.com/in/example-person",
169
169
  location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
170
- # Positions from the profile, in profile order — read `job_is_current` for the
171
- # current role rather than assuming index 0.
170
+ # Only the position that matched your filters — `job_is_current` says whether it
171
+ # is current (past jobs are searched only with `include_past_jobs`).
172
172
  experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
173
173
  # first_name, last_name, skills, education, certifications, … also present
174
174
  )
175
175
  ```
176
176
 
177
- **How many positions land in `experiences[]` depends on the endpoint** — and upstream
178
- currently contradicts itself for `search.people`: the changelog entry of 2026-09-21 says
179
- it returns only the position that matched your filters, while the API reference still
180
- says it returns the full position history. Don't rely on either from a search result. If
181
- you need the person's whole career in profile order, `enrichment.person` returns it
182
- unambiguously (1 record on success, free on a miss):
177
+ **How many positions land in `experiences[]` depends on the endpoint.** `search.people`,
178
+ `search.employee_finder` and `search.waterfall_icp` return one row per person, with only
179
+ the position that matched. If you need the person's whole career in profile order,
180
+ `enrichment.person` returns it (1 record on success, free on a miss):
183
181
 
184
182
  ```python
185
183
  if person.linkedin_url: # optional on Person; the call requires a str
@@ -378,13 +376,14 @@ client = BlitzAPI(
378
376
  The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
379
377
  in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
380
378
  `.phone`) is throttled independently, mirroring the API's own limit, which is also per
381
- endpoint (10 req/s on every plan — 50 on plans created before 2026-09-30; check yours
382
- via `client.account.key_info().max_requests_per_seconds`). The default `5.0`
383
- deliberately sits at half the *lowest* cap — raise it to your key's limit to use the
384
- full budget. A single
379
+ endpoint and set by your plan (5 req/s on the free trial, 10 on Start, 25 on Scale,
380
+ custom on Build Your Infra; 50 on plans created before 2026-09-30). The API counts it per
381
+ account, so every API key of the account shares it; check yours via
382
+ `client.account.key_info().max_requests_per_seconds`. The default `5.0` is the free-trial
383
+ limit — raise it to your key's limit to use the full budget. A single
385
384
  client instance therefore stays under the limit on every endpoint, so a burst on one
386
- never blocks another. Across multiple processes — which share an endpoint's budget — you
387
- may still hit `429`; the retry path handles that.
385
+ never blocks another. Across multiple processes (or several keys of one account) — which
386
+ share an endpoint's budget — you may still hit `429`; the retry path handles that.
388
387
 
389
388
  Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
390
389
  endpoint needs longer than the client default:
@@ -407,7 +406,7 @@ try:
407
406
  except InsufficientRecordsError as err:
408
407
  ... # 402 — out of records; err.fair_usage.next_reset_at
409
408
  except AuthenticationError:
410
- ... # 401 — bad key
409
+ ... # 401 — missing/invalid key, or no access to this endpoint
411
410
  except APIStatusError as err:
412
411
  print(err.status_code, err.message, err.body)
413
412
  except APIResponseValidationError:
@@ -417,10 +416,16 @@ except BlitzError:
417
416
  ```
418
417
 
419
418
  `429` and `5xx` are retried automatically (with backoff) up to `max_retries`;
420
- `401`/`402`/`404` raise immediately. Connect timeouts and connection errors are retried,
419
+ `401`/`402`/`404`/`422`/`423` raise immediately. Connect timeouts and connection errors are retried,
421
420
  but a **read timeout is not** — the server may already have processed (and billed) the
422
421
  request, so it surfaces as `APITimeoutError` rather than risking a double charge.
423
422
 
423
+ An invalid request body (including an unknown field at any depth) raises `APIStatusError`
424
+ with `status_code == 422`: `err.message` sums up the first three problems, and
425
+ `err.body["errors"]` lists up to 20 of them, each as `{"field": ..., "message": ...}` with the
426
+ full field path and what to fix. A locked account gets `423`
427
+ (`{"blocked": true, "message": ...}`), also raised as `APIStatusError`.
428
+
424
429
  ## Forward compatibility
425
430
 
426
431
  Response models subclass a base configured with `extra="allow"`, so a field the API adds
@@ -131,24 +131,22 @@ later are preserved):
131
131
  ```python
132
132
  Person(
133
133
  full_name="Jordan Lee",
134
- # Derived from the first position as "<job title> | @<employer>" — not the
134
+ # Derived from the matched position as "<job title> | @<employer>" — not the
135
135
  # free-text headline written on the LinkedIn profile.
136
136
  headline="VP of Engineering | @Acme",
137
137
  linkedin_url="https://www.linkedin.com/in/example-person",
138
138
  location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
139
- # Positions from the profile, in profile order — read `job_is_current` for the
140
- # current role rather than assuming index 0.
139
+ # Only the position that matched your filters — `job_is_current` says whether it
140
+ # is current (past jobs are searched only with `include_past_jobs`).
141
141
  experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
142
142
  # first_name, last_name, skills, education, certifications, … also present
143
143
  )
144
144
  ```
145
145
 
146
- **How many positions land in `experiences[]` depends on the endpoint** — and upstream
147
- currently contradicts itself for `search.people`: the changelog entry of 2026-09-21 says
148
- it returns only the position that matched your filters, while the API reference still
149
- says it returns the full position history. Don't rely on either from a search result. If
150
- you need the person's whole career in profile order, `enrichment.person` returns it
151
- unambiguously (1 record on success, free on a miss):
146
+ **How many positions land in `experiences[]` depends on the endpoint.** `search.people`,
147
+ `search.employee_finder` and `search.waterfall_icp` return one row per person, with only
148
+ the position that matched. If you need the person's whole career in profile order,
149
+ `enrichment.person` returns it (1 record on success, free on a miss):
152
150
 
153
151
  ```python
154
152
  if person.linkedin_url: # optional on Person; the call requires a str
@@ -347,13 +345,14 @@ client = BlitzAPI(
347
345
  The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
348
346
  in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
349
347
  `.phone`) is throttled independently, mirroring the API's own limit, which is also per
350
- endpoint (10 req/s on every plan — 50 on plans created before 2026-09-30; check yours
351
- via `client.account.key_info().max_requests_per_seconds`). The default `5.0`
352
- deliberately sits at half the *lowest* cap — raise it to your key's limit to use the
353
- full budget. A single
348
+ endpoint and set by your plan (5 req/s on the free trial, 10 on Start, 25 on Scale,
349
+ custom on Build Your Infra; 50 on plans created before 2026-09-30). The API counts it per
350
+ account, so every API key of the account shares it; check yours via
351
+ `client.account.key_info().max_requests_per_seconds`. The default `5.0` is the free-trial
352
+ limit — raise it to your key's limit to use the full budget. A single
354
353
  client instance therefore stays under the limit on every endpoint, so a burst on one
355
- never blocks another. Across multiple processes — which share an endpoint's budget — you
356
- may still hit `429`; the retry path handles that.
354
+ never blocks another. Across multiple processes (or several keys of one account) — which
355
+ share an endpoint's budget — you may still hit `429`; the retry path handles that.
357
356
 
358
357
  Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
359
358
  endpoint needs longer than the client default:
@@ -376,7 +375,7 @@ try:
376
375
  except InsufficientRecordsError as err:
377
376
  ... # 402 — out of records; err.fair_usage.next_reset_at
378
377
  except AuthenticationError:
379
- ... # 401 — bad key
378
+ ... # 401 — missing/invalid key, or no access to this endpoint
380
379
  except APIStatusError as err:
381
380
  print(err.status_code, err.message, err.body)
382
381
  except APIResponseValidationError:
@@ -386,10 +385,16 @@ except BlitzError:
386
385
  ```
387
386
 
388
387
  `429` and `5xx` are retried automatically (with backoff) up to `max_retries`;
389
- `401`/`402`/`404` raise immediately. Connect timeouts and connection errors are retried,
388
+ `401`/`402`/`404`/`422`/`423` raise immediately. Connect timeouts and connection errors are retried,
390
389
  but a **read timeout is not** — the server may already have processed (and billed) the
391
390
  request, so it surfaces as `APITimeoutError` rather than risking a double charge.
392
391
 
392
+ An invalid request body (including an unknown field at any depth) raises `APIStatusError`
393
+ with `status_code == 422`: `err.message` sums up the first three problems, and
394
+ `err.body["errors"]` lists up to 20 of them, each as `{"field": ..., "message": ...}` with the
395
+ full field path and what to fix. A locked account gets `423`
396
+ (`{"blocked": true, "message": ...}`), also raised as `APIStatusError`.
397
+
393
398
  ## Forward compatibility
394
399
 
395
400
  Response models subclass a base configured with `extra="allow"`, so a field the API adds
@@ -11,7 +11,7 @@ requires-python = ">=3.10"
11
11
  license = "MIT"
12
12
  license-files = ["LICENSE"]
13
13
  authors = [{ name = "Blitz API", email = "founders@blitz-api.ai" }]
14
- keywords = ["blitz", "blitz-api", "b2b", "enrichment", "linkedin", "sales", "gtm", "sdk"]
14
+ keywords = ["blitz", "blitz-api", "b2b", "enrichment", "sales", "gtm", "sdk"]
15
15
  classifiers = [
16
16
  "Development Status :: 4 - Beta",
17
17
  "Intended Audience :: Developers",
@@ -20,10 +20,11 @@ DEFAULT_TIMEOUT = 30.0
20
20
  DEFAULT_MAX_RETRIES = 3
21
21
 
22
22
  #: Default client-side rate limit, applied **per endpoint** (one sliding window each).
23
- #: The API limits each endpoint to 10 req/s independently — 50 on plans created before
24
- #: 2026-09-30 — so this default deliberately sits at half the *lowest* cap. It therefore
25
- #: leaves throughput on the table by design: raise it to your key's actual per-endpoint
26
- #: value, discoverable via ``client.account.key_info().max_requests_per_seconds``.
23
+ #: The API limits each endpoint independently, per account, at a rate set by the plan: 5 req/s
24
+ #: on the free trial, 10 on Start, 25 on Scale, custom on Build Your Infra (50 on plans created
25
+ #: before 2026-09-30). This default is the free-trial limit, so it leaves throughput on the
26
+ #: table on paid plans: raise it to your key's actual per-endpoint value, discoverable via
27
+ #: ``client.account.key_info().max_requests_per_seconds``.
27
28
  DEFAULT_RATE_LIMIT_RPS = 5.0
28
29
 
29
30
  #: Seconds to wait after a 429 when the response has no ``Retry-After`` header.
@@ -119,7 +119,11 @@ class APIStatusError(BlitzError):
119
119
 
120
120
 
121
121
  class AuthenticationError(APIStatusError):
122
- """401 — the API key is missing or invalid."""
122
+ """401 — the API key is missing or invalid, or valid but without access to this endpoint
123
+ (``"You do not have access to this route"``).
124
+
125
+ A locked account gets a ``423`` instead, raised as a plain :class:`APIStatusError`.
126
+ """
123
127
 
124
128
 
125
129
  class InsufficientRecordsError(APIStatusError):
@@ -131,7 +135,8 @@ class InsufficientRecordsError(APIStatusError):
131
135
 
132
136
 
133
137
  class NotFoundError(APIStatusError):
134
- """404 — the API key or resource does not exist."""
138
+ """404 — unknown path, or ``account.key_info`` found no billing account
139
+ (``"Customer not found"``). An unknown key is a ``401``."""
135
140
 
136
141
 
137
142
  class RateLimitError(APIStatusError):
@@ -0,0 +1 @@
1
+ __version__ = "4.2.0" # x-release-please-version
@@ -173,10 +173,15 @@ class AsyncEnrichmentResource:
173
173
  ) -> CompanyDistributionByDepartmentResponse:
174
174
  """Get a company's employee count broken down by department.
175
175
 
176
- Employees with no classified department are counted under ``"Other"``.
176
+ Counts current **jobs** at the company, not people, once per current job: a person with
177
+ two current jobs there counts twice in ``total_employees`` (once in each job's
178
+ department), so ``total_employees`` can exceed the one from
179
+ ``company_distribution_by_country``.
177
180
 
178
- ``is_recent_hire=True`` counts only people whose current job at the company started
179
- in the last 90 days (a job with no start date is not counted).
181
+ Jobs with no classified department are counted under ``"Other"``.
182
+
183
+ ``is_recent_hire=True`` counts only the current jobs at the company that started in the
184
+ last 90 days (a job with no start date is not counted).
180
185
  """
181
186
  return await self._client._request(
182
187
  "POST",
@@ -96,6 +96,10 @@ class AsyncSearchResource:
96
96
  started in the last 90 days (that job must also match ``job_level`` and
97
97
  ``job_function``; a job with no start date never matches).
98
98
 
99
+ Each list is capped at 50 entries (a longer one is a ``422``). ``country_code``
100
+ defaults to ``["WORLD"]`` server-side: a list holding ``"WORLD"`` drops the country
101
+ filter. ``min_connections_count`` runs 0-500 (``0`` = no lower bound).
102
+
99
103
  Auto-paginates over every matching employee; use ``.iter_pages()`` or ``page=``
100
104
  for manual control.
101
105
  """
@@ -138,6 +142,11 @@ class AsyncSearchResource:
138
142
  ``include_past_jobs``. With ``include_past_jobs`` a tier finds people by a job they
139
143
  held *before* at the company; the company and that tier's title filters must then hold
140
144
  in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set.
145
+
146
+ Each tier's ``location`` takes the same object as ``people.location`` on
147
+ ``search.people`` (:class:`~blitz_api.types.PeopleLocationFilter`): a person must match
148
+ every field you set, and leaving it out searches the whole world. Here each list takes
149
+ at most 10 values (a longer one is a ``422``).
141
150
  """
142
151
  body = {
143
152
  "company_linkedin_url": company_linkedin_url,
@@ -175,10 +175,15 @@ class EnrichmentResource:
175
175
  ) -> CompanyDistributionByDepartmentResponse:
176
176
  """Get a company's employee count broken down by department.
177
177
 
178
- Employees with no classified department are counted under ``"Other"``.
178
+ Counts current **jobs** at the company, not people, once per current job: a person with
179
+ two current jobs there counts twice in ``total_employees`` (once in each job's
180
+ department), so ``total_employees`` can exceed the one from
181
+ ``company_distribution_by_country``.
179
182
 
180
- ``is_recent_hire=True`` counts only people whose current job at the company started
181
- in the last 90 days (a job with no start date is not counted).
183
+ Jobs with no classified department are counted under ``"Other"``.
184
+
185
+ ``is_recent_hire=True`` counts only the current jobs at the company that started in the
186
+ last 90 days (a job with no start date is not counted).
182
187
  """
183
188
  return self._client._request(
184
189
  "POST",
@@ -98,6 +98,10 @@ class SearchResource:
98
98
  started in the last 90 days (that job must also match ``job_level`` and
99
99
  ``job_function``; a job with no start date never matches).
100
100
 
101
+ Each list is capped at 50 entries (a longer one is a ``422``). ``country_code``
102
+ defaults to ``["WORLD"]`` server-side: a list holding ``"WORLD"`` drops the country
103
+ filter. ``min_connections_count`` runs 0-500 (``0`` = no lower bound).
104
+
101
105
  Auto-paginates over every matching employee; use ``.iter_pages()`` or ``page=``
102
106
  for manual control.
103
107
  """
@@ -140,6 +144,11 @@ class SearchResource:
140
144
  ``include_past_jobs``. With ``include_past_jobs`` a tier finds people by a job they
141
145
  held *before* at the company; the company and that tier's title filters must then hold
142
146
  in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set.
147
+
148
+ Each tier's ``location`` takes the same object as ``people.location`` on
149
+ ``search.people`` (:class:`~blitz_api.types.PeopleLocationFilter`): a person must match
150
+ every field you set, and leaving it out searches the whole world. Here each list takes
151
+ at most 10 values (a longer one is a ``422``).
143
152
  """
144
153
  body = {
145
154
  "company_linkedin_url": company_linkedin_url,
@@ -142,7 +142,9 @@ class CompanyDistributionByCountryResponse(BlitzResponse):
142
142
  class CompanyDistributionByDepartmentItem(BlitzModel):
143
143
  """Employee count for a single department (Blitz job function).
144
144
 
145
- Employees with no classified department are counted under ``"Other"``.
145
+ ``count`` counts current jobs at the company, not people, once per current job: a person
146
+ with two current jobs there counts twice in ``total_employees`` (once in each job's
147
+ department). Jobs with no classified department are counted under ``"Other"``.
146
148
  ``percentage_ratio`` is the bucket's share of ``total_employees`` (0-100, to 2
147
149
  decimals).
148
150
  """
@@ -157,6 +159,10 @@ class CompanyDistributionByDepartmentResponse(BlitzResponse):
157
159
 
158
160
  Served by ``POST /v2/enrichment/company-distribution-by-department``.
159
161
 
162
+ ``total_employees`` counts current jobs at the company, not people (a person with two
163
+ current jobs there counts twice), so it can exceed the one from
164
+ ``enrichment.company_distribution_by_country``.
165
+
160
166
  ``found`` is ``False`` (and the call costs no records) when the company is unknown or
161
167
  has no current employees.
162
168
  """
@@ -6,8 +6,9 @@ fields accept either an enum member (autocompleted, e.g. ``Industry.BANKING``) o
6
6
  a raw string, so power users are never blocked.
7
7
 
8
8
  All keys are optional unless noted; omit a filter to leave it unset. The search
9
- endpoints cap every filter list at **50 entries** — a longer list is rejected with a
10
- ``422``, so split a bigger inclusion/exclusion set across several requests.
9
+ endpoints cap every filter list at **50 entries** (10 in a waterfall tier's ``location``,
10
+ see :class:`CascadeTier`) — a longer list is rejected with a ``422``, so split a bigger
11
+ inclusion/exclusion set across several requests.
11
12
  """
12
13
 
13
14
  from __future__ import annotations
@@ -143,7 +144,7 @@ class CompanyFilter(TypedDict, total=False):
143
144
  ``company.tam_by_people``.
144
145
 
145
146
  ``linkedin_url`` is deliberately **not** here: only the people-side endpoints honour
146
- it, and ``search.companies`` accepts-then-ignores it. See :class:`PeopleCompanyFilter`.
147
+ it, and ``search.companies`` rejects it with a ``422``. See :class:`PeopleCompanyFilter`.
147
148
  """
148
149
 
149
150
  name: KeywordFilter
@@ -176,11 +177,9 @@ class PeopleCompanyFilter(CompanyFilter, total=False):
176
177
  Extending, rather than leaving ``linkedin_url`` on the shared filter, keeps it off
177
178
  ``search.companies``: the live spec declares it on the ``company`` object of
178
179
  ``/v2/search/people`` and ``/v2/company/tam-by-people`` but **not**
179
- ``/v2/search/companies``, and request schemas are open (no ``additionalProperties:
180
- false``), so that endpoint accepts the key and silently returns results for your other
181
- criteria. That is the same accepted-but-ignored failure mode that got ``linkedin_url``
182
- removed from :class:`PeopleFilter`, and the same split as :class:`TamPeopleFilter` over
183
- :class:`PeopleFilter`.
180
+ ``/v2/search/companies``, which rejects the key with a ``422`` naming the field (since
181
+ 2026-09-28; it used to be accepted and ignored). Same split as :class:`TamPeopleFilter`
182
+ over :class:`PeopleFilter`.
184
183
 
185
184
  The assignability caveat on :class:`TamJobFilter` applies verbatim: this only rejects a
186
185
  ``search.companies`` call site that passes a *dict literal* carrying ``linkedin_url``.
@@ -202,9 +201,12 @@ class PeopleJobTitleFilter(TypedDict, total=False):
202
201
 
203
202
 
204
203
  class PeopleLocationFilter(TypedDict, total=False):
205
- """Location filter for the people side of a people search."""
204
+ """Location filter for the people side of a people search, and for each waterfall tier
205
+ (:class:`CascadeTier`). A person must match every field you set.
206
+ """
206
207
 
207
208
  city: KeywordFilter
209
+ # Codes such as ``"FR"`` or ``"GB"`` (2-3 letters, any case).
208
210
  country_code: list[str]
209
211
  continent: list[ContinentValue]
210
212
  sales_region: list[SalesRegionValue]
@@ -227,9 +229,8 @@ class PeopleFilter(TypedDict, total=False):
227
229
  """People search criteria for ``search.people``.
228
230
 
229
231
  ``linkedin_url`` is deliberately absent: ``/v2/search/people`` stopped honouring it
230
- on 2026-09-11 (the request still succeeds, but the filter is *ignored*, so you get
231
- results for your other criteria instead of the people you asked for). Match specific
232
- people by LinkedIn URL with ``company.tam_by_people`` (:class:`TamPeopleFilter`),
232
+ on 2026-09-11, and since 2026-09-28 rejects it with a ``422`` naming the field. Match
233
+ specific people by LinkedIn URL with ``company.tam_by_people`` (:class:`TamPeopleFilter`),
233
234
  which still accepts it.
234
235
 
235
236
  This is the persona criteria ``search.people`` and ``company.tam_by_people`` share;
@@ -246,6 +247,7 @@ class PeopleFilter(TypedDict, total=False):
246
247
  job_title: PeopleJobTitleFilter
247
248
  job_function: list[JobFunctionValue]
248
249
  job_level: list[JobLevelValue]
250
+ # Smallest LinkedIn connection count (0-500, ``0`` = no lower bound); above 500 is a ``422``.
249
251
  min_connections: int
250
252
  location: PeopleLocationFilter
251
253
  # ``| KeywordFilter`` is deliberate: this field was a ``KeywordFilter`` before it gained
@@ -286,9 +288,16 @@ class SearchPeopleFilter(PeopleFilter, total=False):
286
288
  class CascadeTier(TypedDict):
287
289
  """One tier of a waterfall ICP cascade, tried in order until results are found.
288
290
 
289
- Only ``include_title`` is required; the server defaults ``location`` to worldwide
290
- and ``include_headline_search`` to ``False`` when omitted. The ``cascade`` list is
291
- capped at **10 tiers**, and each tier at 50 title phrases.
291
+ Only ``include_title`` is required; the server defaults ``include_headline_search`` to
292
+ ``False`` when omitted. The ``cascade`` list is capped at **10 tiers**, and each tier at
293
+ 50 title phrases.
294
+
295
+ ``location`` takes the same object as ``people.location`` on ``search.people``
296
+ (:class:`PeopleLocationFilter`): a person must match every field you set, and leaving it
297
+ out searches the whole world. Each list in it takes at most **10 values**; a longer list
298
+ is a ``422``. A plain list of country codes (``["US", "CA"]``) is the legacy form, still
299
+ accepted: it is read as ``country_code``, with the same 10-code cap, and a list holding
300
+ ``"WORLD"`` turns the location filter off.
292
301
 
293
302
  ``is_recent_hire``, ``include_active_jobs`` and ``include_past_jobs`` are per-tier keys,
294
303
  not arguments of ``search.waterfall_icp``: each tier can scope its own search, so a
@@ -296,7 +305,7 @@ class CascadeTier(TypedDict):
296
305
  """
297
306
 
298
307
  include_title: list[str]
299
- location: NotRequired[list[str]]
308
+ location: NotRequired[PeopleLocationFilter | list[str]]
300
309
  include_headline_search: NotRequired[bool]
301
310
  exclude_title: NotRequired[list[str]]
302
311
  # Only people whose job at the company started in the last 90 days. It covers the jobs
@@ -95,8 +95,8 @@ class Person(BlitzModel):
95
95
  full_name: str | None = None
96
96
  nickname: str | None = None
97
97
  civility_title: str | None = None
98
- #: Built from the person's first position as ``"<job title> | @<employer>"``, not
99
- #: the free-text headline written on the LinkedIn profile.
98
+ #: Built from the first entry of ``experiences`` (the matched position on the searches)
99
+ #: as ``"<job title> | @<employer>"``, not the free-text headline on the LinkedIn profile.
100
100
  headline: str | None = None
101
101
  about_me: str | None = None
102
102
  location: Location | None = None
@@ -104,12 +104,11 @@ class Person(BlitzModel):
104
104
  connections_count: int | None = None
105
105
  #: Always ``None`` since 2026-09-15; the API keeps the key so clients don't break.
106
106
  profile_picture_url: str | None = None
107
- #: Positions from the person's profile, in profile order. **How many** positions land
108
- #: here depends on the endpoint, and upstream currently contradicts itself for
109
- #: ``search.people``: the changelog entry of 2026-09-21 says it returns only the
110
- #: position that matched your filters, while the docs still say the whole career.
111
- #: ``enrichment.person`` returns the whole career either way. Read ``job_is_current``
112
- #: rather than assuming index 0 is the current role.
107
+ #: Positions from the person's profile. ``search.people``, ``search.employee_finder`` and
108
+ #: ``search.waterfall_icp`` return exactly one: the position that matched, which can be a
109
+ #: past one with ``include_past_jobs`` (read ``job_is_current``). ``enrichment.person``,
110
+ #: ``enrichment.email_to_person`` and ``enrichment.phone_to_person`` return the whole
111
+ #: career, in profile order.
113
112
  experiences: BlitzList[Experience] = []
114
113
  education: BlitzList[Education] = []
115
114
  skills: BlitzList[str] = []
@@ -1 +0,0 @@
1
- __version__ = "4.1.0" # x-release-please-version
File without changes
File without changes