feat(api): Add Findall Candidates

client.beta.findall.candidates

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 23
+configured_endpoints: 24
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/parallel-web%2Fparallel-sdk-c4cc922783460c6e65811d13c9abe35807a551c77c126d452806f93caaaf48fb.yml
 openapi_spec_hash: 99c9e48d4dafaca71f058107008d174b
-config_hash: fe820a5a10ee48e143c9e49a153b23b4
+config_hash: 80e7ee7ad8e3424616aca7189ffd5ae7

src/parallel/resources/beta/api.md

@@ -73,6 +73,8 @@ Types:
 ```python
 from parallel.types.beta import (
     FindAllCandidateMatchStatusEvent,
+    FindAllCandidatesRequest,
+    FindAllCandidatesResponse,
     FindAllEnrichInput,
     FindAllExtendInput,
     FindAllRun,
@@ -91,6 +93,7 @@ Methods:
 - <code title="post /v1beta/findall/runs">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">create</a>(\*\*<a href="src/parallel/types/beta/findall_create_params.py">params</a>) -> <a href="./src/parallel/types/beta/findall_run.py">FindAllRun</a></code>
 - <code title="get /v1beta/findall/runs/{findall_id}">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">retrieve</a>(findall_id) -> <a href="./src/parallel/types/beta/findall_run.py">FindAllRun</a></code>
 - <code title="post /v1beta/findall/runs/{findall_id}/cancel">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">cancel</a>(findall_id) -> object</code>
+- <code title="post /v1beta/findall/candidates">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">candidates</a>(\*\*<a href="src/parallel/types/beta/findall_candidates_params.py">params</a>) -> <a href="./src/parallel/types/beta/findall_candidates_response.py">FindAllCandidatesResponse</a></code>
 - <code title="post /v1beta/findall/runs/{findall_id}/enrich">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">enrich</a>(findall_id, \*\*<a href="src/parallel/types/beta/findall_enrich_params.py">params</a>) -> <a href="./src/parallel/types/beta/findall_schema.py">FindAllSchema</a></code>
 - <code title="get /v1beta/findall/runs/{findall_id}/events">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">events</a>(findall_id, \*\*<a href="src/parallel/types/beta/findall_events_params.py">params</a>) -> <a href="./src/parallel/types/beta/findall_events_response.py">FindAllEventsResponse</a></code>
 - <code title="post /v1beta/findall/runs/{findall_id}/extend">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">extend</a>(findall_id, \*\*<a href="src/parallel/types/beta/findall_extend_params.py">params</a>) -> <a href="./src/parallel/types/beta/findall_schema.py">FindAllSchema</a></code>

src/parallel/resources/beta/findall.py

@@ -25,6 +25,7 @@
     findall_events_params,
     findall_extend_params,
     findall_ingest_params,
+    findall_candidates_params,
 )
 from ..._base_client import make_request_options
 from ...types.beta.findall_run import FindAllRun
@@ -35,6 +36,7 @@
 from ...types.beta.findall_run_result import FindAllRunResult
 from ...types.beta.parallel_beta_param import ParallelBetaParam
 from ...types.beta.findall_events_response import FindAllEventsResponse
+from ...types.beta.findall_candidates_response import FindAllCandidatesResponse
 
 __all__ = [
     "FindAllResource",
@@ -263,6 +265,59 @@ def cancel(
             cast_to=object,
         )
 
+    def candidates(
+        self,
+        *,
+        entity_type: Literal["company", "people"],
+        objective: str,
+        match_limit: int | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> FindAllCandidatesResponse:
+        """
+        Return ranked entity candidates matching a natural language objective.
+
+        This endpoint performs a best-effort search optimised for low latency. For
+        comprehensive match evaluation and enrichment, use the
+        [FindAll API](https://docs.parallel.ai/findall-api/findall-quickstart).
+
+        Args:
+          entity_type: Type of entity to search for.
+
+          objective: Natural language description of target entities.
+
+          match_limit: Maximum number of candidates to return. Must be between 5 and 1000 (inclusive).
+              May return fewer results. Defaults to 100.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        extra_headers = {"parallel-beta": "findall-2025-09-15", **(extra_headers or {})}
+        return self._post(
+            "/v1beta/findall/candidates",
+            body=maybe_transform(
+                {
+                    "entity_type": entity_type,
+                    "objective": objective,
+                    "match_limit": match_limit,
+                },
+                findall_candidates_params.FindAllCandidatesParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=FindAllCandidatesResponse,
+        )
+
     def enrich(
         self,
         findall_id: str,
@@ -808,6 +863,59 @@ async def cancel(
             cast_to=object,
         )
 
+    async def candidates(
+        self,
+        *,
+        entity_type: Literal["company", "people"],
+        objective: str,
+        match_limit: int | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> FindAllCandidatesResponse:
+        """
+        Return ranked entity candidates matching a natural language objective.
+
+        This endpoint performs a best-effort search optimised for low latency. For
+        comprehensive match evaluation and enrichment, use the
+        [FindAll API](https://docs.parallel.ai/findall-api/findall-quickstart).
+
+        Args:
+          entity_type: Type of entity to search for.
+
+          objective: Natural language description of target entities.
+
+          match_limit: Maximum number of candidates to return. Must be between 5 and 1000 (inclusive).
+              May return fewer results. Defaults to 100.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        extra_headers = {"parallel-beta": "findall-2025-09-15", **(extra_headers or {})}
+        return await self._post(
+            "/v1beta/findall/candidates",
+            body=await async_maybe_transform(
+                {
+                    "entity_type": entity_type,
+                    "objective": objective,
+                    "match_limit": match_limit,
+                },
+                findall_candidates_params.FindAllCandidatesParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=FindAllCandidatesResponse,
+        )
+
     async def enrich(
         self,
         findall_id: str,
@@ -1155,6 +1263,9 @@ def __init__(self, findall: FindAllResource) -> None:
         self.cancel = to_raw_response_wrapper(
             findall.cancel,
         )
+        self.candidates = to_raw_response_wrapper(
+            findall.candidates,
+        )
         self.enrich = to_raw_response_wrapper(
             findall.enrich,
         )
@@ -1188,6 +1299,9 @@ def __init__(self, findall: AsyncFindAllResource) -> None:
         self.cancel = async_to_raw_response_wrapper(
             findall.cancel,
         )
+        self.candidates = async_to_raw_response_wrapper(
+            findall.candidates,
+        )
         self.enrich = async_to_raw_response_wrapper(
             findall.enrich,
         )
@@ -1221,6 +1335,9 @@ def __init__(self, findall: FindAllResource) -> None:
         self.cancel = to_streamed_response_wrapper(
             findall.cancel,
         )
+        self.candidates = to_streamed_response_wrapper(
+            findall.candidates,
+        )
         self.enrich = to_streamed_response_wrapper(
             findall.enrich,
         )
@@ -1254,6 +1371,9 @@ def __init__(self, findall: AsyncFindAllResource) -> None:
         self.cancel = async_to_streamed_response_wrapper(
             findall.cancel,
         )
+        self.candidates = async_to_streamed_response_wrapper(
+            findall.candidates,
+        )
         self.enrich = async_to_streamed_response_wrapper(
             findall.enrich,
         )

src/parallel/types/beta/__init__.py

@@ -63,9 +63,11 @@
 from .task_group_create_params import TaskGroupCreateParams as TaskGroupCreateParams
 from .task_group_events_params import TaskGroupEventsParams as TaskGroupEventsParams
 from .task_run_events_response import TaskRunEventsResponse as TaskRunEventsResponse
+from .findall_candidates_params import FindAllCandidatesParams as FindAllCandidatesParams
 from .task_group_add_runs_params import TaskGroupAddRunsParams as TaskGroupAddRunsParams
 from .task_group_events_response import TaskGroupEventsResponse as TaskGroupEventsResponse
 from .task_group_get_runs_params import TaskGroupGetRunsParams as TaskGroupGetRunsParams
+from .findall_candidates_response import FindAllCandidatesResponse as FindAllCandidatesResponse
 from .findall_schema_updated_event import (
     FindAllSchemaUpdatedEvent as FindAllSchemaUpdatedEvent,
     FindallSchemaUpdatedEvent as FindallSchemaUpdatedEvent,

src/parallel/types/beta/findall_candidates_params.py

@@ -0,0 +1,22 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, Required, TypedDict
+
+__all__ = ["FindAllCandidatesParams"]
+
+
+class FindAllCandidatesParams(TypedDict, total=False):
+    entity_type: Required[Literal["company", "people"]]
+    """Type of entity to search for."""
+
+    objective: Required[str]
+    """Natural language description of target entities."""
+
+    match_limit: int
+    """Maximum number of candidates to return.
+
+    Must be between 5 and 1000 (inclusive). May return fewer results. Defaults
+    to 100.
+    """

src/parallel/types/beta/findall_candidates_response.py

@@ -0,0 +1,29 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List
+
+from ..._models import BaseModel
+
+__all__ = ["FindAllCandidatesResponse", "Candidate"]
+
+
+class Candidate(BaseModel):
+    description: str
+    """Descriptive text about the entity."""
+
+    name: str
+    """Entity name."""
+
+    url: str
+    """Canonical URL for the entity."""
+
+
+class FindAllCandidatesResponse(BaseModel):
+    candidate_set_id: str
+    """Candidate set request ID.
+
+    Example: `candidate_set_cad0a6d2dec046bd95ae900527d880e7`
+    """
+
+    candidates: List[Candidate]
+    """Ranked list of entity candidates."""

tests/api_resources/beta/test_findall.py

@@ -13,6 +13,7 @@
     FindAllRun,
     FindAllSchema,
     FindAllRunResult,
+    FindAllCandidatesResponse,
 )
 
 base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
@@ -199,6 +200,49 @@ def test_path_params_cancel(self, client: Parallel) -> None:
                 findall_id="",
             )
 
+    @parametrize
+    def test_method_candidates(self, client: Parallel) -> None:
+        findall = client.beta.findall.candidates(
+            entity_type="company",
+            objective="objective",
+        )
+        assert_matches_type(FindAllCandidatesResponse, findall, path=["response"])
+
+    @parametrize
+    def test_method_candidates_with_all_params(self, client: Parallel) -> None:
+        findall = client.beta.findall.candidates(
+            entity_type="company",
+            objective="objective",
+            match_limit=5,
+        )
+        assert_matches_type(FindAllCandidatesResponse, findall, path=["response"])
+
+    @parametrize
+    def test_raw_response_candidates(self, client: Parallel) -> None:
+        response = client.beta.findall.with_raw_response.candidates(
+            entity_type="company",
+            objective="objective",
+        )
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        findall = response.parse()
+        assert_matches_type(FindAllCandidatesResponse, findall, path=["response"])
+
+    @parametrize
+    def test_streaming_response_candidates(self, client: Parallel) -> None:
+        with client.beta.findall.with_streaming_response.candidates(
+            entity_type="company",
+            objective="objective",
+        ) as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            findall = response.parse()
+            assert_matches_type(FindAllCandidatesResponse, findall, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
     @parametrize
     def test_method_enrich(self, client: Parallel) -> None:
         findall = client.beta.findall.enrich(
@@ -709,6 +753,49 @@ async def test_path_params_cancel(self, async_client: AsyncParallel) -> None:
                 findall_id="",
             )
 
+    @parametrize
+    async def test_method_candidates(self, async_client: AsyncParallel) -> None:
+        findall = await async_client.beta.findall.candidates(
+            entity_type="company",
+            objective="objective",
+        )
+        assert_matches_type(FindAllCandidatesResponse, findall, path=["response"])
+
+    @parametrize
+    async def test_method_candidates_with_all_params(self, async_client: AsyncParallel) -> None:
+        findall = await async_client.beta.findall.candidates(
+            entity_type="company",
+            objective="objective",
+            match_limit=5,
+        )
+        assert_matches_type(FindAllCandidatesResponse, findall, path=["response"])
+
+    @parametrize
+    async def test_raw_response_candidates(self, async_client: AsyncParallel) -> None:
+        response = await async_client.beta.findall.with_raw_response.candidates(
+            entity_type="company",
+            objective="objective",
+        )
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        findall = await response.parse()
+        assert_matches_type(FindAllCandidatesResponse, findall, path=["response"])
+
+    @parametrize
+    async def test_streaming_response_candidates(self, async_client: AsyncParallel) -> None:
+        async with async_client.beta.findall.with_streaming_response.candidates(
+            entity_type="company",
+            objective="objective",
+        ) as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            findall = await response.parse()
+            assert_matches_type(FindAllCandidatesResponse, findall, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
     @parametrize
     async def test_method_enrich(self, async_client: AsyncParallel) -> None:
         findall = await async_client.beta.findall.enrich(