blitz-api-py 4.0.0__tar.gz → 4.1.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.0.0 → blitz_api_py-4.1.0}/CHANGELOG.md +7 -0
  2. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/PKG-INFO +50 -1
  3. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/README.md +49 -0
  4. blitz_api_py-4.1.0/src/blitz_api/_version.py +1 -0
  5. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/company.py +4 -0
  6. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/enrichment.py +21 -4
  7. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/search.py +19 -1
  8. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/company.py +4 -0
  9. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/enrichment.py +21 -4
  10. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/search.py +19 -1
  11. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/__init__.py +12 -0
  12. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/_models.py +7 -0
  13. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/enrichment.py +16 -1
  14. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/enums.py +70 -0
  15. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/filters.py +111 -4
  16. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/shared.py +39 -14
  17. blitz_api_py-4.0.0/src/blitz_api/_version.py +0 -1
  18. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/.gitignore +0 -0
  19. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/LICENSE +0 -0
  20. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/pyproject.toml +0 -0
  21. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/__init__.py +0 -0
  22. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_base_client.py +0 -0
  23. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_client.py +0 -0
  24. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_client_async.py +0 -0
  25. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_client_sync.py +0 -0
  26. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_compat.py +0 -0
  27. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_constants.py +0 -0
  28. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_exceptions.py +0 -0
  29. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_pagination_async.py +0 -0
  30. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_pagination_base.py +0 -0
  31. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_pagination_sync.py +0 -0
  32. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_rate_limit.py +0 -0
  33. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_rate_limit_async.py +0 -0
  34. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_rate_limit_sync.py +0 -0
  35. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/py.typed +0 -0
  36. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/__init__.py +0 -0
  37. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/__init__.py +0 -0
  38. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/account.py +0 -0
  39. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/changelog.py +0 -0
  40. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/jobs.py +0 -0
  41. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/utils.py +0 -0
  42. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
  43. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/account.py +0 -0
  44. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/changelog.py +0 -0
  45. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/jobs.py +0 -0
  46. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/utils.py +0 -0
  47. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/account.py +0 -0
  48. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/changelog.py +0 -0
  49. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/company.py +0 -0
  50. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/jobs.py +0 -0
  51. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/search.py +0 -0
  52. {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/utils.py +0 -0
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## [4.1.0](https://github.com/api-blitz/blitz-api-py/compare/v4.0.0...v4.1.0) (2026-10-15)
4
+
5
+
6
+ ### Features
7
+
8
+ * sync the SDK to the 2026-09-28 → 2026-10-15 API releases ([#33](https://github.com/api-blitz/blitz-api-py/issues/33)) ([260320b](https://github.com/api-blitz/blitz-api-py/commit/260320bdedfeff466702c9d80e24ee21920ef450))
9
+
3
10
  ## [4.0.0](https://github.com/api-blitz/blitz-api-py/compare/v3.0.0...v4.0.0) (2026-09-22)
4
11
 
5
12
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: blitz-api-py
3
- Version: 4.0.0
3
+ Version: 4.1.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
@@ -229,6 +229,55 @@ Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
229
229
  filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
230
230
  member or a raw string.
231
231
 
232
+ ### Hiring signals and mail provider
233
+
234
+ ```python
235
+ from blitz_api import BlitzAPI
236
+ from blitz_api.types import JobLevel, MxProvider
237
+
238
+ client = BlitzAPI()
239
+
240
+ # VPs who started a job in the last 90 days, at companies on Google Workspace, who
241
+ # graduated in 2015 or later. `is_recent_hire` is a key of `people`.
242
+ page = client.search.people(
243
+ company={"mx": {"provider": {"include": [MxProvider.GOOGLE]}}},
244
+ people={
245
+ "job_level": [JobLevel.VP],
246
+ "education": {"end_year": {"min": 2015}},
247
+ "is_recent_hire": True,
248
+ },
249
+ )
250
+
251
+ # Also search jobs a person held before: your job and company filters must hold in the
252
+ # same job, which comes back in `experiences` with `job_is_current` set. Past jobs only:
253
+ client.search.people(people={"include_active_jobs": False, "include_past_jobs": True})
254
+
255
+ # The waterfall takes the same three flags per cascade tier: try recent hires first, then
256
+ # fall back to anyone in the role.
257
+ client.search.waterfall_icp(
258
+ company_linkedin_url="https://www.linkedin.com/company/openai",
259
+ cascade=[
260
+ {"include_title": ["CTO"], "is_recent_hire": True},
261
+ {"include_title": ["CTO"]},
262
+ ],
263
+ )
264
+ ```
265
+
266
+ Where the flags go depends on the route, and the API rejects a flag in the wrong place with a
267
+ `422`:
268
+
269
+ | Route | `is_recent_hire` | `include_active_jobs` / `include_past_jobs` |
270
+ | --- | --- | --- |
271
+ | `search.people` | key of `people` | key of `people` |
272
+ | `company.tam_by_people` | key of `people` | — |
273
+ | `search.waterfall_icp` | key of each `cascade` tier | key of each `cascade` tier |
274
+ | `search.employee_finder` | top-level argument | — |
275
+ | `enrichment.company_distribution_by_country` / `_by_department` | top-level argument | — |
276
+
277
+ Setting both `include_*_jobs` flags to `False` is a `422`. `MxProvider.ANY` stands for
278
+ *every* provider: in `include` it keeps companies with mail data, in `exclude` it keeps
279
+ companies with none.
280
+
232
281
  ## Pagination
233
282
 
234
283
  The search, jobs and TAM methods return an **auto-paginating page**: iterate it and the
@@ -198,6 +198,55 @@ Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
198
198
  filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
199
199
  member or a raw string.
200
200
 
201
+ ### Hiring signals and mail provider
202
+
203
+ ```python
204
+ from blitz_api import BlitzAPI
205
+ from blitz_api.types import JobLevel, MxProvider
206
+
207
+ client = BlitzAPI()
208
+
209
+ # VPs who started a job in the last 90 days, at companies on Google Workspace, who
210
+ # graduated in 2015 or later. `is_recent_hire` is a key of `people`.
211
+ page = client.search.people(
212
+ company={"mx": {"provider": {"include": [MxProvider.GOOGLE]}}},
213
+ people={
214
+ "job_level": [JobLevel.VP],
215
+ "education": {"end_year": {"min": 2015}},
216
+ "is_recent_hire": True,
217
+ },
218
+ )
219
+
220
+ # Also search jobs a person held before: your job and company filters must hold in the
221
+ # same job, which comes back in `experiences` with `job_is_current` set. Past jobs only:
222
+ client.search.people(people={"include_active_jobs": False, "include_past_jobs": True})
223
+
224
+ # The waterfall takes the same three flags per cascade tier: try recent hires first, then
225
+ # fall back to anyone in the role.
226
+ client.search.waterfall_icp(
227
+ company_linkedin_url="https://www.linkedin.com/company/openai",
228
+ cascade=[
229
+ {"include_title": ["CTO"], "is_recent_hire": True},
230
+ {"include_title": ["CTO"]},
231
+ ],
232
+ )
233
+ ```
234
+
235
+ Where the flags go depends on the route, and the API rejects a flag in the wrong place with a
236
+ `422`:
237
+
238
+ | Route | `is_recent_hire` | `include_active_jobs` / `include_past_jobs` |
239
+ | --- | --- | --- |
240
+ | `search.people` | key of `people` | key of `people` |
241
+ | `company.tam_by_people` | key of `people` | — |
242
+ | `search.waterfall_icp` | key of each `cascade` tier | key of each `cascade` tier |
243
+ | `search.employee_finder` | top-level argument | — |
244
+ | `enrichment.company_distribution_by_country` / `_by_department` | top-level argument | — |
245
+
246
+ Setting both `include_*_jobs` flags to `False` is a `422`. `MxProvider.ANY` stands for
247
+ *every* provider: in `include` it keeps companies with mail data, in `exclude` it keeps
248
+ companies with none.
249
+
201
250
  ## Pagination
202
251
 
203
252
  The search, jobs and TAM methods return an **auto-paginating page**: iterate it and the
@@ -0,0 +1 @@
1
+ __version__ = "4.1.0" # x-release-please-version
@@ -72,6 +72,10 @@ class AsyncCompanyResource:
72
72
  ``people["min_per_company"]`` to require a minimum number of matching employees
73
73
  per company.
74
74
 
75
+ Set ``people["is_recent_hire"]`` to count only people with a job that started in the
76
+ last 90 days (the job must also match your other job and company filters; a job
77
+ with no start date never matches).
78
+
75
79
  Cursor-paginated: auto-paginates over every ``{company, matched_people}`` match
76
80
  when the result is iterated; use ``.iter_pages()`` or the ``cursor=`` arg for
77
81
  manual control. When ``min_per_company`` filters heavily a page may come back
@@ -139,32 +139,49 @@ class AsyncEnrichmentResource:
139
139
  )
140
140
 
141
141
  async def company_distribution_by_country(
142
- self, *, company_linkedin_url: str, timeout: TimeoutParam = None
142
+ self,
143
+ *,
144
+ company_linkedin_url: str,
145
+ is_recent_hire: bool | None = None,
146
+ timeout: TimeoutParam = None,
143
147
  ) -> CompanyDistributionByCountryResponse:
144
148
  """Get a company's employee count broken down by country.
145
149
 
150
+ Counts **people**, not jobs: since 2026-10-14 a person with a second job at the
151
+ company is no longer counted twice in ``count`` / ``total_employees``.
152
+
146
153
  Countries are reported as ISO 3166-1 alpha-2 codes (e.g. ``US``, ``GB``);
147
154
  employees whose country can't be determined are bucketed under ``"unknown"``.
155
+
156
+ ``is_recent_hire=True`` counts only people whose current job at the company started
157
+ in the last 90 days (a job with no start date is not counted).
148
158
  """
149
159
  return await self._client._request(
150
160
  "POST",
151
161
  _DISTRIBUTION_BY_COUNTRY,
152
- body={"company_linkedin_url": company_linkedin_url},
162
+ body={"company_linkedin_url": company_linkedin_url, "is_recent_hire": is_recent_hire},
153
163
  cast_to=CompanyDistributionByCountryResponse,
154
164
  timeout=timeout,
155
165
  )
156
166
 
157
167
  async def company_distribution_by_department(
158
- self, *, company_linkedin_url: str, timeout: TimeoutParam = None
168
+ self,
169
+ *,
170
+ company_linkedin_url: str,
171
+ is_recent_hire: bool | None = None,
172
+ timeout: TimeoutParam = None,
159
173
  ) -> CompanyDistributionByDepartmentResponse:
160
174
  """Get a company's employee count broken down by department.
161
175
 
162
176
  Employees with no classified department are counted under ``"Other"``.
177
+
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).
163
180
  """
164
181
  return await self._client._request(
165
182
  "POST",
166
183
  _DISTRIBUTION_BY_DEPARTMENT,
167
- body={"company_linkedin_url": company_linkedin_url},
184
+ body={"company_linkedin_url": company_linkedin_url, "is_recent_hire": is_recent_hire},
168
185
  cast_to=CompanyDistributionByDepartmentResponse,
169
186
  timeout=timeout,
170
187
  )
@@ -15,6 +15,7 @@ from ...types.filters import (
15
15
  PeopleCompanyFilter,
16
16
  PeopleFilter,
17
17
  SalesRegionValue,
18
+ SearchPeopleFilter,
18
19
  )
19
20
  from ...types.search import WaterfallIcpResponse
20
21
  from ...types.shared import Company, Person
@@ -36,13 +37,18 @@ class AsyncSearchResource:
36
37
  self,
37
38
  *,
38
39
  company: PeopleCompanyFilter | None = None,
39
- people: PeopleFilter | None = None,
40
+ people: SearchPeopleFilter | PeopleFilter | None = None,
40
41
  max_results: int | None = None,
41
42
  cursor: str | None = None,
42
43
  timeout: TimeoutParam = None,
43
44
  ) -> AsyncCursorPage[Person]:
44
45
  """Search people across many companies, combining company and persona filters.
45
46
 
47
+ Which of a person's jobs are searched is set in ``people``: ``is_recent_hire``
48
+ (job started in the last 90 days), ``include_active_jobs`` and ``include_past_jobs``
49
+ (see :class:`~blitz_api.types.SearchPeopleFilter`). Your job and company filters must hold
50
+ in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set.
51
+
46
52
  Auto-paginates over every matching person when the result is iterated; use
47
53
  ``.iter_pages()`` or the ``cursor=`` arg for manual control.
48
54
  """
@@ -79,12 +85,17 @@ class AsyncSearchResource:
79
85
  job_level: list[JobLevelValue] | None = None,
80
86
  job_function: list[JobFunctionValue] | None = None,
81
87
  min_connections_count: int | None = None,
88
+ is_recent_hire: bool | None = None,
82
89
  max_results: int | None = None,
83
90
  page: int | None = None,
84
91
  timeout: TimeoutParam = None,
85
92
  ) -> AsyncPageNumberPage[Person]:
