feat(api): api update

.stats.yml

@@ -1,3 +1,3 @@
 configured_endpoints: 238
-openapi_spec_hash: ed21325b0e3f886a49c45d2decc4f5d0
+openapi_spec_hash: 9a970d9f5d1fe0aba1b390f682db71c3
 config_hash: 2ae0d8aaecf01b38cbf9f9e112822c23

pyproject.toml

@@ -90,18 +90,14 @@ include = [
 packages = ["src/increase"]
 
 [tool.hatch.build.targets.sdist]
-# Basically everything except hidden files/directories (such as .github, .devcontainers, .python-version, etc)
+# Runtime package (src/) plus top-level metadata only.
+# Dev files (tests/, examples/, tooling) stay out of the published sdist.
 include = [
   "/*.toml",
   "/*.json",
   "/*.lock",
   "/*.md",
-  "/mypy.ini",
-  "/noxfile.py",
-  "bin/*",
-  "examples/*",
   "src/*",
-  "tests/*",
 ]
 
 [tool.hatch.metadata.hooks.fancy-pypi-readme]

src/increase/resources/accounts.py

@@ -83,8 +83,9 @@ def create(
 
           loan: The loan details for the account.
 
-          program_id: The identifier for the Program that this Account falls under. Required if you
-              operate more than one Program.
+          program_id: The identifier for the Program that this Account falls under. Required if your
+              Group operates more than one Program. List your [Programs](#programs) to find
+              their identifiers.
 
           extra_headers: Send extra headers
 
@@ -423,8 +424,9 @@ async def create(
 
           loan: The loan details for the account.
 
-          program_id: The identifier for the Program that this Account falls under. Required if you
-              operate more than one Program.
+          program_id: The identifier for the Program that this Account falls under. Required if your
+              Group operates more than one Program. List your [Programs](#programs) to find
+              their identifiers.
 
           extra_headers: Send extra headers
 

src/increase/resources/ach_transfers.py

@@ -149,7 +149,8 @@ def create(
 
           standard_entry_class_code: The
               [Standard Entry Class (SEC) code](/documentation/ach-standard-entry-class-codes)
-              to use for the transfer.
+              to use for the transfer. If not provided, the default is
+              `corporate_credit_or_debit`.
 
               - `corporate_credit_or_debit` - Corporate Credit and Debit (CCD) is used for
                 business-to-business payments.
@@ -527,7 +528,8 @@ async def create(
 
           standard_entry_class_code: The
               [Standard Entry Class (SEC) code](/documentation/ach-standard-entry-class-codes)
-              to use for the transfer.
+              to use for the transfer. If not provided, the default is
+              `corporate_credit_or_debit`.
 
               - `corporate_credit_or_debit` - Corporate Credit and Debit (CCD) is used for
                 business-to-business payments.

src/increase/resources/inbound_mail_items.py

@@ -153,7 +153,9 @@ def action(
         idempotency_key: str | None = None,
     ) -> InboundMailItem:
         """
-        Action an Inbound Mail Item
+        Deposits or ignores each check contained in a pending Inbound Mail Item.
+        Depositing a check creates a [Check Deposit](#check-deposits) into the Account
+        you specify.
 
         Args:
           inbound_mail_item_id: The identifier of the Inbound Mail Item to action.
@@ -319,7 +321,9 @@ async def action(
         idempotency_key: str | None = None,
     ) -> InboundMailItem:
         """
-        Action an Inbound Mail Item
+        Deposits or ignores each check contained in a pending Inbound Mail Item.
+        Depositing a check creates a [Check Deposit](#check-deposits) into the Account
+        you specify.
 
         Args:
           inbound_mail_item_id: The identifier of the Inbound Mail Item to action.

src/increase/resources/lockbox_addresses.py

@@ -56,8 +56,12 @@ def create(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
         idempotency_key: str | None = None,
     ) -> LockboxAddress:
-        """
-        Create a Lockbox Address
+        """The Lockbox Address starts with a `pending` status and a null `address`.
+
+        Shortly
+        after creation, Increase generates the mailing address and the status becomes
+        `active`. You can only create Lockbox Recipients for an `active` Lockbox
+        Address.
 
         Args:
           description: The description you choose for the Lockbox Address.
@@ -271,8 +275,12 @@ async def create(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
         idempotency_key: str | None = None,
     ) -> LockboxAddress:
-        """
-        Create a Lockbox Address
+        """The Lockbox Address starts with a `pending` status and a null `address`.
+
+        Shortly
+        after creation, Increase generates the mailing address and the status becomes
+        `active`. You can only create Lockbox Recipients for an `active` Lockbox
+        Address.
 
         Args:
           description: The description you choose for the Lockbox Address.

src/increase/resources/lockbox_recipients.py

@@ -65,7 +65,8 @@ def create(
         Args:
           account_id: The Account that checks sent to this Lockbox Recipient should be deposited into.
 
-          lockbox_address_id: The Lockbox Address where this Lockbox Recipient may receive mail.
+          lockbox_address_id: The Lockbox Address where this Lockbox Recipient may receive mail. The Lockbox
+              Address must have a `status` of `active`.
 
           description: The description you choose for the Lockbox Recipient.
 
@@ -313,7 +314,8 @@ async def create(
         Args:
           account_id: The Account that checks sent to this Lockbox Recipient should be deposited into.
 
-          lockbox_address_id: The Lockbox Address where this Lockbox Recipient may receive mail.
+          lockbox_address_id: The Lockbox Address where this Lockbox Recipient may receive mail. The Lockbox
+              Address must have a `status` of `active`.
 
           description: The description you choose for the Lockbox Recipient.
 

src/increase/resources/simulations/card_authorizations.py

@@ -102,7 +102,10 @@ def create(
         `card_authorization` or a [Declined Transaction](#declined-transactions) of type
         `card_decline`. You can pass either a Card id or a
         [Digital Wallet Token](#digital-wallet-tokens) id to simulate the two different
-        ways purchases can be made.
+        ways purchases can be made. The response will contain either a
+        `pending_transaction` or a `declined_transaction`; the other attribute will be
+        null. If the authorization is declined, the reason is available on the Declined
+        Transaction at `source.card_decline.reason`.
 
         Args:
           amount: The authorization amount in cents.
@@ -306,7 +309,10 @@ async def create(
         `card_authorization` or a [Declined Transaction](#declined-transactions) of type
         `card_decline`. You can pass either a Card id or a
         [Digital Wallet Token](#digital-wallet-tokens) id to simulate the two different
-        ways purchases can be made.
+        ways purchases can be made. The response will contain either a
+        `pending_transaction` or a `declined_transaction`; the other attribute will be
+        null. If the authorization is declined, the reason is available on the Declined
+        Transaction at `source.card_decline.reason`.
 
         Args:
           amount: The authorization amount in cents.

src/increase/resources/simulations/inbound_ach_transfers.py

@@ -116,7 +116,8 @@ def create(
 
           company_id: The sender's company ID.
 
-          company_name: The name of the sender.
+          company_name: The name of the sender. This corresponds to the `originator_company_name` field
+              on the resulting Inbound ACH Transfer.
 
           receiver_id_number: The ID of the receiver of the transfer.
 
@@ -275,7 +276,8 @@ async def create(
 
           company_id: The sender's company ID.
 
-          company_name: The name of the sender.
+          company_name: The name of the sender. This corresponds to the `originator_company_name` field
+              on the resulting Inbound ACH Transfer.
 
           receiver_id_number: The ID of the receiver of the transfer.
 

src/increase/resources/simulations/inbound_mail_items.py

@@ -58,17 +58,22 @@ def create(
     ) -> InboundMailItem:
         """
         Simulates an Inbound Mail Item to one of your Lockbox Addresses or Lockbox
-        Recipients, as if someone had mailed a physical check.
+        Recipients, as if someone had mailed a physical check. Increase automatically
+        deposits a check mailed to a Lockbox Recipient into the recipient's Account. A
+        check mailed to a Lockbox Address must be deposited or ignored with the
+        [Action an Inbound Mail Item](#inbound-mail-items) endpoint.
 
         Args:
           amount: The amount of the check to be simulated, in cents.
 
           contents_file_id: The file containing the PDF contents. If not present, a default check image file
               will be used.
 
-          lockbox_address_id: The identifier of the Lockbox Address to simulate inbound mail to.
+          lockbox_address_id: The identifier of the Lockbox Address to simulate inbound mail to. Exactly one
+              lockbox identifier parameter must be provided.
 
-          lockbox_recipient_id: The identifier of the Lockbox Recipient to simulate inbound mail to.
+          lockbox_recipient_id: The identifier of the Lockbox Recipient to simulate inbound mail to. Exactly one
+              lockbox identifier parameter must be provided.
 
           extra_headers: Send extra headers
 
@@ -139,17 +144,22 @@ async def create(
     ) -> InboundMailItem:
         """
         Simulates an Inbound Mail Item to one of your Lockbox Addresses or Lockbox
-        Recipients, as if someone had mailed a physical check.
+        Recipients, as if someone had mailed a physical check. Increase automatically
+        deposits a check mailed to a Lockbox Recipient into the recipient's Account. A
+        check mailed to a Lockbox Address must be deposited or ignored with the
+        [Action an Inbound Mail Item](#inbound-mail-items) endpoint.
 
         Args:
           amount: The amount of the check to be simulated, in cents.
 
           contents_file_id: The file containing the PDF contents. If not present, a default check image file
               will be used.
 
-          lockbox_address_id: The identifier of the Lockbox Address to simulate inbound mail to.
+          lockbox_address_id: The identifier of the Lockbox Address to simulate inbound mail to. Exactly one
+              lockbox identifier parameter must be provided.
 
-          lockbox_recipient_id: The identifier of the Lockbox Recipient to simulate inbound mail to.
+          lockbox_recipient_id: The identifier of the Lockbox Recipient to simulate inbound mail to. Exactly one
+              lockbox identifier parameter must be provided.
 
           extra_headers: Send extra headers
 

src/increase/types/account_create_params.py

@@ -38,7 +38,8 @@ class AccountCreateParams(TypedDict, total=False):
     program_id: str
     """The identifier for the Program that this Account falls under.
 
-    Required if you operate more than one Program.
+    Required if your Group operates more than one Program. List your
+    [Programs](#programs) to find their identifiers.
     """
 
 

src/increase/types/ach_transfer.py

@@ -633,7 +633,11 @@ class Return(BaseModel):
     """The identifier of the Transaction associated with this return."""
 
     transfer_id: str
-    """The identifier of the ACH Transfer associated with this return."""
+    """The identifier of the ACH Transfer associated with this return.
+
+    This matches the original Transaction's
+    `source.ach_transfer_intention.transfer_id`.
+    """
 
     if TYPE_CHECKING:
         # Some versions of Pydantic <2.8.0 have a bug and don’t allow assigning a
@@ -923,7 +927,9 @@ class ACHTransfer(BaseModel):
     - `requires_attention` - The transfer requires attention from an Increase
       operator.
     - `rejected` - The transfer has been rejected.
-    - `submitted` - The transfer is complete.
+    - `submitted` - The transfer has been submitted to the Federal Reserve. When the
+      transfer settles, the status remains `submitted` and the `settlement`
+      sub-object is populated.
     - `returned` - The transfer has been returned.
     """
 

src/increase/types/ach_transfer_create_params.py

@@ -137,7 +137,8 @@ class ACHTransferCreateParams(TypedDict, total=False):
     """
     The
     [Standard Entry Class (SEC) code](/documentation/ach-standard-entry-class-codes)
-    to use for the transfer.
+    to use for the transfer. If not provided, the default is
+    `corporate_credit_or_debit`.
 
     - `corporate_credit_or_debit` - Corporate Credit and Debit (CCD) is used for
       business-to-business payments.

src/increase/types/beneficial_owner_create_params.py

@@ -158,7 +158,8 @@ class IndividualIdentification(TypedDict, total=False, extra_items=object):  # t
     An identification number that can be used to verify the individual's identity,
     such as a social security number. For Social Security Numbers and Individual
     Taxpayer Identification Numbers, submit nine digits with no dashes or other
-    separators.
+    separators. When testing in sandbox, use one of our
+    [sandbox test values](https://increase.com/documentation/sandbox-test-values).
     """
 
     drivers_license: IndividualIdentificationDriversLicense

src/increase/types/beneficial_owner_update_params.py

@@ -169,7 +169,8 @@ class Identification(TypedDict, total=False, extra_items=object):  # type: ignor
     An identification number that can be used to verify the individual's identity,
     such as a social security number. For Social Security Numbers and Individual
     Taxpayer Identification Numbers, submit nine digits with no dashes or other
-    separators.
+    separators. When testing in sandbox, use one of our
+    [sandbox test values](https://increase.com/documentation/sandbox-test-values).
     """
 
     drivers_license: IdentificationDriversLicense

src/increase/types/card_push_transfer.py

@@ -880,9 +880,9 @@ class CardPushTransfer(BaseModel):
     status: Literal[
         "pending_approval",
         "canceled",
+        "pending_submission",
         "pending_reviewing",
         "requires_attention",
-        "pending_submission",
         "submitted",
         "complete",
         "declined",
@@ -891,11 +891,11 @@ class CardPushTransfer(BaseModel):
 
     - `pending_approval` - The transfer is pending approval.
     - `canceled` - The transfer has been canceled.
+    - `pending_submission` - The transfer is queued to be submitted to the card
+      network.
     - `pending_reviewing` - The transfer is pending review by Increase.
     - `requires_attention` - The transfer requires attention from an Increase
       operator.
-    - `pending_submission` - The transfer is queued to be submitted to the card
-      network.
     - `submitted` - The transfer has been submitted and is pending a response from
       the card network.
     - `complete` - The transfer has been sent successfully and is complete.

src/increase/types/card_push_transfer_list_params.py

@@ -70,9 +70,9 @@ class CreatedAt(TypedDict, total=False):
             Literal[
                 "pending_approval",
                 "canceled",
+                "pending_submission",
                 "pending_reviewing",
                 "requires_attention",
-                "pending_submission",
                 "submitted",
                 "complete",
                 "declined",