release: 2.2.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.1.0"
+  ".": "2.2.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 48
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch/finch-3cd1346947fabfca2aa9c6f821170c8d945a82667fb20a15644d5c77f8e98c10.yml
-openapi_spec_hash: 642e04e90d37c0e4875d154abd06eb54
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch/finch-a6b05e51c46366a54466c2009f5fdde74e0fa40bbcc6568601a4e3342dd16937.yml
+openapi_spec_hash: 084797c220144df17d98eb984dd4cba2
 config_hash: 9ae56f40cec7304896138bfad5caf748

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.2.0 (2026-07-13)
+
+Full Changelog: [v2.1.0...v2.2.0](https://github.com/Finch-API/finch-api-python/compare/v2.1.0...v2.2.0)
+
+### Features
+
+* **api:** api update ([2e8eab2](https://github.com/Finch-API/finch-api-python/commit/2e8eab2ee284482e6ed1070156bb378570cbc194))
+
 ## 2.1.0 (2026-07-01)
 
 Full Changelog: [v2.0.0...v2.1.0](https://github.com/Finch-API/finch-api-python/compare/v2.0.0...v2.1.0)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "finch-api"
-version = "2.1.0"
+version = "2.2.0"
 description = "The official Python library for the Finch API"
 dynamic = ["readme"]
 license = "Apache-2.0"

src/finch/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "finch"
-__version__ = "2.1.0"  # x-release-please-version
+__version__ = "2.2.0"  # x-release-please-version

src/finch/resources/hris/directory.py

@@ -59,7 +59,7 @@ def list(
         Args:
           entity_ids: The entity IDs to specify which entities' data to access.
 
-          limit: Number of employees to return (defaults to all)
+          limit: Number of employees to return (defaults to 100, maximum 10000)
 
           offset: Index to start from (defaults to 0)
 
@@ -112,7 +112,7 @@ def list_individuals(
         Args:
           entity_ids: The entity IDs to specify which entities' data to access.
 
-          limit: Number of employees to return (defaults to all)
+          limit: Number of employees to return (defaults to 100, maximum 10000)
 
           offset: Index to start from (defaults to 0)
 
@@ -174,7 +174,7 @@ def list(
         Args:
           entity_ids: The entity IDs to specify which entities' data to access.
 
-          limit: Number of employees to return (defaults to all)
+          limit: Number of employees to return (defaults to 100, maximum 10000)
 
           offset: Index to start from (defaults to 0)
 
@@ -227,7 +227,7 @@ def list_individuals(
         Args:
           entity_ids: The entity IDs to specify which entities' data to access.
 
-          limit: Number of employees to return (defaults to all)
+          limit: Number of employees to return (defaults to 100, maximum 10000)
 
           offset: Index to start from (defaults to 0)
 

src/finch/resources/hris/employments.py

@@ -56,7 +56,7 @@ def retrieve_many(
         Read individual employment and income data
 
         Args:
-          requests: The array of batch requests.
+          requests: The array of batch requests. Maximum 10000 items per request.
 
           entity_ids: The entity IDs to specify which entities' data to access.
 
@@ -123,7 +123,7 @@ def retrieve_many(
         Read individual employment and income data
 
         Args:
-          requests: The array of batch requests.
+          requests: The array of batch requests. Maximum 10000 items per request.
 
           entity_ids: The entity IDs to specify which entities' data to access.
 

src/finch/resources/hris/individuals.py

@@ -43,9 +43,9 @@ def with_streaming_response(self) -> IndividualsWithStreamingResponse:
     def retrieve_many(
         self,
         *,
+        requests: Iterable[individual_retrieve_many_params.Request],
         entity_ids: SequenceNotStr[str] | Omit = omit,
         options: Optional[individual_retrieve_many_params.Options] | Omit = omit,
-        requests: Iterable[individual_retrieve_many_params.Request] | 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,
@@ -57,6 +57,8 @@ def retrieve_many(
         Read individual data, excluding income and employment data
 
         Args:
+          requests: The array of batch requests. Maximum 10000 items per request.
+
           entity_ids: The entity IDs to specify which entities' data to access.
 
           extra_headers: Send extra headers
@@ -72,8 +74,8 @@ def retrieve_many(
             page=SyncResponsesPage[IndividualResponse],
             body=maybe_transform(
                 {
-                    "options": options,
                     "requests": requests,
+                    "options": options,
                 },
                 individual_retrieve_many_params.IndividualRetrieveManyParams,
             ),
@@ -115,9 +117,9 @@ def with_streaming_response(self) -> AsyncIndividualsWithStreamingResponse:
     def retrieve_many(
         self,
         *,
+        requests: Iterable[individual_retrieve_many_params.Request],
         entity_ids: SequenceNotStr[str] | Omit = omit,
         options: Optional[individual_retrieve_many_params.Options] | Omit = omit,
-        requests: Iterable[individual_retrieve_many_params.Request] | 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,
@@ -129,6 +131,8 @@ def retrieve_many(
         Read individual data, excluding income and employment data
 
         Args:
+          requests: The array of batch requests. Maximum 10000 items per request.
+
           entity_ids: The entity IDs to specify which entities' data to access.
 
           extra_headers: Send extra headers
@@ -144,8 +148,8 @@ def retrieve_many(
             page=AsyncResponsesPage[IndividualResponse],
             body=maybe_transform(
                 {
-                    "options": options,
                     "requests": requests,
+                    "options": options,
                 },
                 individual_retrieve_many_params.IndividualRetrieveManyParams,
             ),

src/finch/resources/hris/pay_statements.py

@@ -59,7 +59,7 @@ def retrieve_many(
         supports Benefits.
 
         Args:
-          requests: The array of batch requests.
+          requests: The array of batch requests. Maximum 10 payment_ids per request.
 
           entity_ids: The entity IDs to specify which entities' data to access.
 
@@ -131,7 +131,7 @@ def retrieve_many(
         supports Benefits.
 
         Args:
-          requests: The array of batch requests.
+          requests: The array of batch requests. Maximum 10 payment_ids per request.
 
           entity_ids: The entity IDs to specify which entities' data to access.
 

src/finch/types/hris/directory_list_individuals_params.py

@@ -14,7 +14,7 @@ class DirectoryListIndividualsParams(TypedDict, total=False):
     """The entity IDs to specify which entities' data to access."""
 
     limit: int
-    """Number of employees to return (defaults to all)"""
+    """Number of employees to return (defaults to 100, maximum 10000)"""
 
     offset: int
     """Index to start from (defaults to 0)"""

src/finch/types/hris/directory_list_params.py

@@ -14,7 +14,7 @@ class DirectoryListParams(TypedDict, total=False):
     """The entity IDs to specify which entities' data to access."""
 
     limit: int
-    """Number of employees to return (defaults to all)"""
+    """Number of employees to return (defaults to 100, maximum 10000)"""
 
     offset: int
     """Index to start from (defaults to 0)"""

src/finch/types/hris/employment_retrieve_many_params.py

@@ -12,17 +12,12 @@
 
 class EmploymentRetrieveManyParams(TypedDict, total=False):
     requests: Required[Iterable[Request]]
-    """The array of batch requests."""
+    """The array of batch requests. Maximum 10000 items per request."""
 
     entity_ids: SequenceNotStr[str]
     """The entity IDs to specify which entities' data to access."""
 
 
 class Request(TypedDict, total=False):
     individual_id: Required[str]
-    """A stable Finch `id` (UUID v4) for an individual in the company.
-
-    There is no limit to the number of `individual_id` to send per request. It is
-    preferantial to send all ids in a single request for Finch to optimize provider
-    rate-limits.
-    """
+    """A stable Finch `id` (UUID v4) for an individual in the company."""

src/finch/types/hris/individual_retrieve_many_params.py

@@ -3,25 +3,26 @@
 from __future__ import annotations
 
 from typing import Iterable, Optional
-from typing_extensions import TypedDict
+from typing_extensions import Required, TypedDict
 
 from ..._types import SequenceNotStr
 
-__all__ = ["IndividualRetrieveManyParams", "Options", "Request"]
+__all__ = ["IndividualRetrieveManyParams", "Request", "Options"]
 
 
 class IndividualRetrieveManyParams(TypedDict, total=False):
+    requests: Required[Iterable[Request]]
+    """The array of batch requests. Maximum 10000 items per request."""
+
     entity_ids: SequenceNotStr[str]
     """The entity IDs to specify which entities' data to access."""
 
     options: Optional[Options]
 
-    requests: Iterable[Request]
+
+class Request(TypedDict, total=False):
+    individual_id: Required[str]
 
 
 class Options(TypedDict, total=False):
     include: SequenceNotStr[str]
-
-
-class Request(TypedDict, total=False):
-    individual_id: str

src/finch/types/hris/pay_statement_retrieve_many_params.py

@@ -12,7 +12,7 @@
 
 class PayStatementRetrieveManyParams(TypedDict, total=False):
     requests: Required[Iterable[Request]]
-    """The array of batch requests."""
+    """The array of batch requests. Maximum 10 payment_ids per request."""
 
     entity_ids: SequenceNotStr[str]
     """The entity IDs to specify which entities' data to access."""
@@ -23,7 +23,7 @@ class Request(TypedDict, total=False):
     """A stable Finch `id` (UUID v4) for a payment."""
 
     limit: int
-    """Number of pay statements to return (defaults to all)."""
+    """Number of pay statements to return (defaults to 100, maximum 5000)."""
 
     offset: int
     """Index to start from."""

tests/api_resources/hris/test_directory.py

@@ -29,7 +29,7 @@ def test_method_list(self, client: Finch) -> None:
     def test_method_list_with_all_params(self, client: Finch) -> None:
         directory = client.hris.directory.list(
             entity_ids=["550e8400-e29b-41d4-a716-446655440000"],
-            limit=0,
+            limit=10000,
             offset=0,
         )
         assert_matches_type(SyncIndividualsPage[IndividualInDirectory], directory, path=["response"])
@@ -66,7 +66,7 @@ def test_method_list_individuals_with_all_params(self, client: Finch) -> None:
         with pytest.warns(DeprecationWarning):
             directory = client.hris.directory.list_individuals(
                 entity_ids=["550e8400-e29b-41d4-a716-446655440000"],
-                limit=0,
+                limit=10000,
                 offset=0,
             )
 
@@ -109,7 +109,7 @@ async def test_method_list(self, async_client: AsyncFinch) -> None:
     async def test_method_list_with_all_params(self, async_client: AsyncFinch) -> None:
         directory = await async_client.hris.directory.list(
             entity_ids=["550e8400-e29b-41d4-a716-446655440000"],
-            limit=0,
+            limit=10000,
             offset=0,
         )
         assert_matches_type(AsyncIndividualsPage[IndividualInDirectory], directory, path=["response"])
@@ -146,7 +146,7 @@ async def test_method_list_individuals_with_all_params(self, async_client: Async
         with pytest.warns(DeprecationWarning):
             directory = await async_client.hris.directory.list_individuals(
                 entity_ids=["550e8400-e29b-41d4-a716-446655440000"],
-                limit=0,
+                limit=10000,
                 offset=0,
             )
 

tests/api_resources/hris/test_individuals.py

@@ -20,21 +20,25 @@ class TestIndividuals:
 
     @parametrize
     def test_method_retrieve_many(self, client: Finch) -> None:
-        individual = client.hris.individuals.retrieve_many()
+        individual = client.hris.individuals.retrieve_many(
+            requests=[{"individual_id": "individual_id"}],
+        )
         assert_matches_type(SyncResponsesPage[IndividualResponse], individual, path=["response"])
 
     @parametrize
     def test_method_retrieve_many_with_all_params(self, client: Finch) -> None:
         individual = client.hris.individuals.retrieve_many(
+            requests=[{"individual_id": "individual_id"}],
             entity_ids=["550e8400-e29b-41d4-a716-446655440000"],
             options={"include": ["string"]},
-            requests=[{"individual_id": "individual_id"}],
         )
         assert_matches_type(SyncResponsesPage[IndividualResponse], individual, path=["response"])
 
     @parametrize
     def test_raw_response_retrieve_many(self, client: Finch) -> None:
-        response = client.hris.individuals.with_raw_response.retrieve_many()
+        response = client.hris.individuals.with_raw_response.retrieve_many(
+            requests=[{"individual_id": "individual_id"}],
+        )
 
         assert response.is_closed is True
         assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -43,7 +47,9 @@ def test_raw_response_retrieve_many(self, client: Finch) -> None:
 
     @parametrize
     def test_streaming_response_retrieve_many(self, client: Finch) -> None:
-        with client.hris.individuals.with_streaming_response.retrieve_many() as response:
+        with client.hris.individuals.with_streaming_response.retrieve_many(
+            requests=[{"individual_id": "individual_id"}],
+        ) as response:
             assert not response.is_closed
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
 
@@ -60,21 +66,25 @@ class TestAsyncIndividuals:
 
     @parametrize
     async def test_method_retrieve_many(self, async_client: AsyncFinch) -> None:
-        individual = await async_client.hris.individuals.retrieve_many()
+        individual = await async_client.hris.individuals.retrieve_many(
+            requests=[{"individual_id": "individual_id"}],
+        )
         assert_matches_type(AsyncResponsesPage[IndividualResponse], individual, path=["response"])
 
     @parametrize
     async def test_method_retrieve_many_with_all_params(self, async_client: AsyncFinch) -> None:
         individual = await async_client.hris.individuals.retrieve_many(
+            requests=[{"individual_id": "individual_id"}],
             entity_ids=["550e8400-e29b-41d4-a716-446655440000"],
             options={"include": ["string"]},
-            requests=[{"individual_id": "individual_id"}],
         )
         assert_matches_type(AsyncResponsesPage[IndividualResponse], individual, path=["response"])
 
     @parametrize
     async def test_raw_response_retrieve_many(self, async_client: AsyncFinch) -> None:
-        response = await async_client.hris.individuals.with_raw_response.retrieve_many()
+        response = await async_client.hris.individuals.with_raw_response.retrieve_many(
+            requests=[{"individual_id": "individual_id"}],
+        )
 
         assert response.is_closed is True
         assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -83,7 +93,9 @@ async def test_raw_response_retrieve_many(self, async_client: AsyncFinch) -> Non
 
     @parametrize
     async def test_streaming_response_retrieve_many(self, async_client: AsyncFinch) -> None:
-        async with async_client.hris.individuals.with_streaming_response.retrieve_many() as response:
+        async with async_client.hris.individuals.with_streaming_response.retrieve_many(
+            requests=[{"individual_id": "individual_id"}],
+        ) as response:
             assert not response.is_closed
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"