86
93
  """Search employees at a single company, with page-based pagination.
87
94
 
95
+ ``is_recent_hire=True`` keeps only people whose **current** job at the company
96
+ started in the last 90 days (that job must also match ``job_level`` and
97
+ ``job_function``; a job with no start date never matches).
98
+
88
99
  Auto-paginates over every matching employee; use ``.iter_pages()`` or ``page=``
89
100
  for manual control.
90
101
  """
@@ -96,6 +107,7 @@ class AsyncSearchResource:
96
107
  "job_level": job_level,
97
108
  "job_function": job_function,
98
109
  "min_connections_count": min_connections_count,
110
+ "is_recent_hire": is_recent_hire,
99
111
  "max_results": max_results,
100
112
  "page": page,
101
113
  }
@@ -120,6 +132,12 @@ class AsyncSearchResource:
120
132
 
121
133
  ``profile_min_connections`` sets the minimum LinkedIn connections for a match
122
134
  (server defaults to ``0`` — i.e. **no** floor — when omitted).
135
+
136
+ Recent-hire and past-job scoping is per tier, set on each :class:`CascadeTier`:
137
+ ``is_recent_hire`` (job started in the last 90 days), ``include_active_jobs`` and
138
+ ``include_past_jobs``. With ``include_past_jobs`` a tier finds people by a job they
139
+ held *before* at the company; the company and that tier's title filters must then hold
140
+ in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set.
123
141
  """
124
142
  body = {
125
143
  "company_linkedin_url": company_linkedin_url,
@@ -74,6 +74,10 @@ class CompanyResource:
74
74
  ``people["min_per_company"]`` to require a minimum number of matching employees
75
75
  per company.
76
76
 
77
+ Set ``people["is_recent_hire"]`` to count only people with a job that started in the
78
+ last 90 days (the job must also match your other job and company filters; a job
79
+ with no start date never matches).
80
+
77
81
  Cursor-paginated: auto-paginates over every ``{company, matched_people}`` match
78
82
  when the result is iterated; use ``.iter_pages()`` or the ``cursor=`` arg for
79
83
  manual control. When ``min_per_company`` filters heavily a page may come back
@@ -141,32 +141,49 @@ class EnrichmentResource:
141
141
  )
142
142
 
143
143
  def company_distribution_by_country(
144
- self, *, company_linkedin_url: str, timeout: TimeoutParam = None
144
+ self,
145
+ *,
146
+ company_linkedin_url: str,
147
+ is_recent_hire: bool | None = None,
148
+ timeout: TimeoutParam = None,
145
149
  ) -> CompanyDistributionByCountryResponse:
146
150
  """Get a company's employee count broken down by country.
