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.
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/CHANGELOG.md +7 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/PKG-INFO +50 -1
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/README.md +49 -0
- blitz_api_py-4.1.0/src/blitz_api/_version.py +1 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/company.py +4 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/enrichment.py +21 -4
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/search.py +19 -1
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/company.py +4 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/enrichment.py +21 -4
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/search.py +19 -1
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/__init__.py +12 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/_models.py +7 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/enrichment.py +16 -1
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/enums.py +70 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/filters.py +111 -4
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/shared.py +39 -14
- blitz_api_py-4.0.0/src/blitz_api/_version.py +0 -1
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/.gitignore +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/LICENSE +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/pyproject.toml +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/__init__.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_base_client.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_client.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_client_async.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_client_sync.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_compat.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_constants.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_exceptions.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_pagination_async.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_pagination_base.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_pagination_sync.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_rate_limit.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_rate_limit_async.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_rate_limit_sync.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/py.typed +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/__init__.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/__init__.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/account.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/changelog.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/jobs.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/utils.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/account.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/changelog.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/jobs.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/utils.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/account.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/changelog.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/company.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/jobs.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/search.py +0 -0
- {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.
|
|
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,
|
|
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,
|
|
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,
|
|
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,
|
|
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
|
-
|
|
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
|
|
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-
|
|
9
|
-
spec returns, except the
|
|
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
|
-
..
|
|
115
|
-
``postcode`` and ``street`` are
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
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
|
-
#:
|
|
138
|
+
#: Not in the live spec — a deliberate extra, see the class note.
|
|
131
139
|
postcode: str | None = None
|
|
132
|
-
#:
|
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|