147
151
 
152
+ Counts **people**, not jobs: since 2026-10-14 a person with a second job at the
153
+ company is no longer counted twice in ``count`` / ``total_employees``.
154
+
148
155
  Countries are reported as ISO 3166-1 alpha-2 codes (e.g. ``US``, ``GB``);
149
156
  employees whose country can't be determined are bucketed under ``"unknown"``.
157
+
158
+ ``is_recent_hire=True`` counts only people whose current job at the company started
159
+ in the last 90 days (a job with no start date is not counted).
150
160
  """
151
161
  return self._client._request(
152
162
  "POST",
153
163
  _DISTRIBUTION_BY_COUNTRY,
154
- body={"company_linkedin_url": company_linkedin_url},
164
+ body={"company_linkedin_url": company_linkedin_url, "is_recent_hire": is_recent_hire},
155
165
  cast_to=CompanyDistributionByCountryResponse,
156
166
  timeout=timeout,
157
167
  )
158
168
 
159
169
  def company_distribution_by_department(
160
- self, *, company_linkedin_url: str, timeout: TimeoutParam = None
170
+ self,
171
+ *,
172
+ company_linkedin_url: str,
173
+ is_recent_hire: bool | None = None,
174
+ timeout: TimeoutParam = None,
161
175
  ) -> CompanyDistributionByDepartmentResponse:
162
176
  """Get a company's employee count broken down by department.
163
177
 
164
178
  Employees with no classified department are counted under ``"Other"``.
179
+
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).
165
182
  """
166
183
  return self._client._request(
167
184
  "POST",
168
185
  _DISTRIBUTION_BY_DEPARTMENT,
169
- body={"company_linkedin_url": company_linkedin_url},
186
+ body={"company_linkedin_url": company_linkedin_url, "is_recent_hire": is_recent_hire},
170
187
  cast_to=CompanyDistributionByDepartmentResponse,
171
188
  timeout=timeout,
172
189
  )
@@ -17,6 +17,7 @@ from ...types.filters import (
17
17
  PeopleCompanyFilter,
18
18
  PeopleFilter,
19
19
  SalesRegionValue,
20
+ SearchPeopleFilter,
20
21
  )
21
22
  from ...types.search import WaterfallIcpResponse
22
23
  from ...types.shared import Company, Person
@@ -38,13 +39,18 @@ class SearchResource:
38
39
  self,
39
40
  *,
40
41
  company: PeopleCompanyFilter | None = None,
41
- people: PeopleFilter | None = None,
42
+ people: SearchPeopleFilter | PeopleFilter | None = None,
42
43
  max_results: int | None = None,
43
44
  cursor: str | None = None,
44
45
  timeout: TimeoutParam = None,
45
46
  ) -> CursorPage[Person]:
46
47
  """Search people across many companies, combining company and persona filters.
47
48
 
49
+ Which of a person's jobs are searched is set in ``people``: ``is_recent_hire``
50
+ (job started in the last 90 days), ``include_active_jobs`` and ``include_past_jobs``
51
+ (see :class:`~blitz_api.types.SearchPeopleFilter`). Your job and company filters must hold
52
+ in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set.
53
+
48
54
  Auto-paginates over every matching person when the result is iterated; use
49
55
  ``.iter_pages()`` or the ``cursor=`` arg for manual control.
50
56
  """
@@ -81,12 +87,17 @@ class SearchResource:
81
87
  job_level: list[JobLevelValue] | None = None,
82
88
  job_function: list[JobFunctionValue] | None = None,
83
89
  min_connections_count: int | None = None,
90
+ is_recent_hire: bool | None = None,
84
91
  max_results: int | None = None,
85
92
  page: int | None = None,
86
93
  timeout: TimeoutParam = None,
87
94
  ) -> PageNumberPage[Person]:
88
95
  """Search employees at a single company, with page-based pagination.
89
96
 
97
+ ``is_recent_hire=True`` keeps only people whose **current** job at the company
98
+ started in the last 90 days (that job must also match ``job_level`` and
99
+ ``job_function``; a job with no start date never matches).
100
+
90
101
  Auto-paginates over every matching employee; use ``.iter_pages()`` or ``page=``
91
102
  for manual control.
92
103
  """
@@ -98,6 +109,7 @@ class SearchResource:
98
109
  "job_level": job_level,
99
110
  "job_function": job_function,
100
111
  "min_connections_count": min_connections_count,
112
+ "is_recent_hire": is_recent_hire,
101
113
  "max_results": max_results,
102
114
  "page": page,
103
115
  }
@@ -122,6 +134,12 @@ class SearchResource:
122
134
 
123
135
  ``profile_min_connections`` sets the minimum LinkedIn connections for a match
124
136
  (server defaults to ``0`` — i.e. **no** floor — when omitted).
137
+
138
+ Recent-hire and past-job scoping is per tier, set on each :class:`CascadeTier`:
139
+ ``is_recent_hire`` (job started in the last 90 days), ``include_active_jobs`` and
140
+ ``include_past_jobs``. With ``include_past_jobs`` a tier finds people by a job they
141
+ held *before* at the company; the company and that tier's title filters must then hold
142
+ in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set.
125
143
  """
126
144
  body = {
127
145
  "company_linkedin_url": company_linkedin_url,
@@ -36,6 +36,7 @@ from .enums import (
36
36
  JobFunction,
37
37
  JobLevel,
38
38
  LastFundingType,
39
+ MxProvider,
39
40
  SalesRegion,
40
41
  Seniority,
41
42
  WorkArrangement,
@@ -55,11 +56,15 @@ from .filters import (
55
56
  JobLocationFilter,
56
57
  KeywordFilter,
57
58
  LastFundingTypeFilter,
59
+ MxFilter,
60
+ MxProviderFilter,
58
61
  PeopleCompanyFilter,
62
+ PeopleEducationFilter,
59
63
  PeopleFilter,
60
64
  PeopleJobTitleFilter,
61
65
  PeopleLocationFilter,
62
66
  RangeFilter,
67
+ SearchPeopleFilter,
63
68
  SeniorityFilter,
64
69
  TamJobFilter,
65
70
  TamPeopleFilter,
@@ -77,6 +82,7 @@ from .shared import (
77
82
  Education,
78
83
  Experience,
79
84
  Location,
85
+ MxRecord,
80
86
  Person,
81
87
  )
82
88
  from .utils import (
@@ -92,11 +98,13 @@ __all__ = [
92
98
  "Location",
93
99
  "Company",
94
100
  "HQ",
101
+ "MxRecord",
95
102
  # enums
96
103
  "Industry",
97
104
  "CompanyType",
98
105
  "EmployeeRange",
99
106
  "LastFundingType",
107
+ "MxProvider",
100
108
  "Continent",
101
109
  "SalesRegion",
102
110
  "JobFunction",
@@ -109,13 +117,17 @@ __all__ = [
109
117
  "IndustryFilter",
110
118
  "CompanyTypeFilter",
111
119
  "LastFundingTypeFilter",
120
+ "MxProviderFilter",
121
+ "MxFilter",
112
122
  "RangeFilter",
113
123
  "CompanyHQFilter",
114
124
  "CompanyFilter",
115
125
  "PeopleJobTitleFilter",
116
126
  "PeopleLocationFilter",
127
+ "PeopleEducationFilter",
117
128
  "PeopleCompanyFilter",
118
129
  "PeopleFilter",
130
+ "SearchPeopleFilter",
119
131
  "CascadeTier",
120
132
  "SeniorityFilter",
121
133
  "EmploymentTypeFilter",
@@ -95,4 +95,11 @@ def _null_to_empty(value: Any) -> Any:
95
95
  #: a ``None`` guard. The rule is exhaustive as of 2026-09-22: the remaining plain
96
96
  #: ``list[T] = []`` fields (``allowed_apis``, ``active_plans``, ``all_emails``, ``other``,
97
97
  #: both ``distribution``s, the waterfall ``results``) are all non-nullable in the spec.
98
+ #:
99
+ #: **The one exception is ``mx``** (``Company.mx``, ``EmailEnrichmentResponse.mx``,
100
+ #: ``EmailMatch.mx``), added 2026-10-15: the API documents ``null`` ("no MX data yet" /
101
+ #: "not resolved") and ``[]`` ("the domain takes no mail") as *different answers*, so
102
+ #: coercing one into the other would destroy information. Those fields are
103
+ #: ``list[MxRecord] | None``. Before wrapping a new nullable list here, check that ``null``
104
+ #: and ``[]`` are not distinguished by the spec.
98
105
  BlitzList = Annotated[list[_ItemT], BeforeValidator(_null_to_empty)]
@@ -3,7 +3,7 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  from ._models import BlitzModel, BlitzResponse
6
- from .shared import Company, Person
6
+ from .shared import Company, MxRecord, Person
7
7
 
8
8
  __all__ = [
9
9
  "PersonEnrichmentResponse",
@@ -41,6 +41,9 @@ class EmailMatch(BlitzModel):
41
41
  job_order_in_profile: int | None = None
42
42
  company_linkedin_url: str | None = None
43
43
  email_domain: str | None = None
44
+ #: MX records of the email's domain, by priority, at most 10. ``None`` when not resolved
45
+ #: (so, as on :attr:`EmailEnrichmentResponse.mx`, not coerced to ``[]``).
46
+ mx: list[MxRecord] | None = None
44
47
 
45
48
 
46
49
  class EmailEnrichmentResponse(BlitzResponse):
@@ -48,6 +51,10 @@ class EmailEnrichmentResponse(BlitzResponse):
48
51
 
49
52
  found: bool | None = None
50
53
  email: str | None = None
54
+ #: MX records of ``email``'s domain, by priority, at most 10. ``None`` when not resolved
55
+ #: -- left as ``None`` rather than coerced to ``[]``, because for the sibling
56
+ #: :attr:`Company.mx` the two mean different things and the field should read alike.
57
+ mx: list[MxRecord] | None = None
51
58
  all_emails: list[EmailMatch] = []
52
59
 
53
60
 
@@ -121,8 +128,12 @@ class CompanyDistributionByCountryResponse(BlitzResponse):
121
128
  """Result of ``enrichment.company_distribution_by_country``.
122
129
 
123
130
  Served by ``POST /v2/enrichment/company-distribution-by-country``.
131
+
132
+ ``found`` is ``False`` (and the call costs no records) when the company is unknown or
133
+ has no current employees.
124
134
  """
125
135
 
136
+ found: bool | None = None
126
137
  company_linkedin_url: str | None = None
127
138
  total_employees: int | None = None
128
139
  distribution: list[CompanyDistributionByCountryItem] = []
@@ -145,8 +156,12 @@ class CompanyDistributionByDepartmentResponse(BlitzResponse):
145
156
  """Result of ``enrichment.company_distribution_by_department``.
146
157
 
147
158
  Served by ``POST /v2/enrichment/company-distribution-by-department``.
159
+
160
+ ``found`` is ``False`` (and the call costs no records) when the company is unknown or
161
+ has no current employees.
148
162
  """
149
163
 
164
+ found: bool | None = None
150
165
  company_linkedin_url: str | None = None
151
166
  total_employees: int | None = None
152
167
  distribution: list[CompanyDistributionByDepartmentItem] = []
@@ -22,6 +22,7 @@ __all__ = [
22
22
  "Seniority",
23
23
  "EmploymentType",
24
24
  "WorkArrangement",
25
+ "MxProvider",
25
26
  ]
26
27
 
27
28
 
@@ -687,3 +688,72 @@ class WorkArrangement(str, Enum):
687
688
  HYBRID = 'Hybrid'
688
689
  REMOTE_OK = 'Remote OK'
689
690
  REMOTE_SOLELY = 'Remote Solely'
691
+
692
+
693
+ class MxProvider(str, Enum):
694
+ ANY = 'any'
695
+ GOOGLE = 'google'
696
+ MICROSOFT = 'microsoft'
697
+ ZOHO = 'zoho'
698
+ GODADDY = 'godaddy'
699
+ PROOFPOINT = 'proofpoint'
700
+ MIMECAST = 'mimecast'
701
+ BARRACUDA = 'barracuda'
702
+ CLOUDFLARE = 'cloudflare'
703
+ IONOS = 'ionos'
704
+ HOSTINGER = 'hostinger'
705
+ NAMECHEAP = 'namecheap'
706
+ FASTMAIL = 'fastmail'
707
+ PROTON = 'proton'
708
+ STRATO = 'strato'
709
+ OVH = 'ovh'
710
+ SITEGROUND = 'siteground'
711
+ OPENSRS = 'opensrs'
712
+ ONE_COM = 'one_com'
713
+ TENCENT = 'tencent'
714
+ TITAN = 'titan'
715
+ _20I = '20i'
716
+ RACKSPACE = 'rackspace'
717
+ ALIBABA = 'alibaba'
718
+ OPEN_XCHANGE = 'open_xchange'
719
+ INFOMANIAK = 'infomaniak'
720
+ JIMDO = 'jimdo'
721
+ NETEASE = 'netease'
722
+ GANDI = 'gandi'
723
+ REGISTER_IT = 'register_it'
724
+ HETZNER = 'hetzner'
725
+ YAHOO = 'yahoo'
726
+ AMAZON = 'amazon'
727
+ YANDEX = 'yandex'
728
+ LOCAWEB = 'locaweb'
729
+ UOL_HOST = 'uol_host'
730
+ FASTHOSTS = 'fasthosts'
731
+ KINGHOST = 'kinghost'
732
+ T_ONLINE = 't_online'
733
+ HOSTOPIA = 'hostopia'
734
+ UNITED_DOMAINS = 'united_domains'
735
+ HOSTPOINT = 'hostpoint'
736
+ MIJNDOMEIN = 'mijndomein'
737
+ ICLOUD = 'icloud'
738
+ REG123 = 'reg123'
739
+ MAILHOSTBOX = 'mailhostbox'
740
+ TRANSIP = 'transip'
741
+ NATRO = 'natro'
742
+ NAMES_CO_UK = 'names_co_uk'
743
+ INTERMEDIA = 'intermedia'
744
+ HOSTNET = 'hostnet'
745
+ ARUBA = 'aruba'
746
+ LOOPIA = 'loopia'
747
+ NETCUP = 'netcup'
748
+ LOLIPOP = 'lolipop'
749
+ SIMPLY = 'simply'
750
+ DOMENESHOP = 'domeneshop'
751
+ HORNETSECURITY = 'hornetsecurity'
752
+ MAILCHANNELS = 'mailchannels'
753
+ APPRIVER = 'appriver'
754
+ TRENDMICRO = 'trendmicro'
755
+ SPAMEXPERTS = 'spamexperts'
756
+ CISCO = 'cisco'
757
+ SOPHOS = 'sophos'
758
+ MESH = 'mesh'
759
+ MAILINBLACK = 'mailinblack'
@@ -23,6 +23,7 @@ from .enums import (
23
23
  JobFunction,
24
24
  JobLevel,
25
25
  LastFundingType,
26
+ MxProvider,
26
27
  SalesRegion,
27
28
  Seniority,
28
29
  WorkArrangement,
@@ -37,6 +38,7 @@ IndustryValue = Industry | str
37
38
  CompanyTypeValue = CompanyType | str
38
39
  EmployeeRangeValue = EmployeeRange | str
39
40
  LastFundingTypeValue = LastFundingType | str
41
+ MxProviderValue = MxProvider | str
40
42
  ContinentValue = Continent | str
41
43
  SalesRegionValue = SalesRegion | str
42
44
  JobFunctionValue = JobFunction | str
@@ -89,6 +91,30 @@ class LastFundingTypeFilter(TypedDict, total=False):
89
91
  exclude: list[LastFundingTypeValue]
90
92
 
91
93
 
94
+ class MxProviderFilter(TypedDict, total=False):
95
+ """Include/exclude filter over the mail provider behind a company's domains.
96
+
97
+ :attr:`~blitz_api.types.MxProvider.ANY` (``"any"``) stands for *every* provider. In
98
+ ``include`` it keeps companies that have MX data at all; in ``exclude`` it keeps
99
+ companies that have **none**. So ``{"include": ["any"], "exclude": ["google"]}`` means
100
+ "has MX data, but not on Google".
101
+ """
102
+
103
+ include: list[MxProviderValue]
104
+ exclude: list[MxProviderValue]
105
+
106
+
107
+ class MxFilter(TypedDict, total=False):
108
+ """Mail-provider criteria, read from the MX records of a company's domains.
109
+
110
+ A company matches when **any** of its domains uses the provider. A company with no MX
111
+ data is never matched by ``include`` and never dropped by ``exclude`` — unless you use
112
+ :attr:`~blitz_api.types.MxProvider.ANY`.
113
+ """
114
+
115
+ provider: MxProviderFilter
116
+
117
+
92
118
  class RangeFilter(TypedDict, total=False):
93
119
  """Numeric range filter. ``0`` means unset for most fields.
94
120
 
@@ -139,6 +165,7 @@ class CompanyFilter(TypedDict, total=False):
139
165
  keywords: KeywordFilter
140
166
  founded_year: RangeFilter
141
167
  hq: CompanyHQFilter
168
+ mx: MxFilter
142
169
 
143
170
 
144
171
  class PeopleCompanyFilter(CompanyFilter, total=False):
@@ -183,6 +210,19 @@ class PeopleLocationFilter(TypedDict, total=False):
183
210
  sales_region: list[SalesRegionValue]
184
211
 
185
212
 
213
+ class PeopleEducationFilter(KeywordFilter, total=False):
214
+ """Education filter for the person: phrase include/exclude plus start/end year ranges.
215
+
216
+ ``start_year`` and ``end_year`` (graduation year) are :class:`RangeFilter` bounds with
217
+ ``0`` meaning unset. They apply to the **same education entry** that ``include`` matches,
218
+ so the school and the year are correlated rather than matched independently. An entry
219
+ with no such year never matches a bound.
220
+ """
221
+
222
+ start_year: RangeFilter
223
+ end_year: RangeFilter
224
+
225
+
186
226
  class PeopleFilter(TypedDict, total=False):
187
227
  """People search criteria for ``search.people``.
188
228
 
@@ -191,6 +231,16 @@ class PeopleFilter(TypedDict, total=False):
191
231
  results for your other criteria instead of the people you asked for). Match specific
192
232
  people by LinkedIn URL with ``company.tam_by_people`` (:class:`TamPeopleFilter`),
193
233
  which still accepts it.
234
+
235
+ This is the persona criteria ``search.people`` and ``company.tam_by_people`` share;
236
+ :class:`SearchPeopleFilter` adds the past-job flags only ``search.people`` takes, and
237
+ :class:`TamPeopleFilter` adds the keys only ``company.tam_by_people`` takes.
238
+
239
+ ``is_recent_hire`` is a key of *this* object, not a top-level argument of either method.
240
+ (Not every route is the same: ``search.employee_finder`` and the two
241
+ ``enrichment.company_distribution_by_*`` methods take it as a top-level argument.) The
242
+ API rejects unknown fields at any depth with a ``422``, so a flag in the wrong place
243
+ fails the call.
194
244
  """
195
245
 
196
246
  job_title: PeopleJobTitleFilter
@@ -198,7 +248,39 @@ class PeopleFilter(TypedDict, total=False):
198
248
  job_level: list[JobLevelValue]
199
249
  min_connections: int
200
250
  location: PeopleLocationFilter
201
- education: KeywordFilter
251
+ # ``| KeywordFilter`` is deliberate: this field was a ``KeywordFilter`` before it gained
252
+ # year ranges, and a ``KeywordFilter`` *variable* is not assignable to the wider
253
+ # ``PeopleEducationFilter`` alone (its extra optional keys could hold any type). The union
254
+ # keeps that existing usage compiling; dict literals and ``PeopleEducationFilter`` variables
255
+ # are unaffected.
256
+ education: PeopleEducationFilter | KeywordFilter
257
+ # Only people with a job that started in the last 90 days. The job must also match the
258
+ # other job and company filters; a job with no start date never matches. On
259
+ # ``search.people`` it covers the jobs ``include_active_jobs`` / ``include_past_jobs``
260
+ # select (current jobs by default); on ``company.tam_by_people``, current jobs.
261
+ is_recent_hire: bool
262
+
263
+
264
+ class SearchPeopleFilter(PeopleFilter, total=False):
265
+ """People criteria for ``search.people`` — every :class:`PeopleFilter` field plus the
266
+ flags that choose which of a person's jobs are searched.
267
+
268
+ ``company.tam_by_people`` does **not** take these two (its ``people`` object has only
269
+ ``is_recent_hire`` of the job-scope flags), which is why they are not on
270
+ :class:`PeopleFilter`. ``search.people`` accepts ``SearchPeopleFilter | PeopleFilter`` so
271
+ an existing ``PeopleFilter`` variable keeps type-checking: a ``PeopleFilter`` variable is
272
+ not assignable to this wider type alone (``TypedDict`` assignability is structural, and
273
+ the extra optional keys could hold anything).
274
+ """
275
+
276
+ # Search the current jobs of each person (server default ``True``). Your job and company
277
+ # filters must hold in the *same* job; that job is returned in ``experiences`` with
278
+ # ``job_is_current`` set.
279
+ include_active_jobs: bool
280
+ # Also search the past jobs of each person (server default ``False``). A person is returned
281
+ # once, with the matched job; a current job is preferred to a past one. Setting both
282
+ # ``include_*_jobs`` flags to ``False`` is a ``422``.
283
+ include_past_jobs: bool
202
284
 
203
285
 
204
286
  class CascadeTier(TypedDict):
@@ -207,12 +289,28 @@ class CascadeTier(TypedDict):
207
289
  Only ``include_title`` is required; the server defaults ``location`` to worldwide
208
290
  and ``include_headline_search`` to ``False`` when omitted. The ``cascade`` list is
209
291
  capped at **10 tiers**, and each tier at 50 title phrases.
292
+
293
+ ``is_recent_hire``, ``include_active_jobs`` and ``include_past_jobs`` are per-tier keys,
294
+ not arguments of ``search.waterfall_icp``: each tier can scope its own search, so a
295
+ cascade can try recent hires first and fall back to everyone.
210
296
  """
211
297
 
212
298
  include_title: list[str]
213
299
  location: NotRequired[list[str]]
214
300
  include_headline_search: NotRequired[bool]
215
301
  exclude_title: NotRequired[list[str]]
302
+ # Only people whose job at the company started in the last 90 days. It covers the jobs
303
+ # this tier's ``include_active_jobs`` / ``include_past_jobs`` select (current jobs by
304
+ # default), and that job must also match the tier's title filters; a job with no start
305
+ # date never matches.
306
+ is_recent_hire: NotRequired[bool]
307
+ # Search the current jobs of each person (server default ``True``). The company and the
308
+ # tier's title filters must hold in the same job; it is returned in ``experiences`` with
309
+ # ``job_is_current`` set.
310
+ include_active_jobs: NotRequired[bool]
311
+ # Also search the jobs a person held *before* at the company (server default ``False``).
312
+ # A person is returned once. Both ``include_*_jobs`` flags ``False`` is a ``422``.
313
+ include_past_jobs: NotRequired[bool]
216
314
 
217
315
 
218
316
  class SeniorityFilter(TypedDict, total=False):
@@ -256,6 +354,8 @@ class DatePostedFilter(TypedDict):
256
354
  class JobFilter(TypedDict, total=False):
257
355
  """Job-level search criteria, shared by ``jobs.search`` and ``jobs.company``."""
258
356
 
357
+ # Wrap a phrase in ``[brackets]`` (e.g. ``"[Head of Sales]"``) to match the whole title
358
+ # exactly, ignoring case and accents; an unbracketed phrase is a tokenized full-text match.
259
359
  title: KeywordFilter
260
360
  description: KeywordFilter
261
361
  ai_keywords: KeywordFilter # Broad theme search across title, description, taxonomies.
@@ -289,8 +389,10 @@ class TamPeopleFilter(PeopleFilter, total=False):
289
389
  plus ``linkedin_url`` and a per-company floor.
290
390
 
291
391
  Extends ``PeopleFilter`` for the same reason as :class:`TamJobFilter`, and because
292
- the API documents this endpoint as taking *the same input as Find People*: sharing
293
- the base is what keeps that true as the persona filters evolve.
392
+ the API documents this endpoint as taking the same persona input as Find People: sharing
393
+ the base is what keeps that true as the persona filters evolve. The one deliberate gap is
394
+ :class:`SearchPeopleFilter`'s ``include_active_jobs`` / ``include_past_jobs``, which only
395
+ ``search.people`` takes.
294
396
  """
295
397
 
296
398
  # Match specific people by LinkedIn URL. Still honoured here (unlike on
@@ -309,7 +411,12 @@ class CompanySizeFilter(TypedDict, total=False):
309
411
 
310
412
 
311
413
  class JobCompanyHQFilter(TypedDict, total=False):
312
- """Headquarters-location filter for the company side of a job search."""
414
+ """Headquarters-location filter for the company side of a job search.
415
+
416
+ ``city`` and ``state`` take the same ``[brackets]`` exact-match syntax as
417
+ :attr:`JobFilter.title`: ``"[San Francisco]"`` matches the whole value exactly (ignoring
418
+ case and accents), while an unbracketed phrase is a tokenized full-text match.
419
+ """
313
420
 
314
421
  city: KeywordFilter
315
422
  state: KeywordFilter
@@ -5,8 +5,9 @@ endpoints — e.g. ``Location`` carries ``continent``/``postal_code``/``street_a
5
5
  on a person but not on an ``Experience.job_location`` — so divergent fields are modeled
6
6
  as ``Optional`` on a single superset type rather than duplicated.
7
7
 
8
- Audited field-by-field against the live spec on 2026-09-22; every field here is one the
9
- spec returns, except the two flagged on :class:`HQ`.
8
+ Audited field-by-field against the live spec on 2026-10-15. Every field here is one the
9
+ spec returns at some site, except the deliberate extras recorded in ``docs/CONTEXT.md`` §7
10
+ (``HQ.postcode`` / ``HQ.street``).
10
11
  """
11
12
 
12
13
  from __future__ import annotations
@@ -20,18 +21,25 @@ __all__ = [
20
21
  "Certification",
21
22
  "Person",
22
23
  "HQ",
24
+ "MxRecord",
23
25
  "Company",
24
26
  ]
25
27
 
26
28
 
27
29
  class Location(BlitzModel):
28
- """A geographic location attached to a person or a job."""
30
+ """A geographic location attached to a person or a job.
31
+
32
+ One superset model over three differently-sized spec sites: a person's ``location``
33
+ carries every field; ``Experience.job_location`` has only ``city`` / ``state_code`` /
34
+ ``country_code``; a job's ``location`` (``jobs.*``) has only ``city`` / ``country_code``.
35
+ A field the site doesn't list reads ``None``. That is deliberate — see
36
+ ``docs/CONTEXT.md`` §7.
37
+ """
29
38
 
30
39
  city: str | None = None
31
40
  state_code: str | None = None
32
41
  country_code: str | None = None
33
42
  continent: str | None = None
34
- # Populated on a person's ``location``; absent from ``Experience.job_location``.
35
43
  postal_code: str | None = None
36
44
  street_address: str | None = None
37
45
 
@@ -111,14 +119,14 @@ class Person(BlitzModel):
111
119
  class HQ(BlitzModel):
112
120
  """A company's headquarters location.
113
121
 
114
- .. warning::
115
- ``postcode`` and ``street`` are **unverified**. They predate the spec publishing
116
- real response properties, and the live spec now types every ``hq`` object — on
117
- ``search.companies``, ``enrichment.company`` and both TAM builders alike — with
118
- exactly the six other fields, ``additionalProperties: false`` and all six
119
- ``required``. A closed schema cannot carry them, so they read ``None`` on every
120
- response. Kept pending confirmation from the API owner; see ``docs/CONTEXT.md``
121
- §7. Do not add fields here without checking the live spec first.
122
+ .. note::
123
+ ``postcode`` and ``street`` are deliberate extras. The live spec types every ``hq``
124
+ object — on ``search.companies``, ``enrichment.company`` and both TAM builders alike —
125
+ with exactly the six other fields, ``additionalProperties: false`` and all six
126
+ ``required``, so these two read ``None`` on every response. They are kept on purpose:
127
+ they shipped in a released version, and a ``None`` is harmless where an
128
+ ``AttributeError`` would not be. See ``docs/CONTEXT.md`` §7. Do not add *other* fields
129
+ here without checking the live spec first.
122
130
  """
123
131
 
124
132
  city: str | None = None
@@ -127,12 +135,23 @@ class HQ(BlitzModel):
127
135
  country_name: str | None = None
128
136
  region: str | None = None
129
137
  continent: str | None = None
130
- #: Unverified — see the class warning.
138
+ #: Not in the live spec — a deliberate extra, see the class note.
131
139
  postcode: str | None = None
132
- #: Unverified — see the class warning.
140
+ #: Not in the live spec — a deliberate extra, see the class note.
133
141
  street: str | None = None
134
142
 
135
143
 
144
+ class MxRecord(BlitzModel):
145
+ """One MX record of a domain: a mail host and its priority.
146
+
147
+ A lower ``priority`` is tried first. Returned in :attr:`Company.mx` and in the ``mx`` of
148
+ ``enrichment.email``.
149
+ """
150
+
151
+ priority: int | None = None
152
+ host: str | None = None
153
+
154
+
136
155
  class Company(BlitzModel):
137
156
  """A company profile returned by company search and company enrichment."""
138
157
 
@@ -150,3 +169,9 @@ class Company(BlitzModel):
150
169
  hq: HQ | None = None
151
170
  domain: str | None = None
152
171
  website: str | None = None
172
+ #: MX records of ``domain``, lowest priority first, at most 10. **``None`` and ``[]`` mean
173
+ #: different things:** ``None`` is "no MX data for the domain yet", ``[]`` is "the domain
174
+ #: takes no mail". That is why this is not a ``BlitzList``, which would coerce ``None`` to
175
+ #: ``[]`` and erase the difference (``docs/CONTEXT.md`` §5). Returned by
176
+ #: ``enrichment.company`` only, so it is ``None`` on every other endpoint's companies.
177
+ mx: list[MxRecord] | None = None
@@ -1 +0,0 @@
1
- __version__ = "4.0.0" # x-release-please-version
File without changes
File without changes